com.simba.dsi.core.interfaces
Interface IConnection

All Known Implementing Classes:
DSIConnection

public interface IConnection

An IConnection handles connection properties and statements. It is also responsible for verifying if given connection settings are valid, and granting a connection to the data source.


Method Summary
 void beginTransaction()
          Begins a transaction.
 void close()
          Closes the connection and releases any resources held by it.
 void commit()
          Commits all transactions within this connection.
 void connect(ConnSettingRequestMap requestMap)
          Attempts to establish connection when requested to form a connection, not when the IConnection is allocated.
 IArray createArrayOf(java.lang.String typeName, java.lang.Object[] elements)
          Factory method for creating IArray objects.
 void createSavepoint(java.lang.String name)
          Create a savepoint with the given name.
 IStatement createStatement()
          Factory method for creating IStatements.
 void disconnect()
          Closes the connection.
 java.lang.String getClientInfo(java.lang.String name)
          Gets a client info property identified by the given property key.
 java.util.Map<java.lang.String,ClientInfoData> getClientInfoProperties()
          Gets all the client info properties.
 com.simba.support.ILogger getConnectionLog()
          Gets the connection ILogger logging interface.
 java.util.Map<java.lang.Long,ConnectionSettingInfo> getConnectionSettingInfo()
          Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions.
 Variant getCustomProperty(int propKey)
          Gets a custom connection property as identified by the given property key.
 int getCustomPropertyType(int propKey)
          Gets the type of the custom property associated with the given property key.
 java.lang.String getDataSourceName()
          Gets name of the data source.
 java.util.Locale getLocale()
          Gets the connection-wide locale.
 com.simba.support.IMessageSource getMessageSource()
          Gets the message source.
 IEnvironment getParentEnvironment()
          Gets the parent environment for this connection.
 Variant getProperty(int propKey)
          Gets the DSI property as identified by the given property key.
 com.simba.support.IWarningListener getWarningListener()
          Gets the warning listener associated with this IConnection.
 boolean isAlive()
          Determine if the connection is still alive and connected.
 boolean isCustomProperty(int propKey)
          Validates if the given property key is associated with a custom connection property.
 boolean promptDialog(ConnSettingResponseMap connResponseMap, ConnSettingRequestMap connectionSettings, long parentWindow, PromptType promptType)
          Displays a dialog box that prompts the user for settings for this connection.
 void registerTransactionStateListener(ITransactionStateListener listener)
          Register a transaction state listener for allowing the IConnection to notify when transaction state changes occur via SQL queries.
 void registerWarningListener(com.simba.support.IWarningListener listener)
          Registers a warning listener for allowing the IConnection to post warnings.
 void releaseSavepoint(java.lang.String name)
          Releases the specified Savepoint from the current transaction.
 void reset()
          Reset this connection to a clean state (w.r.t.
 void rollback()
          Rolls back all transactions within this connection.
 void rollback(java.lang.String name)
          Roll back to the savepoint with the given name.
 void setClientInfoProperty(java.lang.String propName, java.lang.String propValue)
          Sets the client info property value to the database.
 void setCustomProperty(int propKey, Variant propValue)
          Sets a custom property, as identified by the given property key, with the given property value.
 void setInvokerAndClassLoader(java.lang.Object invoker, java.lang.Object classLoader)
          Sets the invoker object and class loader.
 void setLocale(java.util.Locale locale)
          Sets the connection-wide locale.
 void setProperty(int propKey, Variant propValue)
          Sets a DSI property, as identified by the given property key, with the given property value.
 java.lang.String toNativeSQL(java.lang.String sql)
          Converts an ODBC-formatted SQL statement into customized and optimized form for the data source.
 ConnSettingResponseMap updateConnectionSettings(ConnSettingRequestMap requestMap)
          Checks and updates settings for this connection.
 

Method Detail

beginTransaction

void beginTransaction()
                      throws com.simba.support.exceptions.ErrorException
Begins a transaction.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while starting the transaction.

close

void close()
Closes the connection and releases any resources held by it.


commit

void commit()
            throws com.simba.support.exceptions.ErrorException
Commits all transactions within this connection. Committing will invalidate any savepoints that have been created in the current transaction.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while committing the transaction.

connect

void connect(ConnSettingRequestMap requestMap)
             throws BadAuthException,
                    com.simba.support.exceptions.ErrorException
Attempts to establish connection when requested to form a connection, not when the IConnection is allocated. The IConnection can be re-used after disconnect(), therefore calling connect() after disconnect() will set up a new connection on the same IConnection.

Parameters:
requestMap - Connection settings used to authenticate if connection should be granted.
Throws:
com.simba.support.exceptions.ErrorException - If an unspecified error occurs.
BadAuthException - If the inputs fail authentication.
See Also:
ConnSettingRequestMap

createSavepoint

void createSavepoint(java.lang.String name)
                     throws com.simba.support.exceptions.ErrorException
Create a savepoint with the given name.

Parameters:
name - The name of the savepoint to create.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs, or if savepoints are not supported.

createStatement

IStatement createStatement()
                           throws com.simba.support.exceptions.ErrorException
Factory method for creating IStatements.

Returns:
the created IStatement
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.
See Also:
IStatement

disconnect

void disconnect()
                throws com.simba.support.exceptions.ErrorException
Closes the connection. This is not equivalent to destroying the IConnection object. The connection object can be re-used.

This call is a request to the DSII layer to free up all memory that it has allocated for the database, and to close any tables that are currently open for the database.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getConnectionSettingInfo

java.util.Map<java.lang.Long,ConnectionSettingInfo> getConnectionSettingInfo()
Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions. This is currently only used by OLEDB providers. How the map keys are interpreted is dependent on if this is an ODBC or OLEDB connection. In OLEDB Mode, the following values are used to map initialization properties to connection settings: OLEDB ID | OLEDB Description | Variant Type --------------------------|-----------------------------|------------------------------ DBPROP_AUTH_USERID | User ID | WString DBPROP_AUTH_PASSWORD | Password | WString DBPROP_AUTH_INTEGRATED | Integrated Security | WString DBPROP_INIT_DATASOURCE | Data Source | WString DBPROP_INIT_LOCATION | Location | WString DBPROP_INIT_CATALOG | Initial Catalog | WString DBPRPO_INIT_LCID | Locale Identifier | WString (See Note) Notes on specific properties: DBPROP_AUTH_INTEGRATED - This property is a WString which OLEDB describes as being the name of the security service to use. - Many windows applications will pass a value of "SSPI" to this property. - A value of "" means to use integrated security with the default service. - In many applications, when a user selects this option, the application will disable entry fields for USERID and PASSWORD and will not pass values for them. If you would like to receive those values along with a similar one for integrated security, you must not use this and should define a custom ID. DBPROP_INIT_CATALOG - If you don't describe this property, or describe an empty key, it will still be supported if your DSII supports Catalogs. It will instead be passed to IConnection::SetProperty(DSI_CONN_CURRENT_CATALOG) before connecting. - If you describe a non-empty key for this in your info map, DBPROP_INIT_CATALOG will be passed to your UpdateConnectionSettings and Connect functions. DBPROP_INIT_LCID - This property always maps to key "LOCALE" - It defaults to optional but may be reported as required. - The type WString is what will be passed to the connection settings map, however, OLEDB defines this as an int32 locale identifier. We look up this identifier value and pass its string representation. Other properties (initialization or otherwise) are not mapped. Custom properties may be present but must not conflict with existing property IDs and only be used within the range 0x80000000 to 0xFFFFFFFF. In ODBC Mode, the map keys currently have no defined relationship with the setting info. The DSII must remain prepared to deal with entries in the DSIConnSettingRequestMap passed to UpdateConnectionSettings or Connect that were not described by this function.

Returns:
Reference to map to filled in with settings accepted.

getConnectionLog

com.simba.support.ILogger getConnectionLog()
Gets the connection ILogger logging interface.

Returns:
Log for connection logging.
See Also:
ILogger

getClientInfo

java.lang.String getClientInfo(java.lang.String name)
                               throws com.simba.support.exceptions.ErrorException
Gets a client info property identified by the given property key.

Parameters:
name - The client info property name.
Returns:
the client info property value.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getClientInfoProperties

java.util.Map<java.lang.String,ClientInfoData> getClientInfoProperties()
Gets all the client info properties.

Returns:
a map containing all client info properties.

getCustomProperty

Variant getCustomProperty(int propKey)
                          throws com.simba.support.exceptions.ErrorException
Gets a custom connection property as identified by the given property key.

Parameters:
propKey - Property key associated with a custom connection property.
Returns:
Property value associated with the given property key.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.
See Also:
Variant

getCustomPropertyType

int getCustomPropertyType(int propKey)
                          throws com.simba.support.exceptions.ErrorException
Gets the type of the custom property associated with the given property key.

Parameters:
propKey - Gets the type of the custom property associated with the given property key.
Returns:
Type of the custom property associated with the given property key.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getDataSourceName

java.lang.String getDataSourceName()
                                   throws com.simba.support.exceptions.ErrorException
Gets name of the data source.

Returns:
Data source name.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getLocale

java.util.Locale getLocale()
Gets the connection-wide locale. The locale is set by setting the "LOCALE" connection key to a valid value. The locale is composed of a 2-letter (lower case) language code, and an optional 2-letter (upper case) country code. If a country code is included, the two codes _MUST_ be separated by a hyphen (-). The language codes conform to the ISO 639-1 standard. http://www.loc.gov/standards/iso639-2/php/code_list.php The country codes conform to the ISO 3166-1 Alpha-2 code standard. http://www.iso.org/iso/country_codes/iso-3166-1_decoding_table.htm Examples: en-US (English - United States) fr-CA (French - Canada) it-IT (Italian - Italy) de-DE (German - Germany) es-ES (Spanish - Spain (Traditional)) ja (Japanese)

Returns:
The locale for this connection.

getMessageSource

com.simba.support.IMessageSource getMessageSource()
Gets the message source.

Returns:
The message source.

getParentEnvironment

IEnvironment getParentEnvironment()
Gets the parent environment for this connection.

Returns:
The parent environment instance.

getProperty

Variant getProperty(int propKey)
                    throws BadPropertyKeyException,
                           com.simba.support.exceptions.ErrorException
Gets the DSI property as identified by the given property key.

Parameters:
propKey - Property key associated with a DSI connection property.
Returns:
Property value associated with the given DSI property key.
Throws:
BadPropertyKeyException - If the input key is not valid.
com.simba.support.exceptions.ErrorException - If an unspecified error occurs.
See Also:
Variant

getWarningListener

com.simba.support.IWarningListener getWarningListener()
Gets the warning listener associated with this IConnection.

Returns:
The warning listener associated with this IConnection.

isAlive

boolean isAlive()
Determine if the connection is still alive and connected. This method will be called when using pooled connections with the JDBC layer after an exception has been thrown up if the JDBC layer needs to determine if the exception caused the connection to become invalid.

Returns:
true if the connection is still valid and connected; false otherwise.

isCustomProperty

boolean isCustomProperty(int propKey)
                         throws com.simba.support.exceptions.ErrorException
Validates if the given property key is associated with a custom connection property.

Parameters:
propKey - Property key associated with a custom connection property
Returns:
true if given property key is associated with a custom connection property, false if given property key is not recognized.
Throws:
com.simba.support.exceptions.ErrorException - If there is an error checking the property key.

promptDialog

boolean promptDialog(ConnSettingResponseMap connResponseMap,
                     ConnSettingRequestMap connectionSettings,
                     long parentWindow,
                     PromptType promptType)
Displays a dialog box that prompts the user for settings for this connection. The connection settings from io_connectionSettings are presented as key-value string pairs. The input connection settings map is the initial state of the dialog box. The input connection settings map will be modified to reflect the user's input to the dialog box. The return value for this method indicates if the user completed the process by clicking OK on the dialog box (return true), or if the user aborts the process by clicking CANCEL on the dialog box (return false).

Parameters:
connResponseMap - The connection settings map updated to reflect the user's input.
connectionSettings - The connection settings map updated with settings that are still needed and were not supplied.
parentWindow - Handle to the parent window to which this dialog belongs.
promptType - Indicates what type of connection settings to request - either both required and optional settings or just required settings.
Returns:
true if the user clicks OK on the dialog box; false if the user clicks CANCEL.

registerTransactionStateListener

void registerTransactionStateListener(ITransactionStateListener listener)
Register a transaction state listener for allowing the IConnection to notify when transaction state changes occur via SQL queries.

Parameters:
listener - The listener to register.

registerWarningListener

void registerWarningListener(com.simba.support.IWarningListener listener)
Registers a warning listener for allowing the IConnection to post warnings.

Parameters:
listener - The listener to register with this IConnection.

releaseSavepoint

void releaseSavepoint(java.lang.String name)
                      throws com.simba.support.exceptions.ErrorException
Releases the specified Savepoint from the current transaction.

Releasing a Savepoint will invalidate that Savepoint and any attempt to reference that Savepoint will cause an exception to be thrown.

Parameters:
name - The name of the Savepoint to release.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while releasing the Savepoint.

reset

void reset()
           throws com.simba.support.exceptions.ErrorException
Reset this connection to a clean state (w.r.t. connection properties). Reset this connection's connection properties to their default state. If the connection was currently connected, it stays connected. Note: Will only be called if running in the context of an ODBC driver or Server.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

rollback

void rollback()
              throws com.simba.support.exceptions.ErrorException
Rolls back all transactions within this connection. Rolling back will invalidate any savepoints that have been created in the current transaction.

Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while rolling back the transaction.

rollback

void rollback(java.lang.String name)
              throws com.simba.support.exceptions.ErrorException
Roll back to the savepoint with the given name.

Parameters:
name - The name of the savepoint to roll back to.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

setClientInfoProperty

void setClientInfoProperty(java.lang.String propName,
                           java.lang.String propValue)
                           throws com.simba.support.exceptions.ClientInfoException
Sets the client info property value to the database.

Parameters:
propName - The client info property name.
propValue - The value for the given property.
Throws:
com.simba.support.exceptions.ClientInfoException - If an error occurs.

setCustomProperty

void setCustomProperty(int propKey,
                       Variant propValue)
                       throws BadAttrValException,
                              com.simba.support.exceptions.ErrorException
Sets a custom property, as identified by the given property key, with the given property value. If the value is substituted with another value before storage, an OPT_VAL_CHANGED_WARNING warning should be posted in the warnings holder. For properties which accept more than just a discrete set of values, this method should throw a BadAttrValException if an illegal value is given which can't be substituted with another value.

Parameters:
propKey - Property key associated with a custom connection property.
propValue - Property value to be set on the custom connection property associated with the given property key.
Throws:
BadAttrValException - If an illegal value is given which can't substituted with another value.
com.simba.support.exceptions.ErrorException - If an error occurs.
See Also:
Variant

setInvokerAndClassLoader

void setInvokerAndClassLoader(java.lang.Object invoker,
                              java.lang.Object classLoader)
Sets the invoker object and class loader.

NOTE: This will only be called when the JavaDSI is used with the JNIDSI, and when the JNIDSI is built as a DLL that is loaded and invoked from another Java program.

Parameters:
invoker - The Java object that invokes the first JNI class.
classLoader - The Java classLoader object from the invoking Java program.

setLocale

void setLocale(java.util.Locale locale)
Sets the connection-wide locale.

Parameters:
locale - The locale to set.

setProperty

void setProperty(int propKey,
                 Variant propValue)
                 throws BadAttrValException,
                        com.simba.support.exceptions.ErrorException
Sets a DSI property, as identified by the given property key, with the given property value. If the value is substituted with another value before storage, an OPT_VAL_CHANGED_WARNING warning should be posted in the warnings holder. For properties which accept more than just a discrete set of values, this method should throw a BadAttrValException if an illegal value is given which can't be substituted with another value.

Parameters:
propKey - Property key associated with a DSI connection property.
propValue - Property value to be set on the DSI connection property associated with the given property key.
Throws:
BadAttrValException - If the input value is not valid for the key.
com.simba.support.exceptions.ErrorException - If an unspecified error occurs.
See Also:
Variant

toNativeSQL

java.lang.String toNativeSQL(java.lang.String sql)
                             throws com.simba.support.exceptions.ErrorException
Converts an ODBC-formatted SQL statement into customized and optimized form for the data source.

Parameters:
sql - ODBC-formatted SQL statement.
Returns:
Customized and optimised form of the input SQL statement.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

updateConnectionSettings

ConnSettingResponseMap updateConnectionSettings(ConnSettingRequestMap requestMap)
                                                throws BadAuthException,
                                                       com.simba.support.exceptions.ErrorException
Checks and updates settings for this connection. This method is called when attempting to establish a connection to check if the input connection settings are valid. This method DOES NOT establish a connection. Connect() should be called to attempt to establish a connection. This method should inspect the input ConnSettingRequestMap and return any modified and additional requested connection settings in the returned ConnSettingResponseMap.

If any connection settings have been modified, then an OPT_VAL_CHANGED warning must be posted. If a key in the map is unrecognized or does not belong in this stage of connection, then an INVALID_CONN_STR_ATTR warning must be posted.

Parameters:
requestMap - Connection settings specified for this attempt to establish connection.
Returns:
Connection settings that have been modified, and additional connection settings requested which are not provided in the input ConnSettingRequestMap.
Throws:
BadAuthException - If the inputs fail authentication.
com.simba.support.exceptions.ErrorException - If an error occurs.
See Also:
ConnSettingRequestMap, ConnSettingResponseMap

createArrayOf

IArray createArrayOf(java.lang.String typeName,
                     java.lang.Object[] elements)
                     throws com.simba.support.exceptions.ErrorException
Factory method for creating IArray objects. Note: When createArrayOf is used to create an array object that maps to a primitive data type, then it is implementation-defined whether the IArray object is an array of that primitive data type or an array of Object. Note: The JDBC driver is responsible for mapping the elements Object array to the default JDBC SQL type defined in java.sql.Types for the given class of Object. The default mapping is specified in Appendix B of the JDBC specification. If the resulting JDBC type is not the appropriate type for the given typeName then it is implementation defined whether an SQLException is thrown or the driver supports the resulting conversion.

Parameters:
typeName - The SQL name of the type the elements of the array map to. The typeName is a database-specific name which may be the name of a built-in type, a user-defined type or a standard SQL type supported by this database. This is the value returned by Array.getBaseTypeName.
elements - The elements that populate the returned object.
Returns:
an IArray object whose elements map to the specified SQL type.
Throws:
java.sql.SQLException - If a database access error occurs.
com.simba.support.exceptions.ErrorException


Copyright © 2006-2014 Simba Technologies Incorporated. All Rights Reserved.