Difference between revisions of "Documentation/DevGuide/Database/Connections"
From Apache OpenOffice Wiki
< Documentation | DevGuide
OOoWikiBot (Talk | contribs) m (FINAL VERSION FOR L10N) |
|||
| Line 12: | Line 12: | ||
<!--<idltopic>com.sun.star.sdb.Connection</idltopic>--> | <!--<idltopic>com.sun.star.sdb.Connection</idltopic>--> | ||
| − | 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 {{ | + | 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 {{AOo}} 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 {{ | + | * Connect to a data source that has already been set up in the database context of {{AOo}} API. |
* Use the driver manager or a specific driver to connect to a database without using an existing data source from the database context. | * 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 {{ | + | * Get a connection from the connection pool maintained by {{AOo}} API. |
* Reuse the connection of a database form which is currently open in the GUI. | * Reuse the connection of a database form which is currently open in the GUI. | ||
| Line 23: | Line 23: | ||
[[Image:Sdb_Connection.png|none|thumb|400px|<idl>com.sun.star.sdb.Connection</idl>]] | [[Image:Sdb_Connection.png|none|thumb|400px|<idl>com.sun.star.sdb.Connection</idl>]] | ||
| − | The service <idl>com.sun.star.sdb.Connection</idl> has three main functions: communication, data definition and operation on the {{ | + | The service <idl>com.sun.star.sdb.Connection</idl> has three main functions: communication, data definition and operation on the {{AOo}} 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 <idl>com.sun.star.sdbc.Connection</idl>. | * Handles the communication with a database including statement execution, transactions, database metadata and warnings through the simple connection service of the SDBC layer <idl>com.sun.star.sdbc.Connection</idl>. | ||
* Handles database definition tasks, primarily table definitions, through the service <idl>com.sun.star.sdbcx.DatabaseDefinition</idl>. Optionally, it manages views, users and groups. | * Handles database definition tasks, primarily table definitions, through the service <idl>com.sun.star.sdbcx.DatabaseDefinition</idl>. 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 {{ | + | * Organizes query definitions on the application level and provides a method to open queries and tables defined in {{AOo}} API. Query definitions are organized by the interfaces <idl>com.sun.star.sdb.XQueriesSupplier</idl> and <idl>com.sun.star.sdb.XSQLQueryComposerFactory</idl>. Queries and tables can be opened using <idl>com.sun.star.sdb.XCommandPreparation</idl>. In case the underlying data source is needed, <idl>com.sun.star.container.XChild</idl> 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. | Connections are central to all database activities. The connection interfaces are discussed later. | ||
| Line 33: | Line 33: | ||
The main interface of <idl>com.sun.star.sdbc.Connection</idl> is <idl>com.sun.star.sdbc.XConnection</idl>. Its methods control almost every aspect of communication with a database management system: | The main interface of <idl>com.sun.star.sdbc.Connection</idl> is <idl>com.sun.star.sdbc.XConnection</idl>. Its methods control almost every aspect of communication with a database management system: | ||
| − | + | <syntaxhighlight lang="idl"> | |
// general connection control | // general connection control | ||
void close() | void close() | ||
| Line 67: | Line 67: | ||
void setCatalog( [in] string catalog) | void setCatalog( [in] string catalog) | ||
string getCatalog() | string getCatalog() | ||
| − | + | </syntaxhighlight> | |
The use of commands and statements are explained in the sections [[Documentation/DevGuide/Database/Manipulating the Data|Manipulating Data]] and [[Documentation/DevGuide/Database/Using DDL to Change the Database Design|Using DDL to Change the Database Design]]. Transactions are discussed in [[Documentation/DevGuide/Database/Using DBMS Features|Using DBMS Features]]. Database metadata are covered in [[Documentation/DevGuide/Database/Database Design#Retrieving Information about a Database|Retrieving Information about a Database]]. | The use of commands and statements are explained in the sections [[Documentation/DevGuide/Database/Manipulating the Data|Manipulating Data]] and [[Documentation/DevGuide/Database/Using DDL to Change the Database Design|Using DDL to Change the Database Design]]. Transactions are discussed in [[Documentation/DevGuide/Database/Using DBMS Features|Using DBMS Features]]. Database metadata are covered in [[Documentation/DevGuide/Database/Database Design#Retrieving Information about a Database|Retrieving Information about a Database]]. | ||
The <idl>com.sun.star.sdbc.XWarningsSupplier</idl> is a simple interface to handle SQL warnings: | The <idl>com.sun.star.sdbc.XWarningsSupplier</idl> is a simple interface to handle SQL warnings: | ||
| − | + | <syntaxhighlight lang="idl"> | |
any getWarnings() | any getWarnings() | ||
void clearWarnings() | void clearWarnings() | ||
| − | + | </syntaxhighlight> | |
The exception <idl>com.sun.star.sdbc.SQLWarning</idl> is usually not thrown, rather it is transported silently to objects supporting <idl>com.sun.star.sdbc.XWarningsSupplier</idl>. Refer to the API reference for more information about SQL warnings. | The exception <idl>com.sun.star.sdbc.SQLWarning</idl> is usually not thrown, rather it is transported silently to objects supporting <idl>com.sun.star.sdbc.XWarningsSupplier</idl>. Refer to the API reference for more information about SQL warnings. | ||
| Line 87: | Line 87: | ||
Through <idl>com.sun.star.sdb.XCommandPreparation</idl> get the necessary statement objects to open predefined queries and tables in a data source, and execute arbitrary SQL statements. | Through <idl>com.sun.star.sdb.XCommandPreparation</idl> get the necessary statement objects to open predefined queries and tables in a data source, and execute arbitrary SQL statements. | ||
| − | + | <syntaxhighlight lang="idl"> | |
com::sun::star::sdbc::XPreparedStatement prepareCommand( [in] string command, [in] long commandType) | com::sun::star::sdbc::XPreparedStatement prepareCommand( [in] string command, [in] long commandType) | ||
| − | + | </syntaxhighlight> | |
If the value of the parameter <idl>com.sun.star.sdb.CommandType</idl> is <code>TABLE</code> or <code>QUERY</code>, pass a table name or query name that exists in the <idl>com.sun.star.sdb.DataSource</idl> of the connection. The value <code>COMMAND</code> makes <code>prepareCommand()</code> 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 [[Documentation/DevGuide/Database/PreparedStatement From DataSource Queries|PreparedStatement From DataSource Queries]]. | If the value of the parameter <idl>com.sun.star.sdb.CommandType</idl> is <code>TABLE</code> or <code>QUERY</code>, pass a table name or query name that exists in the <idl>com.sun.star.sdb.DataSource</idl> of the connection. The value <code>COMMAND</code> makes <code>prepareCommand()</code> 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 [[Documentation/DevGuide/Database/PreparedStatement From DataSource Queries|PreparedStatement From DataSource Queries]]. | ||
The interface <idl>com.sun.star.container.XChild</idl> accesses the parent <idl>com.sun.star.sdb.DataSource</idl> of the connection, if available. | The interface <idl>com.sun.star.container.XChild</idl> accesses the parent <idl>com.sun.star.sdb.DataSource</idl> of the connection, if available. | ||
| − | + | <syntaxhighlight lang="idl"> | |
com::sun::star::uno::XInterface getParent() | com::sun::star::uno::XInterface getParent() | ||
void setParent( [in] com::sun::star::uno::XInterface Parent) | void setParent( [in] com::sun::star::uno::XInterface Parent) | ||
| − | + | </syntaxhighlight> | |
{{PDL1}} | {{PDL1}} | ||
[[Category:Documentation/Developer's Guide/Database Access]] | [[Category:Documentation/Developer's Guide/Database Access]] | ||
Latest revision as of 13:58, 21 December 2020
- 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). |
