oracle.toplink.sessions
Class DatasourceLogin

java.lang.Object
  oracle.toplink.sessions.DatasourceLogin

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Login

Direct Known Subclasses:

DatabaseLogin, EISLogin, SDKLogin, XMLLogin

public abstract class DatasourceLogin
extends java.lang.Object
implements Login, java.io.Serializable, java.lang.Cloneable

Purpose: Hold the configuration information necessary to connect to a datasource.

Description: This is an abstract class that defines the common datasource independent connection configuration. It is extended to support specific datasources such as JDBC, JCA, XML, etc.

See Also:

Serialized Form

Field Summary

static int	CONCURRENT_READ_WRITE Reads and unit of work merges can occur concurrently.
static int	SYNCHRONIZED_READ_ON_WRITE Reads and unit of work merges will be serialized.
static int	SYNCHRONIZED_WRITE Reads can occur concurrently but unit of work merges will be serialized.
static int	SYNCRONIZED_OBJECT_LEVEL_READ_WRITE Writes to the cache (merge, object build/refresh will be synchronized as will cache access (cloning) based on when access is required.
static int	SYNCRONIZED_OBJECT_LEVEL_READ_WRITE_DATABASE Writes to the cache (merge, object build/refresh will be synchronized as will cache access (cloning) based on database transaction.
static java.lang.String	versionString

Constructor Summary

DatasourceLogin()
Create a new login.

DatasourceLogin(oracle.toplink.internal.databaseaccess.Platform databasePlatform)
ADVANCED: Create a new login for the given platform.

Method Summary

void	addSequence(Sequence sequence) Add sequence corresponding to the name
void	dontUseExternalConnectionPooling() Do not use external connection pooling.
void	dontUseExternalTransactionController() Let TopLink control transactions instead of some external transaction service such as JTS.
int	getCacheTransactionIsolation() ADVANCED: By default concurrency is optimized and the cache is not locked more than required during reads or writes, This allows for virtual concurrent reading and writing and should never cause any problems.
Connector	getConnector() ADVANCED: Return the connector that will instantiate the connection.
oracle.toplink.internal.databaseaccess.Platform	getDatasourcePlatform() Return the datasource platform specific information.
Sequence	getDefaultSequence() Get default sequence
java.lang.String	getPassword() Return the password.
java.lang.Object	getProperty(java.lang.String name) The properties are additional, driver-specific, connection information to be passed to the driver.
Sequence	getSequence(java.lang.String seqName) Get sequence corresponding to the name
int	getSequencePreallocationSize() Deprecated. use getDefaultSequence().getPreallocationSize() instead
java.util.Map	getSequences() Returns a map of sequence names to Sequences (may be null).
java.lang.String	getTableQualifier() Return the qualifier for the all of the tables referenced by TopLink.
java.lang.String	getUserName() The user name is the database login name.
static java.lang.String	getVersion() Return the TopLink version.
boolean	isConnectionHealthValidatedOnError() This value defaults to false when not on a DatabaseLogin as the functionality has not been implemented for other datasource type.
void	removeAllSequences() Remove all sequences but the default one.
void	removeProperty(java.lang.String propertyName) Some drivers don't like the "user" and "password" properties.
Sequence	removeSequence(java.lang.String seqName) Remove sequence corresponding to name.
void	setCacheTransactionIsolation(int cacheTransactionIsolation) ADVANCED: By default concurrency is optimized and the cache is not locked more than required during reads or writes, This allows for virtual concurrent reading and writing and should never cause any problems.
void	setConnector(Connector connector) Set the connector that will instantiate the connection.
void	setDatasourcePlatform(oracle.toplink.internal.databaseaccess.Platform platform) Set the database platform specific information.
void	setDefaultNullValue(java.lang.Class type, java.lang.Object value) The default value to substitute for database NULLs can be configured on a per-class basis.
void	setDefaultSequence(Sequence sequence) Set default sequence
void	setEncryptedPassword(java.lang.String password) Set the encrypted password.
void	setEncryptionClassName(java.lang.String encryptionClassName) Sets the encryption class name
void	setPassword(java.lang.String password) Set the password.
void	setProperties(java.util.Properties properties) The properties are additional, driver-specific, connection information to be passed to the JDBC driver.
void	setProperty(java.lang.String propertyName, java.lang.Object propertyValue) Some JDBC drivers require additional, driver-specific, properties.
void	setSelectSequenceNumberQuery(ValueReadQuery selectSequenceNumberQuery) Deprecated. use ((QuerySequence)getDefaultSequence()).setSelectQuery(ValueReadQuery) instead
void	setSequencePreallocationSize(int size) Deprecated. use getDefaultSequence().setPreallocationSize(int) instead
void	setTableQualifier(java.lang.String qualifier) Set the default qualifier for all tables.
void	setTimestampQuery(ValueReadQuery timestampQuery) Override the default query for returning a timestamp from the server.
void	setUpdateSequenceQuery(DataModifyQuery updateSequenceNumberQuery) Deprecated. use ((QuerySequence)getDefaultSequence()).setUpdateQuery(DataModifyQuery) instead
void	setUserName(java.lang.String name) The user name is the database login name.
void	setUsesExternalConnectionPooling(boolean usesExternalConnectionPooling) Return whether TopLink uses some external connection pooling service such as a JDBC 2.0 driver.
void	setUsesExternalTransactionController(boolean usesExternalTransactionController) Return whether TopLink uses some external transaction service such as JTS.
boolean	shouldUseExternalConnectionPooling() Return whether TopLink uses some external connection pooling (e.g.
boolean	shouldUseExternalTransactionController() Return whether TopLink uses some external transaction service such as JTS.
java.lang.String	toString() Print all of the connection information.
void	useExternalConnectionPooling() Use external connection pooling.
void	useExternalTransactionController() Use an external transaction controller such as a JTS service
void	usePlatform(oracle.toplink.internal.databaseaccess.Platform platform) ADVANCED: Set the database platform to be custom platform.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

versionString

public static java.lang.String versionString

CONCURRENT_READ_WRITE

public static final int CONCURRENT_READ_WRITE

Description copied from class: DatasourceLogin

Reads and unit of work merges can occur concurrently.

See Also:

Constant Field Values

SYNCHRONIZED_WRITE

public static final int SYNCHRONIZED_WRITE

Description copied from class: DatasourceLogin

Reads can occur concurrently but unit of work merges will be serialized.

See Also:

Constant Field Values

SYNCHRONIZED_READ_ON_WRITE

public static final int SYNCHRONIZED_READ_ON_WRITE

Description copied from class: DatasourceLogin

Reads and unit of work merges will be serialized.

See Also:

Constant Field Values

SYNCRONIZED_OBJECT_LEVEL_READ_WRITE

public static final int SYNCRONIZED_OBJECT_LEVEL_READ_WRITE

Description copied from class: DatasourceLogin

Writes to the cache (merge, object build/refresh will be synchronized as will cache access (cloning) based on when access is required.

See Also:

Constant Field Values

SYNCRONIZED_OBJECT_LEVEL_READ_WRITE_DATABASE

public static final int SYNCRONIZED_OBJECT_LEVEL_READ_WRITE_DATABASE

Description copied from class: DatasourceLogin

Writes to the cache (merge, object build/refresh will be synchronized as will cache access (cloning) based on database transaction.

See Also:

Constant Field Values

Constructor Detail

DatasourceLogin

public DatasourceLogin()

Create a new login.

DatasourceLogin

public DatasourceLogin(oracle.toplink.internal.databaseaccess.Platform databasePlatform)

ADVANCED: Create a new login for the given platform.

Method Detail

getCacheTransactionIsolation

public int getCacheTransactionIsolation()

ADVANCED: By default concurrency is optimized and the cache is not locked more than required during reads or writes, This allows for virtual concurrent reading and writing and should never cause any problems. If the application uses no form of locking the last unit of work to merge changes will win, with no locking it is possible only under this senerio for two unit of works to merge changes different than the database although highly unlikely and if occured is the entire purpose of locking and locking is the suggested solution if this is a problem. This property allows for the isolation level of changes to the cache to be configured for sever situations and it is not suggest that this be changed.

Setting are:

• ConcurrentReadWrite - default
• SynchronizedWrite - only allow a single writer (i.e. unit of work merge) to the cache at once
• SynchronizedReadOnWrite - do not allow reading or other unit of work merge ehile a unit of work is in merge

getConnector

public Connector getConnector()

ADVANCED: Return the connector that will instantiate the connection.

getDatasourcePlatform

public oracle.toplink.internal.databaseaccess.Platform getDatasourcePlatform()

Return the datasource platform specific information. This allows TopLink to configure certain advanced features for the datasource desired.

Specified by:

getDatasourcePlatform in interface Login

getProperty

public java.lang.Object getProperty(java.lang.String name)

The properties are additional, driver-specific, connection information to be passed to the driver.

NOTE: Do not set the password directly by getting the properties and setting the "password" property directly. Use the method DatabaseLogin.setPassword(String).

Specified by:

getProperty in interface Login

getSequencePreallocationSize

public int getSequencePreallocationSize()

Deprecated. use getDefaultSequence().getPreallocationSize() instead

OBSOLETE: TopLink supports sequence number preallocation. This improves the performance and concurrency of inserts by selecting new object IDs in batches and caching them on the client. The preallocation size can be configured, and the default is 50. By default a sequence table is used. Using a sequence table is recommended as it supports preallocation. (Native sequencing on Sybase/SQL Server/Informix does not support preallocation. Preallocation can be supported on Oracle by setting the increment size of the SEQUENCE object to match the preallocation size.)

getTableQualifier

public java.lang.String getTableQualifier()

Return the qualifier for the all of the tables referenced by TopLink. This can be the creator of the table or database name the table exists on. This is required by some databases such as Oracle and DB2. This should only be used if all of the tables have the same qualifier. It can also be set on each descriptor when the table name is specified.

Specified by:

getTableQualifier in interface Login

getUserName

public java.lang.String getUserName()

The user name is the database login name. Some databases do not require a user name or the user is obtained from the OS, in this case the user name not be specified.

Specified by:

getUserName in interface Login

getVersion

public static java.lang.String getVersion()

Return the TopLink version.

Returns:

version of TopLink

removeProperty

public void removeProperty(java.lang.String propertyName)

Some drivers don't like the "user" and "password" properties. They can be removed with this method.

setCacheTransactionIsolation

public void setCacheTransactionIsolation(int cacheTransactionIsolation)

ADVANCED: By default concurrency is optimized and the cache is not locked more than required during reads or writes, This allows for virtual concurrent reading and writing and should never cause any problems. If the application uses no form of locking the last unit of work to merge changes will win, with no locking it is possible only under this senerio for two unit of works to merge changes different than the database although highly unlikely and if occured is the entire purpose of locking and locking is the suggested solution if this is a problem. This property allows for the isolation level of changes to the cache to be configured for sever situations and it is not suggest that this be changed.

Setting are:

• ConcurrentReadWrite - default
• SynchronizedWrite - only allow a single writer (i.e. unit of work merge) to the cache at once
• SynchronizedReadOnWrite - do not allow reading or other unit of work merge ehile a unit of work is in merge

setConnector

public void setConnector(Connector connector)

Set the connector that will instantiate the connection. As an example, to use a JNDI-supplied DataSource, use code something like the following:

session.getLogin().setConnector(new JNDIConnector(context, dataSourceName));
session.login();

where the context is an instance of a javax.naming.Context and the dataSourceName refers to the name of the DataSource within the context.

setDefaultNullValue

public void setDefaultNullValue(java.lang.Class type,
                                java.lang.Object value)

The default value to substitute for database NULLs can be configured on a per-class basis. Example: login.setDefaultNullValue(long.class, new Long(0))

setPassword

public void setPassword(java.lang.String password)

Set the password.

Specified by:

setPassword in interface Login

getPassword

public java.lang.String getPassword()

Return the password. It will be encrypted.

Specified by:

getPassword in interface Login

setEncryptedPassword

public void setEncryptedPassword(java.lang.String password)

Set the encrypted password.

setEncryptionClassName

public void setEncryptionClassName(java.lang.String encryptionClassName)

Sets the encryption class name

setDatasourcePlatform

public void setDatasourcePlatform(oracle.toplink.internal.databaseaccess.Platform platform)

Set the database platform specific information. This allows TopLink to configure certain advanced features for the database desired.

Specified by:

setDatasourcePlatform in interface Login

usePlatform

public void usePlatform(oracle.toplink.internal.databaseaccess.Platform platform)

ADVANCED: Set the database platform to be custom platform.

setProperties

public void setProperties(java.util.Properties properties)

The properties are additional, driver-specific, connection information to be passed to the JDBC driver.

Specified by:

setProperties in interface Login

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.Object propertyValue)

Some JDBC drivers require additional, driver-specific, properties. Add the specified property to those to be passed to the JDBC driver.

Specified by:

setProperty in interface Login

setSelectSequenceNumberQuery

public void setSelectSequenceNumberQuery(ValueReadQuery selectSequenceNumberQuery)

Deprecated. use ((QuerySequence)getDefaultSequence()).setSelectQuery(ValueReadQuery) instead

OBSOLETE: Override the default query for reading the sequence numbers. This query must be a valid query that has one parameter, the sequence name. The query should only return the new value. It will be called after the sequence update query. If TopLink is using native sequencing, then the query must both update and return the new sequence value. Additionally, if TopLink is using native sequencing, the query should not define any parameters.

setSequencePreallocationSize

public void setSequencePreallocationSize(int size)

Deprecated. use getDefaultSequence().setPreallocationSize(int) instead

OBSOLETE: TopLink supports sequence number preallocation. This improves the performance and concurrency of inserts by selecting new object IDs in batches and caching them on the client. The preallocation size can be configured, and the default is 50. By default a sequence table is used. Using a sequence table is recommended as it supports preallocation. This MUST be 1 if native sequencing is used on Sybase, Informix, or SQL Server. This MUST match the SEQUENCE increment if Oracle native sequencing is used.

setTableQualifier

public void setTableQualifier(java.lang.String qualifier)

Set the default qualifier for all tables. This can be the creator of the table or database name the table exists on. This is required by some databases such as Oracle and DB2.

setTimestampQuery

public void setTimestampQuery(ValueReadQuery timestampQuery)

Override the default query for returning a timestamp from the server.

setUpdateSequenceQuery

public void setUpdateSequenceQuery(DataModifyQuery updateSequenceNumberQuery)

Deprecated. use ((QuerySequence)getDefaultSequence()).setUpdateQuery(DataModifyQuery) instead

OBSOLETE: Override the default query for updating sequence numbers. This allows another query to be used instead of the default, TopLink-generated, one. This is called before the sequence select query and only if TopLink is using non-native sequencing.

setUserName

public void setUserName(java.lang.String name)

The user name is the database login name. Some databases do not require a user name or the user is obtained from the OS, in this case this should not be specified.

Specified by:

setUserName in interface Login

setUsesExternalConnectionPooling

public void setUsesExternalConnectionPooling(boolean usesExternalConnectionPooling)

Return whether TopLink uses some external connection pooling service such as a JDBC 2.0 driver.

setUsesExternalTransactionController

public void setUsesExternalTransactionController(boolean usesExternalTransactionController)

Return whether TopLink uses some external transaction service such as JTS.

dontUseExternalConnectionPooling

public void dontUseExternalConnectionPooling()

Do not use external connection pooling. This is appropriate if using regular TopLink connection pooling and regular JDBC drivers.

See Also:

useExternalConnectionPooling()

dontUseExternalTransactionController

public void dontUseExternalTransactionController()

Let TopLink control transactions instead of some external transaction service such as JTS.

See Also:

useExternalTransactionController()

shouldUseExternalConnectionPooling

public boolean shouldUseExternalConnectionPooling()

Return whether TopLink uses some external connection pooling (e.g. WebLogic's JTS driver).

Specified by:

shouldUseExternalConnectionPooling in interface Login

See Also:

useExternalConnectionPooling(), dontUseExternalConnectionPooling()

shouldUseExternalTransactionController

public boolean shouldUseExternalTransactionController()

Return whether TopLink uses some external transaction service such as JTS.

Specified by:

shouldUseExternalTransactionController in interface Login

See Also:

useExternalTransactionController(), dontUseExternalTransactionController()

useExternalConnectionPooling

public void useExternalConnectionPooling()

Use external connection pooling.

See Also:

dontUseExternalConnectionPooling(), shouldUseExternalConnectionPooling()

useExternalTransactionController

public void useExternalTransactionController()

Use an external transaction controller such as a JTS service

See Also:

dontUseExternalTransactionController(), shouldUseExternalTransactionController()

toString

public java.lang.String toString()

Print all of the connection information.

Overrides:

toString in class java.lang.Object

getDefaultSequence

public Sequence getDefaultSequence()

Get default sequence

setDefaultSequence

public void setDefaultSequence(Sequence sequence)

Set default sequence

addSequence

public void addSequence(Sequence sequence)

Add sequence corresponding to the name

getSequence

public Sequence getSequence(java.lang.String seqName)

Get sequence corresponding to the name

getSequences

public java.util.Map getSequences()

Returns a map of sequence names to Sequences (may be null).

removeSequence

public Sequence removeSequence(java.lang.String seqName)

Remove sequence corresponding to name. Doesn't remove default sequence.

removeAllSequences

public void removeAllSequences()

Remove all sequences but the default one.

isConnectionHealthValidatedOnError

public boolean isConnectionHealthValidatedOnError()

This value defaults to false when not on a DatabaseLogin as the functionality has not been implemented for other datasource type. On an SQL Exception TopLink will ping the database to determine if the connection used can continue to be used for queries. This should have no impact on applications unless the user is using pessimistic locking queries with 'no wait' or are using a query timeout feature. If that is the case and the application is experiencing a performance impact from the health check then this feature can be turned off. Turning this feature off will prevent TopLink from being able to retry queries in the case of database failure.

Specified by:

isConnectionHealthValidatedOnError in interface Login