diff options
Diffstat (limited to 'offapi/com/sun/star/sdbc/XConnection.idl')
| -rw-r--r-- | offapi/com/sun/star/sdbc/XConnection.idl | 229 |
1 files changed, 185 insertions, 44 deletions
diff --git a/offapi/com/sun/star/sdbc/XConnection.idl b/offapi/com/sun/star/sdbc/XConnection.idl index ac5856dcc6ef..b821c0cab39c 100644 --- a/offapi/com/sun/star/sdbc/XConnection.idl +++ b/offapi/com/sun/star/sdbc/XConnection.idl @@ -2,9 +2,9 @@ * * $RCSfile: XConnection.idl,v $ * - * $Revision: 1.7 $ + * $Revision: 1.8 $ * - * last change: $Author: mi $ $Date: 2001-11-01 16:46:46 $ + * last change: $Author: mi $ $Date: 2002-10-03 13:07:00 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -90,87 +90,133 @@ interface XDatabaseMetaData; executed and results are returned. - <p>A Connection's database is able to provide information + <p> + 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 <code>getMetaData</code> method. - - </p>@see com::sun::star::sdbc::XDriverManager - @see com::sun::star::sdbc::XStatement - @see com::sun::star::sdbc::XDatabaseMetaData + information is obtained with the + <member scope="com::sun::star::sdbc">XDatabaseMetaData::getMetaData()</member> + method. + + </p> + @see com::sun::star::sdbc::XDriverManager + @see com::sun::star::sdbc::XStatement + @see com::sun::star::sdbc::XDatabaseMetaData */ interface XConnection: com::sun::star::sdbc::XCloseable { // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::createStatement - /** creates a new <code>Statement</code> object for sending - SQL statements to the database. + /** creates a new + <type scope="com::sun::star::sdbc">Statement</type> + object for sending SQL statements to the database. - <p>SQL statements without parameters are normally + <p> + 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 <type scope="com::sun::star::sdbc">PreparedStatement</type>. + <type scope="com::sun::star::sdbc">PreparedStatement</type> + . </p> - <p>Result sets created using the returned Statement will have + <p> + Result sets created using the returned Statement will have forward-only type, and read-only concurrency, by default. </p> - <p>Escape processing for the SQL-Statement is enabled, by default. + <p> + Escape processing for the SQL-Statement is enabled, by default. </p> + + @returns + a new Statement object + @throws SQLException + if a database access error occurs. */ XStatement createStatement() raises (SQLException); //------------------------------------------------------------------------- // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::prepareStatement - /** creates a <code>PreparedStatement</code> object for sending - parameterized SQL statements to the database. + /** creates a + <type scope="com::sun::star::sdbc">PreparedStatement</type> + object for sending parameterized SQL statements to the database. - <p>A SQL statement with or without IN parameters can be + <p> + 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. </p> <p> - <b>Note:</b> This method is optimized for handling + <b> + Note: + </b> + This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, - the method <code>prepareStatement</code> will send + the method + <code>prepareStatement</code> + 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 <code>PreparedStatement</code> is - executed. This has no direct effect on users; however, it does + not be sent to the database until the + <type scope="com::sun::star::sdbc">PreparedStatement</type> + is executed. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions. </p> - <p> Result sets created using the returned PreparedStatement will have + <p> + Result sets created using the returned PreparedStatement will have forward-only type and read-only concurrency, by default. </p> - <p>Escape processing for the SQL-Statement is enabled, by default. + <p> + Escape processing for the SQL-Statement is enabled, by default. </p> + + @param 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. */ XPreparedStatement prepareStatement([in]string sql) raises (SQLException); //------------------------------------------------------------------------- // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::prepareCall - /** creates a <code>CallableStatement</code> object for calling + /** creates a + <type scope="com::sun::star::sdbc">CallableStatement</type> + object for calling database stored procedures. - <p>The CallableStatement provides methods for setting up its IN and OUT + <p> + The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure. </p> <p> - <b>Note:</b> This method is optimized for handling stored + <b> + Note: + </b> + This method is optimized for handling stored procedure call statements. Some drivers may send the call - statement to the database when the method <code>prepareCall</code> - is done;<br> + statement to the database when the method + <code>prepareCall</code> + is done; + <br/> 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. </p> + + @param 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. */ XPreparedStatement prepareCall([in]string sql) raises (SQLException); //------------------------------------------------------------------------- @@ -180,6 +226,13 @@ interface XConnection: com::sun::star::sdbc::XCloseable 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. + + @param 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. */ string nativeSQL([in]string sql) raises (SQLException); //------------------------------------------------------------------------- @@ -188,14 +241,20 @@ interface XConnection: com::sun::star::sdbc::XCloseable /** sets this connection's auto-commit mode. - <p>If a connection is in auto-commit mode, then all its SQL + <p> + 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 <code>commit</code> or the method <code>rollback</code>. + the method + <member scope="com::sun::star::sdbc">XConnection::commit()</member> + or the method + <member scope="com::sun::star::sdbc">XConnection::rollback()</member> + . By default, new connections are in auto-commit mode. </p> - <p>The commit occurs when the statement completes or the next + <p> + 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 @@ -204,6 +263,11 @@ interface XConnection: com::sun::star::sdbc::XCloseable parameter values. In these cases the commit occurs when all results and output parameter values have been retrieved. </p> + + @param autoCommit + <TRUE/> enables auto-commit; <FALSE/> disables auto-commit. + @throws SQLException + if a database access error occurs. */ void setAutoCommit([in] boolean autoCommit) raises (SQLException); //------------------------------------------------------------------------- @@ -211,6 +275,11 @@ interface XConnection: com::sun::star::sdbc::XCloseable // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::getAutoCommit /** gets the current auto-commit state. + @returns + the current state of auto-commit mode. + @throws SQLException + if a database access error occurs. + @see setAutoCommit */ boolean getAutoCommit() raises (SQLException); @@ -222,6 +291,9 @@ interface XConnection: com::sun::star::sdbc::XCloseable 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 setAutoCommit */ void commit() raises (SQLException); @@ -232,6 +304,9 @@ interface XConnection: com::sun::star::sdbc::XCloseable 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 setAutoCommit */ void rollback() raises (SQLException); @@ -242,9 +317,17 @@ interface XConnection: com::sun::star::sdbc::XCloseable <p> - <b>Note:</b> A Connection is automatically closed if no one references it + <b> + Note: + </b> + A Connection is automatically closed if no one references it anymore. Certain fatal errors also result in a closed Connection. </p> + + @returns + <TRUE/> if the connection is closed; <FALSE/> if it's still open. + @throws SQLException + if a database access error occurs. */ boolean isClosed() raises (SQLException); //------------------------------------------------------------------------- @@ -253,12 +336,18 @@ interface XConnection: com::sun::star::sdbc::XCloseable /** gets the metadata regarding this connection's database. - <p>A Connection's database is able to provide information + <p> + 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. </p> + + @returns + a DatabaseMetaData object for this Connection. + @throws SQLException + if a database access error occurs. */ XDatabaseMetaData getMetaData() raises (SQLException); //------------------------------------------------------------------------- @@ -269,16 +358,30 @@ interface XConnection: com::sun::star::sdbc::XCloseable <p> - <b>Note:</b> This method cannot be called while in the - middle of a transaction. Calling setReadOnly with <TRUE/> does not + <b> + Note: + </b> + This method cannot be called while in the + middle of a transaction. Calling setReadOnly with + <TRUE/> + does not necessarily cause writes to be prohibited. </p> + + @param readONly + <TRUE/> enables read-only mode; <FALSE/> disables read-only mode. + @throws SQLException + if a database access error occurs. */ void setReadOnly([in]boolean readOnly) raises (SQLException); //------------------------------------------------------------------------- // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::isReadOnly /** 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. */ boolean isReadOnly() raises (SQLException); //------------------------------------------------------------------------- @@ -288,12 +391,20 @@ interface XConnection: com::sun::star::sdbc::XCloseable a subspace of this Connection's database in which to work. If the driver does not support catalogs, it will silently ignore this request. + @param catalog + the name of the catalog. + @throws SQLException + if a database access error occurs. */ void setCatalog([in]string catalog) raises (SQLException); //------------------------------------------------------------------------- // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::getCatalog /** returns the Connection's current catalog name. + @returns + the current catalog name or an empty string. + @throws SQLException + if a database access error occurs. */ string getCatalog() raises (SQLException); //------------------------------------------------------------------------- @@ -302,21 +413,34 @@ interface XConnection: com::sun::star::sdbc::XCloseable /** attempts to change the transaction isolation level to the one given. - <p>The constants defined in - <type scope="com::sun::star::sdbc">TransactionIsolation</type> are the possible - transaction isolation levels. + <p> + The constants defined in + <type scope="com::sun::star::sdbc">TransactionIsolation</type> + are the possible transaction isolation levels. </p> <p> - <b>Note:</b> This method cannot be called while + <b> + Note: + </b> + This method cannot be called while in the middle of a transaction. - </p>@see - com::sun::star::sdbc::XDatabaseMetaData::supportsTransactionIsolationLevel() + </p> + @param 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 com::sun::star::sdbc::XDatabaseMetaData::supportsTransactionIsolationLevel() */ void setTransactionIsolation([in]long level) raises (SQLException); //------------------------------------------------------------------------- // DocMerge from xml: method com::sun::star::container::com::sun::star::sdbc::XConnection::getTransactionIsolation /** gets this Connection's current transaction isolation level. + @returns + the current TransactionIsolation mode value. + @throws SQLException + if a database access error occurs. */ long getTransactionIsolation() raises (SQLException); //------------------------------------------------------------------------- @@ -325,11 +449,16 @@ interface XConnection: com::sun::star::sdbc::XCloseable /** 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. -<!-- JRH: changed "how implement" to "which implement" --> - <p>Unless the application has added an entry to the type map, the map + <p> + Unless the application has added an entry to the type map, the map returned will be empty. </p> + @returns + the XNameAccess object associated with this Connection object. + + @throws SQLException + if a database access error occurs. */ com::sun::star::container::XNameAccess getTypeMap() raises (SQLException); //------------------------------------------------------------------------- @@ -340,8 +469,14 @@ interface XConnection: com::sun::star::sdbc::XCloseable and distinct types. - <p>Only if the driver supports custom type mapping is the setting of a map allowed. + <p> + Only if the driver supports custom type mapping is the setting of a map allowed. </p> + + @param typeMap + set the XNameAccess object associated with this Connection object. + @throws SQLException + if a database access error occurs. */ void setTypeMap([in]com::sun::star::container::XNameAccess typeMap) raises (SQLException); @@ -353,6 +488,12 @@ interface XConnection: com::sun::star::sdbc::XCloseable /*=========================================================================== $Log: not supported by cvs2svn $ + Revision 1.7.2.1 2002/02/18 09:00:56 oj + #97563# parameter,return value and exception description + + Revision 1.7 2001/11/01 16:46:46 mi + proofreading and corrections from Richard Holt + Revision 1.6 2001/03/16 16:41:35 jsc remove interfaceheader with uik and remove [const] in method definitions |