diff options
Diffstat (limited to 'offapi/com/sun/star/sdbc/XConnection.idl')
| -rw-r--r-- | offapi/com/sun/star/sdbc/XConnection.idl | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/offapi/com/sun/star/sdbc/XConnection.idl b/offapi/com/sun/star/sdbc/XConnection.idl new file mode 100644 index 000000000..3548ac187 --- /dev/null +++ b/offapi/com/sun/star/sdbc/XConnection.idl @@ -0,0 +1,406 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_sdbc_XConnection_idl__ +#define __com_sun_star_sdbc_XConnection_idl__ + +#include <com/sun/star/uno/XInterface.idl> + + module com { module sun { module star { module container { + published interface XNameAccess; +};};};}; + +#include <com/sun/star/sdbc/SQLException.idl> + +#include <com/sun/star/sdbc/XCloseable.idl> + + module com { module sun { module star { module sdbc { + + published interface XStatement; + published interface XPreparedStatement; + published interface XDatabaseMetaData; + + +/** represents a connection (session) with a specific + database. Within the context of a Connection, SQL statements are + executed and results are returned. + + + <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 + com::sun::star::sdbc::XDatabaseMetaData::getMetaData() + method. + + </p> + @see com::sun::star::sdbc::XDriverManager + @see com::sun::star::sdbc::XStatement + @see com::sun::star::sdbc::XDatabaseMetaData + */ +published interface XConnection: com::sun::star::sdbc::XCloseable +{ + + /** creates a new + com::sun::star::sdbc::Statement + object for sending SQL statements to the database. + + + <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 + com::sun::star::sdbc::PreparedStatement. + </p> + <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> + + @returns + a new Statement object + @throws SQLException + if a database access error occurs. + */ + XStatement createStatement() raises (SQLException); + + /** creates a + com::sun::star::sdbc::PreparedStatement + object for sending parameterized SQL statements to the database. + + + <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 + parametric SQL statements that benefit from precompilation. If + the driver supports precompilation, + 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 + com::sun::star::sdbc::PreparedStatement + 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 + forward-only type and read-only concurrency, by default. + </p> + <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); + + /** creates a + com::sun::star::sdbc::CallableStatement + object for calling + database stored procedures. + + + <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 + procedure call statements. Some drivers may send the call + 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); + + /** 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. + + @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); + + /** sets this connection's auto-commit mode. + + + <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 + com::sun::star::sdbc::XConnection::commit() + or the method + com::sun::star::sdbc::XConnection::rollback(). + By default, new connections are in auto-commit mode. + </p> + <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 + 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. + </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); + + /** 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); + + /** 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 setAutoCommit + */ + void commit() 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. + + @throws SQLException + if a database access error occurs. + + @see setAutoCommit + */ + void rollback() raises (SQLException); + + /** tests to see if a connection is closed. + + + <p> + <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); + + /** gets the metadata regarding this connection's database. + + + <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); + + /** puts this connection in read-only mode as a hint to enable + database optimizations. + + + <p> + <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); + + /** 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); + + /** 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. + @param catalog + the name of the catalog. + @throws SQLException + if a database access error occurs. + */ + void setCatalog([in]string catalog) raises (SQLException); + + /** 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); + + /** attempts to change the transaction isolation level to the one given. + + + <p> + The constants defined in + com::sun::star::sdbc::TransactionIsolation + are the possible transaction isolation levels. + </p> + <p> + <b> + Note: + </b> + This method cannot be called while + in the middle of a transaction. + </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); + + /** 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); + + /** 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. + + <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); + + /** 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. + + + <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); +}; + + +}; }; }; }; + +/*=========================================================================== +===========================================================================*/ +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |