com.simba.dsi.core.impl
Class DSIConnection

java.lang.Object
  extended by com.simba.dsi.core.impl.DSIConnection
All Implemented Interfaces:
IConnection

public abstract class DSIConnection
extends java.lang.Object
implements IConnection

Abstract implementation of IConnection that initializes and manages connection properties.


Field Summary
protected  java.util.Map<java.lang.String,ClientInfoData> m_clientInfoProperties
          Stores the client info properties.
protected  AttributeDataMap m_connectionProperties
          AtrributeDataMap used for storage of connection properties.
protected  java.util.Map<java.lang.Long,ConnectionSettingInfo> m_connectionSettingInfo
          Stores the connection setting information used for OLEDB providers.
protected  ITransactionStateListener m_transactionListener
          The registered transaction state listener for the connection.
static java.lang.String REQ_INDICATOR
          Indicates that a connection setting is a 'required' connection setting.
 
Constructor Summary
protected DSIConnection(IEnvironment environment)
          Constructs a DSIConnection with default properties.
 
Method Summary
 void beginTransaction()
          Begins a transaction.
 void commit()
          Commits all transactions within this connection.
 IArray createArrayOf(java.lang.String typeName, java.lang.Object[] elements)
          Creates an IArray object.
 void createSavepoint(java.lang.String name)
          Create a savepoint with the given name.
protected abstract  void doReset()
          Called by reset() to rest subclass-specific state.
 java.lang.String getClientInfo(java.lang.String name)
          Gets a client info identified by the given property key.
 java.util.Map<java.lang.String,ClientInfoData> getClientInfoProperties()
          Gets all the client info properties.
 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()
          Retrieve name of the data source.
 java.util.Locale getLocale()
          Retrieves the connection-wide locale.
 com.simba.support.IMessageSource getMessageSource()
          Gets the message source.
protected  Variant getOptionalSetting(java.lang.String key, ConnSettingRequestMap requestMap)
          Get the optional setting.
 IEnvironment getParentEnvironment()
          Gets the parent environment for this connection.
 Variant getProperty(int propKey)
          Gets the DSI property as identified by the given property key.
protected  Variant getRequiredSetting(java.lang.String key, ConnSettingRequestMap requestMap)
          Get the required setting, and throw an exception if it isn't present.
 com.simba.support.IWarningListener getWarningListener()
          Gets the warning listener of this connection.
 boolean isAlive()
          Determine if the connection is still alive and connected.
protected  boolean isBeingReset()
           
 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(ClientInfoData clientInfoProperty)
          Sets or reset a client info property.
 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)
          Set 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.
protected  void verifyOptionalSetting(java.lang.String key, ConnSettingRequestMap requestMap, ConnSettingResponseMap responseMap)
          Verify that an optional setting is present in the request map.
protected  void verifyOptionalSetting(java.lang.String key, java.lang.String label, ConnSettingRequestMap requestMap, ConnSettingResponseMap responseMap)
          Verify that an optional setting is present in the request map.
protected  void verifyRequiredSetting(java.lang.String key, ConnSettingRequestMap requestMap, ConnSettingResponseMap responseMap)
          Verify that a required setting is present in the request map.
protected  void verifyRequiredSetting(java.lang.String key, java.lang.String label, ConnSettingRequestMap requestMap, ConnSettingResponseMap responseMap)
          Verify that a required setting is present in the request map.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.simba.dsi.core.interfaces.IConnection
close, connect, createStatement, disconnect, getConnectionLog, updateConnectionSettings
 

Field Detail

REQ_INDICATOR

public static final java.lang.String REQ_INDICATOR
Indicates that a connection setting is a 'required' connection setting.

See Also:
Constant Field Values

m_transactionListener

protected ITransactionStateListener m_transactionListener
The registered transaction state listener for the connection.


m_connectionProperties

protected AttributeDataMap m_connectionProperties
AtrributeDataMap used for storage of connection properties.


m_clientInfoProperties

protected java.util.Map<java.lang.String,ClientInfoData> m_clientInfoProperties
Stores the client info properties.


m_connectionSettingInfo

