Package org.eclipse.persistence.sessions

Class DatasourceLogin

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, CoreLogin<org.eclipse.persistence.internal.databaseaccess.Platform>, Login
    Direct Known Subclasses:
    DatabaseLogin, EISLogin, 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

      Fields 
      Modifier and Type Field Description
      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.
      static int CONCURRENT_READ_WRITE
      Reads and unit of work merges can occur concurrently.
      protected Connector connector
      Provide a little flexibility for connecting to a database
      protected org.eclipse.persistence.internal.databaseaccess.Platform platform
      Implementation of platform-specific behaviors.
      protected java.util.Properties properties
      Connection properties (e.g. user, password, and driver-specific settings)
      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.
      protected boolean usesExternalConnectionPooling
      True if we use an external connection pool such as WebLogic's JTS driver
      protected boolean usesExternalTransactionController
      True if we should use some external transaction service such as JTS.
      static java.lang.String versionString  

    • Constructor Summary

      Constructors 
      Constructor Description
      DatasourceLogin()
      PUBLIC: Create a new login.
      DatasourceLogin​(org.eclipse.persistence.internal.databaseaccess.Platform databasePlatform)
      ADVANCED: Create a new login for the given platform.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addSequence​(Sequence sequence)
      Add sequence corresponding to the name Don't use if the session is connected.
      DatasourceLogin clone()
      INTERNAL: Clone the login.
      java.lang.Object connectToDatasource​(org.eclipse.persistence.internal.databaseaccess.Accessor accessor, Session session)
      INTERNAL: Connect to the datasource, and return the driver level connection object.
      void dontUseExternalConnectionPooling()
      PUBLIC: Do not use external connection pooling.
      void dontUseExternalTransactionController()
      PUBLIC: Let EclipseLink 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.
      org.eclipse.persistence.internal.databaseaccess.Platform getDatasourcePlatform()
      PUBLIC: Return the datasource platform specific information.
      Sequence getDefaultSequence()
      Get default sequence
      Sequence getDefaultSequenceToWrite()
      INTERNAL: Used only for writing the login into XML or Java.
      java.lang.String getPassword()
      Return the password.
      DatabasePlatform getPlatform()
      INTERNAL: Return the database platform specific information.
      java.lang.String getPlatformClassName()
      INTERNAL: Return the name of the database platform class.
      java.util.Properties getProperties()
      INTERNAL: The properties are additional, driver-specific, connection information to be passed to the driver.
      java.lang.Object getProperty​(java.lang.String name)
      PUBLIC: The properties are additional, driver-specific, connection information to be passed to the driver.
      protected org.eclipse.persistence.internal.security.SecurableObjectHolder getSecurableObjectHolder()
      INTERNAL: Return the encryption securable holder.
      Sequence getSequence​(java.lang.String seqName)
      Get sequence corresponding to the name
      java.util.Map getSequences()
      Returns a map of sequence names to Sequences (may be null).
      java.util.Map getSequencesToWrite()
      INTERNAL: Used only for writing the login into XML or Java.
      java.lang.String getTableQualifier()
      PUBLIC: Return the qualifier for the all of the tables referenced by EclipseLink.
      java.lang.String getUserName()
      PUBLIC: The user name is the database login name.
      static java.lang.String getVersion()
      PUBLIC: Return the EclipseLink version.
      boolean isConnectionHealthValidatedOnError()
      PUBLIC: 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)
      PUBLIC: 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)
      PUBLIC: Set the connector that will instantiate the connection.
      void setDatasourcePlatform​(org.eclipse.persistence.internal.databaseaccess.Platform platform)
      PUBLIC: Set the database platform specific information.
      void setDefaultNullValue​(java.lang.Class type, java.lang.Object value)
      PUBLIC: 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 setPlatform​(org.eclipse.persistence.internal.databaseaccess.Platform platform)
      INTERNAL: Set the database platform specific information.
      void setPlatformClassName​(java.lang.String platformClassName)
      INTERNAL: Set the name of the Platform to be used.
      void setPlatformClassName​(java.lang.String platformClassName, java.lang.ClassLoader loader)
      INTERNAL: Set the name of the Platform to be created using the passed in class loader.
      void setProperties​(java.util.Properties properties)
      PUBLIC: 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)
      PUBLIC: Some JDBC drivers require additional, driver-specific, properties.
      void setSequences​(java.util.Map sequences)
      INTERNAL: Used only for reading the login from XML.
      void setTableQualifier​(java.lang.String qualifier)
      PUBLIC: Set the default qualifier for all tables.
      void setTimestampQuery​(ValueReadQuery timestampQuery)
      PUBLIC: Override the default query for returning a timestamp from the server.
      void setUserName​(java.lang.String name)
      PUBLIC: The user name is the database login name.
      void setUsesExternalConnectionPooling​(boolean usesExternalConnectionPooling)
      PUBLIC: Return whether EclipseLink uses some external connection pooling service such as a JDBC 2.0 driver.
      void setUsesExternalTransactionController​(boolean usesExternalTransactionController)
      PUBLIC: Return whether EclipseLink uses some external transaction service such as JTS.
      boolean shouldAllowConcurrentReadWrite()
      INTERNAL: Used for cache isolation.
      boolean shouldSynchronizedReadOnWrite()
      INTERNAL: Used for cache isolation.
      boolean shouldSynchronizeObjectLevelReadWrite()
      INTERNAL: Used for Cache Isolation.
      boolean shouldSynchronizeObjectLevelReadWriteDatabase()
      INTERNAL: Used for Cache Isolation.
      boolean shouldSynchronizeWrites()
      INTERNAL: Used for Cache Isolation.
      boolean shouldUseExternalConnectionPooling()
      PUBLIC: Return whether EclipseLink uses some external connection pooling (e.g.
      boolean shouldUseExternalTransactionController()
      PUBLIC: Return whether EclipseLink uses some external transaction service such as JTS.
      java.lang.String toString()
      PUBLIC: Print all of the connection information.
      void useExternalConnectionPooling()
      PUBLIC: Use external connection pooling.
      void useExternalTransactionController()
      PUBLIC: Use an external transaction controller such as a JTS service
      void usePlatform​(org.eclipse.persistence.internal.databaseaccess.Platform platform)
      ADVANCED: Set the database platform to be custom platform.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • versionString

        public static java.lang.String versionString

      • properties

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

      • platform

        protected org.eclipse.persistence.internal.databaseaccess.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:
        Constant Field Values

      • SYNCHRONIZED_WRITE

        public static final int SYNCHRONIZED_WRITE
        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
        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
        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
        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()
        PUBLIC: Create a new login.

      • DatasourceLogin

        public DatasourceLogin​(org.eclipse.persistence.internal.databaseaccess.Platform databasePlatform)
        ADVANCED: Create a new login for the given platform.

    • Method Detail

      • getSecurableObjectHolder

        protected org.eclipse.persistence.internal.security.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 java.lang.Object

      • connectToDatasource

        public java.lang.Object connectToDatasource​(org.eclipse.persistence.internal.databaseaccess.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 org.eclipse.persistence.internal.databaseaccess.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<org.eclipse.persistence.internal.databaseaccess.Platform>
        Specified by:
        getDatasourcePlatform in interface Login

      • getProperties

        public java.util.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 java.lang.Object getProperty​(java.lang.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 java.lang.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 java.lang.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 java.lang.String getVersion()
        PUBLIC: Return the EclipseLink version.
        Returns:
        version of EclipseLink

      • removeProperty

        public void removeProperty​(java.lang.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​(java.lang.Class type,
                                java.lang.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​(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

      • setPlatform

        public void setPlatform​(org.eclipse.persistence.internal.databaseaccess.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​(org.eclipse.persistence.internal.databaseaccess.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 java.lang.String getPlatformClassName()
        INTERNAL: Return the name of the database platform class.

      • setPlatformClassName

        public void setPlatformClassName​(java.lang.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​(java.lang.String platformClassName,
                                 java.lang.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:
        setPlatformClassName(String platformClassName)

      • usePlatform

        public void usePlatform​(org.eclipse.persistence.internal.databaseaccess.Platform platform)
        ADVANCED: Set the database platform to be custom platform.

      • setProperties

        public void setProperties​(java.util.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​(java.lang.String propertyName,
                        java.lang.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​(java.lang.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​(java.lang.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:
        useExternalConnectionPooling()

      • dontUseExternalTransactionController

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

      • 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

      • toString

        public java.lang.String toString()
        PUBLIC: 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 Don't use if the session is connected.

      • 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. 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 java.util.Map getSequencesToWrite()
        INTERNAL: Used only for writing the login into XML or Java.

      • setSequences

        public void setSequences​(java.util.Map sequences)
        INTERNAL: Used only for reading the login from XML.