LibreOffice: XConnection Interface Reference

LibreOffice LibreOffice 7.0 SDK API Reference

Public Member Functions | List of all members
XConnection Interface Referencepublished

represents a connection (session) with a specific database. More...

`import"XConnection.idl";`

Inheritance diagram for XConnection:

## Public Member Functions
XStatement | createStatement () raises (SQLException)
| creates a new com::sun::star::sdbc::Statement object for sending SQL statements to the database. More...
XPreparedStatement | prepareStatement ([in]string sql) raises (SQLException)
| creates a com::sun::star::sdbc::PreparedStatement object for sending parameterized SQL statements to the database. More...
XPreparedStatement | prepareCall ([in]string sql) raises (SQLException)
| creates a com::sun::star::sdbc::CallableStatement object for calling database stored procedures. More...
string | nativeSQL ([in]string sql) raises (SQLException)
| converts the given SQL statement into the system's native SQL grammar. More...
void | setAutoCommit ([in] boolean autoCommit) raises (SQLException)
| sets this connection's auto-commit mode. More...
boolean | getAutoCommit () raises (SQLException)
| gets the current auto-commit state. More...
void | commit () raises (SQLException)
| makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. More...
void | rollback () raises (SQLException)
| drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection. More...
boolean | isClosed () raises (SQLException)
| tests to see if a connection is closed. More...
XDatabaseMetaData | getMetaData () raises (SQLException)
| gets the metadata regarding this connection's database. More...
void | setReadOnly ([in]boolean readOnly) raises (SQLException)
| puts this connection in read-only mode as a hint to enable database optimizations. More...
boolean | isReadOnly () raises (SQLException)
| tests to see if the connection is in read-only mode. More...
void | setCatalog ([in]string catalog) raises (SQLException)
| sets a catalog name in order to select a subspace of this Connection's database in which to work. More...
string | getCatalog () raises (SQLException)
| returns the Connection's current catalog name. More...
void | setTransactionIsolation ([in]long level) raises (SQLException)
| attempts to change the transaction isolation level to the one given. More...
long | getTransactionIsolation () raises (SQLException)
| gets this Connection's current transaction isolation level. More...
com::sun::star::container::XNameAccess | getTypeMap () raises (SQLException)
| gets the type map object associated with this connection. More...
void | setTypeMap ([in]com::sun::star::container::XNameAccess typeMap) raises (SQLException)
| installs the given type map as the type map for this connection. More...
Public Member Functions inherited from XCloseable
void | close () raises (SQLException)
| releases all resources connected to an object. More...
Public Member Functions inherited from XInterface
any | queryInterface ([in] type aType)
| queries for a new interface to an existing UNO object. More...
void | acquire ()
| increases the reference counter by one. More...
void | release ()
| decreases the reference counter by one. More...

## Detailed 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 com::sun::star::sdbc::XDatabaseMetaData::getMetaData() method.

See also
  com::sun::star::sdbc::XDriverManager
  com::sun::star::sdbc::XStatement
  com::sun::star::sdbc::XDatabaseMetaData

## Member Function Documentation

## ◆ commit()

void commit | ( |  | ) |
raises | ( | SQLException
| ) |  |

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.

Exceptions

  SQLException | if a database access error occurs.

See also
  setAutoCommit

## ◆ createStatement()

XStatement createStatement | ( |  | ) |
raises | ( | SQLException
| ) |  |

creates a new com::sun::star::sdbc::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 com::sun::star::sdbc::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

Exceptions

  SQLException | if a database access error occurs.

## ◆ getAutoCommit()

boolean getAutoCommit | ( |  | ) |
raises | ( | SQLException
| ) |  |

gets the current auto-commit state.

Returns
  the current state of auto-commit mode.

Exceptions

  SQLException | if a database access error occurs.

See also
  setAutoCommit

## ◆ getCatalog()

string getCatalog | ( |  | ) |
raises | ( | SQLException
| ) |  |

returns the Connection's current catalog name.

Returns
  the current catalog name or an empty string.

Exceptions

  SQLException | if a database access error occurs.

## ◆ getMetaData()

XDatabaseMetaData getMetaData | ( |  | ) |
raises | ( | SQLException
| ) |  |

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.

Exceptions

  SQLException | if a database access error occurs.