protected java.util.Map<java.lang.Long,ConnectionSettingInfo> m_connectionSettingInfo
Stores the connection setting information used for OLEDB providers.

Constructor Detail

DSIConnection

protected DSIConnection(IEnvironment environment)
                 throws com.simba.support.exceptions.ErrorException
Constructs a DSIConnection with default properties.

Parameters:
environment - The environment.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while setting up default property values.
Method Detail

beginTransaction

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

Specified by:
beginTransaction in interface IConnection
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while starting the transaction.

commit

public void commit()
            throws com.simba.support.exceptions.ErrorException
Commits all transactions within this connection.

Specified by:
commit in interface IConnection
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while committing the transaction.

createSavepoint

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

Specified by:
createSavepoint in interface IConnection
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.

setClientInfoProperty

public void setClientInfoProperty(ClientInfoData clientInfoProperty)
                           throws com.simba.support.exceptions.ErrorException
Sets or reset a client info property. Standard client properties are : If the property doesn't exist, it is added to the list. Otherwise, the previous values are overridden with the new ones.

Parameters:
clientInfoProperty - The property to define or redefine.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs..

getClientInfo

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

Specified by:
getClientInfo in interface IConnection
Parameters:
name - The client info property name.
Returns:
the client info property value.
Throws:
com.simba.support.exceptions.ErrorException - If the given name is not a valid client info property.

getClientInfoProperties

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

Specified by:
getClientInfoProperties in interface IConnection
Returns:
all the client info properties.

getConnectionSettingInfo

public 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.

Specified by:
getConnectionSettingInfo in interface IConnection
Returns:
Reference to map to filled in with settings accepted.

getCustomProperty

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

Specified by:
getCustomProperty in interface IConnection
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 the custom property can't be load.
See Also:
Variant

getCustomPropertyType

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

Specified by:
getCustomPropertyType in interface IConnection
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 the custom property can't be load.

getDataSourceName

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

Specified by:
getDataSourceName in interface IConnection
Returns:
Data source name.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

getLocale

public java.util.Locale getLocale()
Retrieves the connection-wide locale. The locale is set by setting the "LOCALE" connection key to a valid value.

Specified by:
getLocale in interface IConnection
Returns:
The locale for this connection. NOTE: This will return the driver locale if the connection locale was not set.
See Also:
DSIConnection#CONNECTION_LOCALE_KEY

setLocale

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

Specified by:
setLocale in interface IConnection
Parameters:
locale - The locale to set.

getMessageSource

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

Specified by:
getMessageSource in interface IConnection
Returns:
the message source.

getParentEnvironment

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

Specified by:
getParentEnvironment in interface IConnection
Returns:
The parent environment for this connection.

getProperty

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

Specified by:
getProperty in interface IConnection
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 error occurs.
See Also:
Variant

getWarningListener

public com.simba.support.IWarningListener getWarningListener()
Gets the warning listener of this connection.

Specified by:
getWarningListener in interface IConnection
Returns:
The warning listener of this connection.

isAlive

public 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.

Specified by:
isAlive in interface IConnection
Returns:
true if the connection is still valid and connected; false otherwise.

isCustomProperty

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

Specified by:
isCustomProperty in interface IConnection
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 an error occurs.

promptDialog

public 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).

Specified by:
promptDialog in interface IConnection
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

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

Specified by:
registerTransactionStateListener in interface IConnection
Parameters:
listener - The listener to register.

registerWarningListener

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

Specified by:
registerWarningListener in interface IConnection
Parameters:
listener - The listener to register with this IConnection.

releaseSavepoint

public 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.

Specified by:
releaseSavepoint in interface IConnection
Parameters:
name - The name of the Savepoint to release.
Throws:
com.simba.support.exceptions.ErrorException - if an error occurs while releasing the Savepoint.

reset

public 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.

Specified by:
reset in interface IConnection
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

rollback

public void rollback()
              throws com.simba.support.exceptions.ErrorException
Rolls back all transactions within this connection.

Specified by:
rollback in interface IConnection
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs while rolling back the transaction.

rollback

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

Specified by:
rollback in interface IConnection
Parameters:
name - The name of the Savepoint to roll back to.
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

setClientInfoProperty

public 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.

