A connection is an open communication channel to a database. A connection is required to work with data in a database or with a database definition. Connections are encapsulated in Connection objects in the OpenOffice.org API. There are several possibilities to get a Connection:
- Connect to a data source that has already been set up in the database context of OpenOffice.org API.
- Use the driver manager or a specific driver to connect to a database without using an existing data source from the database context.
- Get a connection from the connection pool maintained by OpenOffice.org API.
- Reuse the connection of a database form which is currently open in the GUI.
The service com.sun.star.sdb.Connection has three main functions: communication, data definition and operation on the OpenOffice.org API application level. The service:
- Handles the communication with a database including statement execution, transactions, database metadata and warnings through the simple connection service of the SDBC layer com.sun.star.sdbc.Connection.
- Handles database definition tasks, primarily table definitions, through the service com.sun.star.sdbcx.DatabaseDefinition. Optionally, it manages views, users and groups.
- Organizes query definitions on the application level and provides a method to open queries and tables defined in OpenOffice.org API. Query definitions are organized by the interfaces com.sun.star.sdb.XQueriesSupplier and com.sun.star.sdb.XSQLQueryComposerFactory. Queries and tables can be opened using com.sun.star.sdb.XCommandPreparation. In case the underlying data source is needed, com.sun.star.container.XChild provides the parent data source. This is useful when using an existing connection, for instance, of a database form, to act upon its data source.
Connections are central to all database activities. The connection interfaces are discussed later.
// general connection control void close() boolean isClosed() void setReadOnly( [in] boolean readOnly) boolean isReadOnly() // commands and statements // - generic SQL statement // - prepared statement // - stored procedure call com::sun::star::sdbc::XStatement createStatement() com::sun::star::sdbc::XPreparedStatement prepareStatement( [in] string sql) com::sun::star::sdbc::XPreparedStatement prepareCall( [in] string sql) string nativeSQL( [in] string sql) // transactions void setTransactionIsolation( [in] long level) long getTransactionIsolation() void setAutoCommit( [in] boolean autoCommit) boolean getAutoCommit() void commit() void rollback() // database metadata com::sun::star::sdbc::XDatabaseMetaData getMetaData() // data type mapping (driver dependent) com::sun::star::container::XNameAccess getTypeMap() void setTypeMap( [in] com::sun::star::container::XNameAccess typeMap) // catalog (subspace in a database) void setCatalog( [in] string catalog) string getCatalog()
The use of commands and statements are explained in the sections Manipulating Data and Using DDL to Change the Database Design. Transactions are discussed in Using DBMS Features. Database metadata are covered in Retrieving Information about a Database.
The com.sun.star.sdbc.XWarningsSupplier is a simple interface to handle SQL warnings:
any getWarnings() void clearWarnings()
The exception com.sun.star.sdbc.SQLWarning is usually not thrown, rather it is transported silently to objects supporting com.sun.star.sdbc.XWarningsSupplier. Refer to the API reference for more information about SQL warnings.
Operation on Application Level
Through com.sun.star.sdb.XCommandPreparation get the necessary statement objects to open predefined queries and tables in a data source, and execute arbitrary SQL statements.
com::sun::star::sdbc::XPreparedStatement prepareCommand( [in] string command, [in] long commandType)
If the value of the parameter com.sun.star.sdb.CommandType is
QUERY, pass a table name or query name that exists in the com.sun.star.sdb.DataSource of the connection. The value
prepareCommand() expect an SQL string. The result is a prepared statement object that can be parameterized and executed. For details and an example, refer to section PreparedStatement From DataSource Queries.
com::sun::star::uno::XInterface getParent() void setParent( [in] com::sun::star::uno::XInterface Parent)
|Content on this page is licensed under the Public Documentation License (PDL).|