## ◆ getTransactionIsolation()

long getTransactionIsolation | ( |  | ) |
raises | ( | SQLException
| ) |  |

gets this Connection's current transaction isolation level.

Returns
  the current TransactionIsolation mode value.

Exceptions

  SQLException | if a database access error occurs.

## ◆ getTypeMap()

com::sun::star::container::XNameAccess getTypeMap | ( |  | ) |
raises | ( | SQLException
| ) |  |

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.

Exceptions

  SQLException | if a database access error occurs.

## ◆ isClosed()

boolean isClosed | ( |  | ) |
raises | ( | SQLException
| ) |  |

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.

Exceptions

  SQLException | if a database access error occurs.

## ◆ isReadOnly()

boolean isReadOnly | ( |  | ) |
raises | ( | SQLException
| ) |  |

tests to see if the connection is in read-only mode.

Returns
  `TRUE` if connection is read-only and `FALSE` otherwise.

Exceptions

  SQLException | if a database access error occurs.

## ◆ nativeSQL()

string nativeSQL | ( | [in] string | sql | ) |
raises | ( | SQLException
| ) |  |

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.

Parameters

  sql | a SQL statement that may contain one or more "?" parameter placeholders

Returns
  the native form of this statement

Exceptions

  SQLException | if a database access error occurs.

## ◆ prepareCall()

XPreparedStatement prepareCall | ( | [in] string | sql | ) |
raises | ( | SQLException
| ) |  |

creates a com::sun::star::sdbc::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.

Parameters

  sql | a SQL statement that may contain one or more "?" IN parameter placeholders

Returns
  a new PreparedStatement object containing the pre-compiled statement

Exceptions

  SQLException | if a database access error occurs.

## ◆ prepareStatement()

XPreparedStatement prepareStatement | ( | [in] string | sql | ) |
raises | ( | SQLException
| ) |  |

creates a com::sun::star::sdbc::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 com::sun::star::sdbc::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.

Parameters

  sql | a SQL statement that may contain one or more "?" IN parameter placeholders

Returns
  a new PreparedStatement object containing the pre-compiled statement

Exceptions

  SQLException | if a database access error occurs.

## ◆ rollback()

void rollback | ( |  | ) |
raises | ( | SQLException
| ) |  |

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.

Exceptions

  SQLException | if a database access error occurs.

See also
  setAutoCommit

## ◆ setAutoCommit()

void setAutoCommit | ( | [in] boolean | autoCommit | ) |
raises | ( | SQLException
| ) |  |

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 com::sun::star::sdbc::XConnection::commit() or the method com::sun::star::sdbc::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.

Parameters

  autoCommit | `TRUE` enables auto-commit; `FALSE` disables auto-commit.

Exceptions

  SQLException | if a database access error occurs.

## ◆ setCatalog()

void setCatalog | ( | [in] string | catalog | ) |
raises | ( | SQLException
| ) |  |

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.

Parameters

  catalog | the name of the catalog.

Exceptions

  SQLException | if a database access error occurs.

## ◆ setReadOnly()

void setReadOnly | ( | [in] boolean | readOnly | ) |
raises | ( | SQLException
| ) |  |

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.

Parameters

  readOnly | `TRUE` enables read-only mode; `FALSE` disables read-only mode.

Exceptions

  SQLException | if a database access error occurs.

## ◆ setTransactionIsolation()

void setTransactionIsolation | ( | [in] long | level | ) |
raises | ( | SQLException
| ) |  |

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

The constants defined in com::sun::star::sdbc::TransactionIsolation are the possible transaction isolation levels.

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

Parameters

  level | one of the TransactionIsolation values with the exception of NONE; some databases may not support other values.

Exceptions

  SQLException | if a database access error occurs.

See also
  com::sun::star::sdbc::XDatabaseMetaData::supportsTransactionIsolationLevel()

## ◆ setTypeMap()

void setTypeMap | ( | [in] com::sun::star::container::XNameAccess | typeMap | ) |
raises | ( | SQLException
| ) |  |

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.

Parameters

  typeMap | set the XNameAccess object associated with this Connection object.

Exceptions

  SQLException | if a database access error occurs.

The documentation for this interface was generated from the following file:

- com/sun/star/sdbc/XConnection.idl