Connections
- Connections
Understanding Connections
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 Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice API.
- Reuse the connection of a database form which is currently open in the GUI.
With the above possibilities, a com.sun.star.sdb.Connection is made or at least a com.sun.star.sdbc.Connection:
The service com.sun.star.sdb.Connection has three main functions: communication, data definition and operation on the Apache OpenOffice 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 Apache OpenOffice 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.
Communication
The main interface of com.sun.star.sdbc.Connection is com.sun.star.sdbc.XConnection. Its methods control almost every aspect of communication with a database management system:
// 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.
Data Definition
The interfaces of com.sun.star.sdbcx.DatabaseDefinition are explained in the section Using SDBCX to Access the Database Design.
Operation on Application Level
Handling of query definitions through com.sun.star.sdb.XQueriesSupplier and com.sun.star.sdb.XSQLQueryComposerFactory is discussed in the section Queries .
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 TABLE
or QUERY
, pass a table name or query name that exists in the com.sun.star.sdb.DataSource of the connection. The value COMMAND
makes 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.
The interface com.sun.star.container.XChild accesses the parent com.sun.star.sdb.DataSource of the connection, if available.
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). |