Module org.eclipse.persistence.core
Package org.eclipse.persistence.sessions

Class DatasourceLogin

java.lang.Object
org.eclipse.persistence.sessions.DatasourceLogin
All Implemented Interfaces:
Serializable, Cloneable, CoreLogin<Platform>, Login
Direct Known Subclasses:
DatabaseLogin, EISLogin, XMLLogin
public abstract class DatasourceLogin extends Object implements Login, Serializable, 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:

  • Field Details

    • versionString

      public static String versionString

    • properties

      protected Properties properties
      Connection properties (e.g. user, password, and driver-specific settings)

    • platform

      protected Platform platform
      Implementation of platform-specific behaviors.

    • connector

      protected Connector connector
      Provide a little flexibility for connecting to a database

    • usesExternalConnectionPooling

      protected boolean usesExternalConnectionPooling
      True if we use an external connection pool such as WebLogic's JTS driver

    • usesExternalTransactionController

      protected boolean usesExternalTransactionController
      True if we should use some external transaction service such as JTS.

    • cacheTransactionIsolation

      protected int cacheTransactionIsolation
      By default concurrency is optimized and the cache is not locked during reads or writes, This allows for 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 scenario for two unit of works to merge changes different than the database although highly unlikely and if occurred is the entire purpose of locking. This property allows for the isolation level of changes to the cache to be configured for sever situation and it is not suggest that this be changed.

    • CONCURRENT_READ_WRITE

      public static final int CONCURRENT_READ_WRITE
      Reads and unit of work merges can occur concurrently.
      See Also:

    • SYNCHRONIZED_WRITE

      public static final int SYNCHRONIZED_WRITE
      Reads can occur concurrently but unit of work merges will be serialized.
      See Also:

    • SYNCHRONIZED_READ_ON_WRITE

      public static final int SYNCHRONIZED_READ_ON_WRITE
      Reads and unit of work merges will be serialized.
      See Also:

    • SYNCRONIZED_OBJECT_LEVEL_READ_WRITE

      public static final 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.
      See Also:

    • SYNCRONIZED_OBJECT_LEVEL_READ_WRITE_DATABASE

      public static final 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.
      See Also:

  • Constructor Details

    • DatasourceLogin

      protected DatasourceLogin()
      PUBLIC: Create a new login.

    • DatasourceLogin

      protected DatasourceLogin(Platform databasePlatform)
      ADVANCED: Create a new login for the given platform.

  • Method Details

    • getSecurableObjectHolder

      protected SecurableObjectHolder getSecurableObjectHolder()
      INTERNAL: Return the encryption securable holder. Lazy initialize to handle serialization.

    • clone

      public DatasourceLogin clone()
      INTERNAL: Clone the login. This also clones the platform as it is internal to the login.
      Specified by:
      clone in interface Login
      Overrides:
      clone in class Object

    • connectToDatasource

      public Object connectToDatasource(Accessor accessor, Session session) throws DatabaseException
      INTERNAL: Connect to the datasource, and return the driver level connection object.
      Specified by:
      connectToDatasource in interface Login
      Throws:
      DatabaseException

    • 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 scenario for two unit of works to merge changes different than the database although highly unlikely and if occurred 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 while a unit of work is in merge

    • getConnector

      public Connector getConnector()
      ADVANCED: Return the connector that will instantiate the connection.

    • getPlatform

      public DatabasePlatform getPlatform()
      INTERNAL: Return the database platform specific information. This allows EclipseLink to configure certain advanced features for the database desired. NOTE: this must only be used for relational specific usage and will not work for non-relational datasources.
      Specified by:
      getPlatform in interface Login

    • getDatasourcePlatform

      public Platform getDatasourcePlatform()
      PUBLIC: Return the datasource platform specific information. This allows EclipseLink to configure certain advanced features for the datasource desired.
      Specified by:
      getDatasourcePlatform in interface CoreLogin<Platform>
      Specified by:
      getDatasourcePlatform in interface Login

    • getProperties

      public Properties getProperties()
      INTERNAL: 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).

    • getProperty

      public Object getProperty(String name)
      PUBLIC: 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

    • getTableQualifier

      public String getTableQualifier()
      PUBLIC: Return the qualifier for the all of the tables referenced by EclipseLink. 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 String getUserName()
      PUBLIC: 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

    • isConnectionHealthValidatedOnError

      public boolean isConnectionHealthValidatedOnError()
      PUBLIC: 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 EclipseLink 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 EclipseLink from being able to retry queries in the case of database failure.
      Specified by:
      isConnectionHealthValidatedOnError in interface Login

    • getVersion

      public static String getVersion()
      PUBLIC: Return the EclipseLink version.
      Returns:
      version of EclipseLink

    • removeProperty

      public void removeProperty(String propertyName)
      PUBLIC: Some drivers don't like the "user" and "password" properties. They can be removed with this method, or by using setUserName(null) / setPassword(null)

    • 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 scenario for two unit of works to merge changes different than the database although highly unlikely and if occurred 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 while a unit of work is in merge

    • setConnector

      public void setConnector(Connector connector)
      PUBLIC: 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(Class<?> type, Object value)
      PUBLIC: The default value to substitute for database NULLs can be configured on a per-class basis. Example: login.setDefaultNullValue(long.class, Long.valueOf(0))

    • setPassword

      public void setPassword(String password)
      Set the password.
      Specified by:
      setPassword in interface Login

    • getPassword

      public String getPassword()
      Return the password. It will be encrypted.
      Specified by:
      getPassword in interface Login

    • setEncryptedPassword

      public void setEncryptedPassword(String password)
      Set the encrypted password.

    • setEncryptionClassName

      public void setEncryptionClassName(String encryptionClassName)
      Sets the encryption class name

    • setPlatform

      public void setPlatform(Platform platform)
      INTERNAL: Set the database platform specific information. This allows EclipseLink to configure certain advanced features for the database desired.
      Specified by:
      setPlatform in interface Login

    • setDatasourcePlatform

      public void setDatasourcePlatform(Platform platform)
      PUBLIC: Set the database platform specific information. This allows EclipseLink to configure certain advanced features for the database desired.
      Specified by:
      setDatasourcePlatform in interface Login

    • getPlatformClassName

      public String getPlatformClassName()
      INTERNAL: Return the name of the database platform class.

    • setPlatformClassName

      public void setPlatformClassName(String platformClassName) throws ValidationException
      INTERNAL: Set the name of the Platform to be used. Creates a new instance of the specified Class.
      Throws:
      ValidationException

    • setPlatformClassName

      public void setPlatformClassName(String platformClassName, ClassLoader loader) throws ValidationException
      INTERNAL: Set the name of the Platform to be created using the passed in class loader. If no class loader is passed in, of if an exception is thrown, call the setPlatformClassName method with no classloader.
      Throws:
      ValidationException
      See Also:

    • usePlatform

      public void usePlatform(Platform platform)
      ADVANCED: Set the database platform to be custom platform.

    • setProperties

      public void setProperties(Properties properties)
      PUBLIC: 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(String propertyName, Object propertyValue)
      PUBLIC: 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

    • setTableQualifier

      public void setTableQualifier(String qualifier)
      PUBLIC: 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)
      PUBLIC: Override the default query for returning a timestamp from the server.

    • setUserName

      public void setUserName(String name)
      PUBLIC: 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)
      PUBLIC: Return whether EclipseLink uses some external connection pooling service such as a JDBC 2.0 driver.

    • setUsesExternalTransactionController

      public void setUsesExternalTransactionController(boolean usesExternalTransactionController)
      PUBLIC: Return whether EclipseLink uses some external transaction service such as JTS.

    • dontUseExternalConnectionPooling

      public void dontUseExternalConnectionPooling()
      PUBLIC: Do not use external connection pooling. This is appropriate if using regular EclipseLink connection pooling and regular JDBC drivers.
      See Also:

    • dontUseExternalTransactionController

      public void dontUseExternalTransactionController()
      PUBLIC: Let EclipseLink control transactions instead of some external transaction service such as JTS.
      See Also:

    • shouldAllowConcurrentReadWrite

      public boolean shouldAllowConcurrentReadWrite()
      INTERNAL: Used for cache isolation.
      Specified by:
      shouldAllowConcurrentReadWrite in interface Login

    • shouldSynchronizedReadOnWrite

      public boolean shouldSynchronizedReadOnWrite()
      INTERNAL: Used for cache isolation.
      Specified by:
      shouldSynchronizedReadOnWrite in interface Login

    • shouldSynchronizeWrites

      public boolean shouldSynchronizeWrites()
      INTERNAL: Used for Cache Isolation. Causes EclipseLink to lock at the class level on cache updates.
      Specified by:
      shouldSynchronizeWrites in interface Login

    • shouldSynchronizeObjectLevelReadWrite

      public boolean shouldSynchronizeObjectLevelReadWrite()
      INTERNAL: Used for Cache Isolation. Causes EclipseLink to lock at the object level on cache updates and cache access.
      Specified by:
      shouldSynchronizeObjectLevelReadWrite in interface Login

    • shouldSynchronizeObjectLevelReadWriteDatabase

      public boolean shouldSynchronizeObjectLevelReadWriteDatabase()
      INTERNAL: Used for Cache Isolation. Causes EclipseLink to lock at the object level on cache updates and cache access, based on database transaction.
      Specified by:
      shouldSynchronizeObjectLevelReadWriteDatabase in interface Login

    • shouldUseExternalConnectionPooling

      public boolean shouldUseExternalConnectionPooling()
      PUBLIC: Return whether EclipseLink uses some external connection pooling (e.g. WebLogic's JTS driver).
      Specified by:
      shouldUseExternalConnectionPooling in interface Login
      See Also:

    • shouldUseExternalTransactionController

      public boolean shouldUseExternalTransactionController()
      PUBLIC: Return whether EclipseLink uses some external transaction service such as JTS.
      Specified by:
      shouldUseExternalTransactionController in interface Login
      See Also:

    • useExternalConnectionPooling

      public void useExternalConnectionPooling()
      PUBLIC: Use external connection pooling.
      See Also:

    • useExternalTransactionController

      public void useExternalTransactionController()
      PUBLIC: Use an external transaction controller such as a JTS service
      See Also:

    • toString

      public String toString()
      PUBLIC: Print all of the connection information.
      Overrides:
      toString in class 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 Don't use if the session is connected.

    • getSequence

      public Sequence getSequence(String seqName)
      Get sequence corresponding to the name

    • getSequences

      public Map<String,Sequence> getSequences()
      Returns a map of sequence names to Sequences (may be null).

    • removeSequence

      public Sequence removeSequence(String seqName)
      Remove sequence corresponding to name. Doesn't remove default sequence. Don't use if the session is connected.

    • removeAllSequences

      public void removeAllSequences()
      Remove all sequences but the default one.

    • getDefaultSequenceToWrite

      public Sequence getDefaultSequenceToWrite()
      INTERNAL: Used only for writing the login into XML or Java.

    • getSequencesToWrite

      public Map<String,Sequence> getSequencesToWrite()
      INTERNAL: Used only for writing the login into XML or Java.

    • setSequences

      public void setSequences(Map<String,Sequence> sequences)
      INTERNAL: Used only for reading the login from XML.