English:

The Free and Open Productivity Suite
Help us Help the World

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: sdbc ::

interface XConnection
Base Interfaces
XConnectionXCloseable

XCloseable
(referenced interface's summary:)
provides for the releasing of resources acquired by the implementing object.
Description
represents a connection (session) with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, and the capabilities of this connection. This information is obtained with the XDatabaseMetaData::getMetaData() method.

See also
XDriverManager, XStatement, XDatabaseMetaData

Methods' Summary
createStatement creates a new Statement object for sending SQL statements to the database.  
prepareStatement creates a PreparedStatement object for sending parameterized SQL statements to the database.  
prepareCall creates a CallableStatement object for calling database stored procedures.  
nativeSQL converts the given SQL statement into the system's native SQL grammar. A driver may convert the JDBC SQL grammar into its system's native SQL grammar prior to sending it; this method returns the native form of the statement that the driver would have sent.  
setAutoCommit sets this connection's auto-commit mode.  
getAutoCommit gets the current auto-commit state.  
commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should be used only when auto-commit mode has been disabled.  
rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection. This method should be used only when auto-commit has been disabled.  
isClosed tests to see if a connection is closed.  
getMetaData gets the metadata regarding this connection's database.  
setReadOnly puts this connection in read-only mode as a hint to enable database optimizations.  
isReadOnly tests to see if the connection is in read-only mode.  
setCatalog sets a catalog name in order to select a subspace of this Connection's database in which to work. If the driver does not support catalogs, it will silently ignore this request.  
getCatalog returns the Connection's current catalog name.  
setTransactionIsolation attempts to change the transaction isolation level to the one given.  
getTransactionIsolation gets this Connection's current transaction isolation level.  
getTypeMap gets the type map object associated with this connection. Only drivers which implement the custom type mapping facility will return an object otherwise NULL could be returned.  
setTypeMap installs the given type map as the type map for this connection. The type map will be used for the custom mapping of SQL structured types and distinct types.  
Methods' Details
createStatement
XStatement
createStatement()
raises( SQLException );

Description
creates a new Statement object for sending SQL statements to the database.

SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement .

Result sets created using the returned Statement will have forward-only type, and read-only concurrency, by default.

Escape processing for the SQL-Statement is enabled, by default.

Returns
a new Statement object
Throws
SQLException if a database access error occurs.
prepareStatement
XPreparedStatement
prepareStatement( [in] string  sql )
raises( SQLException );

Description
creates a PreparedStatement object for sending parameterized SQL statements to the database.

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions.

Result sets created using the returned PreparedStatement will have forward-only type and read-only concurrency, by default.

Escape processing for the SQL-Statement is enabled, by default.

Parameter sql
a SQL statement that may contain one or more '?' IN parameter placeholders
Returns
a new PreparedStatement object containing the pre-compiled statement
Throws
SQLException if a database access error occurs.
prepareCall
XPreparedStatement
prepareCall( [in] string  sql )
raises( SQLException );

Description
creates a CallableStatement object for calling database stored procedures.

The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the method prepareCall is done;
others may wait until the CallableStatement is executed. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions. Result sets created using the returned CallableStatement will have forward-only type and read-only concurrency, by default.

Parameter sql
a SQL statement that may contain one or more '?' IN parameter placeholders
Returns
a new PreparedStatement object containing the pre-compiled statement
Throws
SQLException if a database access error occurs.
nativeSQL
string
nativeSQL( [in] string  sql )
raises( SQLException );

Description
converts the given SQL statement into the system's native SQL grammar. A driver may convert the JDBC SQL grammar into its system's native SQL grammar prior to sending it; this method returns the native form of the statement that the driver would have sent.
Parameter sql
a SQL statement that may contain one or more '?' parameter placeholders
Returns
the native form of this statement
Throws
SQLException if a database access error occurs.
setAutoCommit
void
setAutoCommit( [in] boolean  autoCommit )
raises( SQLException );

Description
sets this connection's auto-commit mode.

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method XConnection::commit() or the method XConnection::rollback() . By default, new connections are in auto-commit mode.

The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. In these cases the commit occurs when all results and output parameter values have been retrieved.

Parameter autoCommit
true enables auto-commit; false disables auto-commit.
Throws
SQLException if a database access error occurs.
getAutoCommit
boolean
getAutoCommit()
raises( SQLException );

Description
gets the current auto-commit state.
Returns
the current state of auto-commit mode.
Throws
SQLException if a database access error occurs.
See also
setAutoCommit
commit
void
commit()
raises( SQLException );

Description
makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should be used only when auto-commit mode has been disabled.
Throws
SQLException if a database access error occurs.
See also
setAutoCommit
rollback
void
rollback()
raises( SQLException );

Description
drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection. This method should be used only when auto-commit has been disabled.
Throws
SQLException if a database access error occurs.
See also
setAutoCommit
isClosed
boolean
isClosed()
raises( SQLException );

Description
tests to see if a connection is closed.

Note: A Connection is automatically closed if no one references it anymore. Certain fatal errors also result in a closed Connection.

Returns
true if the connection is closed; false if it's still open.
Throws
SQLException if a database access error occurs.
getMetaData
XDatabaseMetaData
getMetaData()
raises( SQLException );

Description
gets the metadata regarding this connection's database.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, and so on. This information is made available through a DatabaseMetaData object.

Returns
a DatabaseMetaData object for this Connection.
Throws
SQLException if a database access error occurs.
setReadOnly
void
setReadOnly( [in] boolean  readOnly )
raises( SQLException );

Description
puts this connection in read-only mode as a hint to enable database optimizations.

Note: This method cannot be called while in the middle of a transaction. Calling setReadOnly with true does not necessarily cause writes to be prohibited.

Parameter readONly
true enables read-only mode; false disables read-only mode.
Throws
SQLException if a database access error occurs.
isReadOnly
boolean
isReadOnly()
raises( SQLException );

Description
tests to see if the connection is in read-only mode.
Returns
true if connection is read-only and false otherwise.
Throws
SQLException if a database access error occurs.
setCatalog
void
setCatalog( [in] string  catalog )
raises( SQLException );

Description
sets a catalog name in order to select a subspace of this Connection's database in which to work. If the driver does not support catalogs, it will silently ignore this request.
Parameter catalog
the name of the catalog.
Throws
SQLException if a database access error occurs.
getCatalog
string
getCatalog()
raises( SQLException );

Description
returns the Connection's current catalog name.
Returns
the current catalog name or an empty string.
Throws
SQLException if a database access error occurs.
setTransactionIsolation
void
setTransactionIsolation( [in] long  level )
raises( SQLException );

Description
attempts to change the transaction isolation level to the one given.

The constants defined in TransactionIsolation are the possible transaction isolation levels.

Note: This method cannot be called while in the middle of a transaction.

Parameter level
one of the TransactionIsolation values with the exception of NONE; some databases may not support other values.
Throws
SQLException if a database access error occurs.
See also
XDatabaseMetaData::supportsTransactionIsolationLevel()
getTransactionIsolation
long
getTransactionIsolation()
raises( SQLException );

Description
gets this Connection's current transaction isolation level.
Returns
the current TransactionIsolation mode value.
Throws
SQLException if a database access error occurs.
getTypeMap
::com::sun::star::container::XNameAccess
getTypeMap()
raises( SQLException );

Description
gets the type map object associated with this connection. Only drivers which implement the custom type mapping facility will return an object otherwise NULL could be returned.

Unless the application has added an entry to the type map, the map returned will be empty.

Returns
the XNameAccess object associated with this Connection object.
Throws
SQLException if a database access error occurs.
setTypeMap
void
setTypeMap( [in] ::com::sun::star::container::XNameAccess  typeMap )
raises( SQLException );

Description
installs the given type map as the type map for this connection. The type map will be used for the custom mapping of SQL structured types and distinct types.

Only if the driver supports custom type mapping is the setting of a map allowed.

Parameter typeMap
set the XNameAccess object associated with this Connection object.
Throws
SQLException if a database access error occurs.
Top of Page

Logo ApacheCon Europe 2014

Apache Feather

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.