Specified by:
setClientInfoProperty in interface IConnection
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

public void setCustomProperty(int propKey,
                              Variant propValue)
                       throws 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 given WarningsHolder. 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.

Specified by:
setCustomProperty in interface IConnection
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:
com.simba.support.exceptions.ErrorException - If an error occurs.
See Also:
Variant

setInvokerAndClassLoader

public void setInvokerAndClassLoader(java.lang.Object invoker,
                                     java.lang.Object classLoader)
Set 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.

Specified by:
setInvokerAndClassLoader in interface IConnection
Parameters:
invoker - The Java object that invokes the first JNI class.
classLoader - The Java classLoader object from the invoking Java program.

setProperty

public 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.

Specified by:
setProperty in interface IConnection
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

public 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.

Specified by:
toNativeSQL in interface IConnection
Parameters:
sql - ODBC-formatted SQL statement
Returns:
Customized and optimized form of the input SQL statement
Throws:
com.simba.support.exceptions.ErrorException - If an error occurs.

doReset

protected abstract void doReset()
                         throws com.simba.support.exceptions.ErrorException
Called by reset() to rest subclass-specific state. Note: m_connectionProperties will already have been reset to DSIConnection's defaults.

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

getOptionalSetting

protected Variant getOptionalSetting(java.lang.String key,
                                     ConnSettingRequestMap requestMap)
Get the optional setting.

Parameters:
key - The name of the setting to retrieve.
requestMap - The connection settings generated by a call to UpdateConnectionSettings().
Returns:
The Variant representing the specified setting, or null if the setting isn't present.

getRequiredSetting

protected Variant getRequiredSetting(java.lang.String key,
                                     ConnSettingRequestMap requestMap)
                              throws BadAuthException
Get the required setting, and throw an exception if it isn't present.

Parameters:
key - The name of the setting to retrieve.
requestMap - The connection settings generated by a call to UpdateConnectionSettings().
Returns:
The Variant representing the specified setting.
Throws:
BadAuthException - If the required setting isn't present.

isBeingReset

protected boolean isBeingReset()
Returns:
True if currently in a call to DSIConnection.reset() on this object, false otherwise.

verifyOptionalSetting

protected void verifyOptionalSetting(java.lang.String key,
                                     ConnSettingRequestMap requestMap,
                                     ConnSettingResponseMap responseMap)
Verify that an optional setting is present in the request map.

Parameters:
key - The key to check for. This key is also used for the setting label.
requestMap - The collection of supplied settings.
responseMap - The collection of responses.

verifyOptionalSetting

protected void verifyOptionalSetting(java.lang.String key,
                                     java.lang.String label,
                                     ConnSettingRequestMap requestMap,
                                     ConnSettingResponseMap responseMap)
Verify that an optional setting is present in the request map.

Parameters:
key - The key to check for.
label - The label for the key.
requestMap - The collection of supplied settings.
responseMap - The collection of responses.

verifyRequiredSetting

protected void verifyRequiredSetting(java.lang.String key,
                                     ConnSettingRequestMap requestMap,
                                     ConnSettingResponseMap responseMap)
Verify that a required setting is present in the request map.

Parameters:
key - The key to check for. This key is also used for the setting label.
requestMap - The collection of supplied settings.
responseMap - The collection of responses.

verifyRequiredSetting

protected void verifyRequiredSetting(java.lang.String key,
                                     java.lang.String label,
                                     ConnSettingRequestMap requestMap,
                                     ConnSettingResponseMap responseMap)
Verify that a required setting is present in the request map.

Parameters:
key - The key to check for.
label - The label for the key.
requestMap - The collection of supplied settings.
responseMap - The collection of responses.

createArrayOf

public IArray createArrayOf(java.lang.String typeName,
                            java.lang.Object[] elements)
                     throws com.simba.support.exceptions.ErrorException
Creates an IArray object.

Specified by:
createArrayOf in interface IConnection
Parameters:
typeName - The SQL name of the type for the most nested element of the array.
elements - The elements that populate the returned object.
Returns:
an IArray object whose elements map to the specified SQL type.
Throws:
com.simba.support.exceptions.ErrorException - If an unexpected error occurs.


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