Package org.datanucleus.store.rdbms.datasource.dbcp2.cpdsadapter

Class DriverAdapterCPDS

  • All Implemented Interfaces:
    java.io.Serializable, javax.naming.Referenceable, javax.naming.spi.ObjectFactory, javax.sql.CommonDataSource, javax.sql.ConnectionPoolDataSource
    public class DriverAdapterCPDS
extends java.lang.Object
implements javax.sql.ConnectionPoolDataSource, javax.naming.Referenceable, java.io.Serializable, javax.naming.spi.ObjectFactory

    An adapter for JDBC drivers that do not include an implementation of ConnectionPoolDataSource, but still include a DriverManager implementation. ConnectionPoolDataSources are not used within general applications. They are used by DataSource implementations that pool Connections, such as SharedPoolDataSource. A J2EE container will normally provide some method of initializing the ConnectionPoolDataSource whose attributes are presented as bean getters/setters and then deploying it via JNDI. It is then available as a source of physical connections to the database, when the pooling DataSource needs to create a new physical connection.

    Although normally used within a JNDI environment, the DriverAdapterCPDS can be instantiated and initialized as any bean and then attached directly to a pooling DataSource. Jdbc2PoolDataSource can use the ConnectionPoolDataSource with or without the use of JNDI.

    The DriverAdapterCPDS also provides PreparedStatement pooling which is not generally available in jdbc2 ConnectionPoolDataSource implementation, but is addressed within the jdbc3 specification. The PreparedStatement pool in DriverAdapterCPDS has been in the dbcp package for some time, but it has not undergone extensive testing in the configuration used here. It should be considered experimental and can be toggled with the poolPreparedStatements attribute.

    The package documentation contains an example using catalina and JNDI. The datasources package documentation shows how to use DriverAdapterCPDS as a source for Jdbc2PoolDataSource without the use of JNDI.

    Since:
    2.0
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      DriverAdapterCPDS()
      Default no-arg constructor for Serialization

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void assertInitializationAllowed()
      Throws an IllegalStateException, if a PooledConnection has already been requested.
      private boolean getBooleanContentString​(javax.naming.RefAddr ra)  
      java.util.Properties getConnectionProperties()
      Gets the connection properties passed to the JDBC driver.
      java.lang.String getDescription()
      Gets the value of description.
      java.lang.String getDriver()
      Gets the driver class name.
      private int getIntegerStringContent​(javax.naming.RefAddr ra)  
      int getLoginTimeout()
      Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
      java.io.PrintWriter getLogWriter()
      Gets the log writer for this data source.
      int getMaxIdle()
      Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
      int getMaxPreparedStatements()
      Gets the maximum number of prepared statements.
      int getMinEvictableIdleTimeMillis()
      Gets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
      int getNumTestsPerEvictionRun()
      Gets the number of statements to examine during each run of the idle object evictor thread (if any.)
      java.lang.Object getObjectInstance​(java.lang.Object refObj, javax.naming.Name name, javax.naming.Context context, java.util.Hashtable<?,​?> env)
      Implements ObjectFactory to create an instance of this class
      java.util.logging.Logger getParentLogger()  
      java.lang.String getPassword()
      Gets the value of password for the default user.
      char[] getPasswordCharArray()
      Gets the value of password for the default user.
      javax.sql.PooledConnection getPooledConnection()
      Attempts to establish a database connection using the default user and password.
      javax.sql.PooledConnection getPooledConnection​(java.lang.String pooledUserName, java.lang.String pooledUserPassword)
      Attempts to establish a database connection.
      javax.naming.Reference getReference()
      Implements Referenceable.
      private java.lang.String getStringContent​(javax.naming.RefAddr ra)  
      long getTimeBetweenEvictionRunsMillis()
      Gets the number of milliseconds to sleep between runs of the idle object evictor thread.
      java.lang.String getUrl()
      Gets the value of url used to locate the database for this datasource.
      java.lang.String getUser()
      Gets the value of default user (login or user name).
      boolean isAccessToUnderlyingConnectionAllowed()
      Returns the value of the accessToUnderlyingConnectionAllowed property.
      private boolean isNotEmpty​(javax.naming.RefAddr ra)  
      boolean isPoolPreparedStatements()
      Whether to toggle the pooling of PreparedStatements
      void setAccessToUnderlyingConnectionAllowed​(boolean allow)
      Sets the value of the accessToUnderlyingConnectionAllowed property.
      void setConnectionProperties​(java.util.Properties props)
      Sets the connection properties passed to the JDBC driver.
      void setDescription​(java.lang.String v)
      Sets the value of description.
      void setDriver​(java.lang.String v)
      Sets the driver class name.
      void setLoginTimeout​(int seconds)
      Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
      void setLogWriter​(java.io.PrintWriter out)
      Sets the log writer for this data source.
      void setMaxIdle​(int maxIdle)
      Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
      void setMaxPreparedStatements​(int maxPreparedStatements)
      Sets the maximum number of prepared statements.
      void setMinEvictableIdleTimeMillis​(int minEvictableIdleTimeMillis)
      Sets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
      void setNumTestsPerEvictionRun​(int numTestsPerEvictionRun)
      Sets the number of statements to examine during each run of the idle object evictor thread (if any).
      void setPassword​(char[] userPassword)
      Sets the value of password for the default user.
      void setPassword​(java.lang.String userPassword)
      Sets the value of password for the default user.
      void setPoolPreparedStatements​(boolean poolPreparedStatements)
      Whether to toggle the pooling of PreparedStatements
      void setTimeBetweenEvictionRunsMillis​(long timeBetweenEvictionRunsMillis)
      Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
      void setUrl​(java.lang.String v)
      Sets the value of URL string used to locate the database for this datasource.
      void setUser​(java.lang.String v)
      Sets the value of default user (login or user name).
      java.lang.String toString()
      Does not print the userName and userPassword field nor the 'user' or 'password' in the connectionProperties.
      private void update​(java.util.Properties properties, java.lang.String key, java.lang.String value)  

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface javax.sql.CommonDataSource

        createShardingKeyBuilder

      • Methods inherited from interface javax.sql.ConnectionPoolDataSource

        createPooledConnectionBuilder

    • Field Detail

      • GET_CONNECTION_CALLED

        private static final java.lang.String GET_CONNECTION_CALLED
        See Also:
        Constant Field Values

      • description

        private java.lang.String description
        Description

      • url

        private java.lang.String url
        Url name

      • userName

        private java.lang.String userName
        User name

      • userPassword

        private char[] userPassword
        User password

      • driver

        private java.lang.String driver
        Driver class name

      • loginTimeout

        private int loginTimeout
        Login TimeOut in seconds

      • logWriter

        private transient java.io.PrintWriter logWriter
        Log stream. NOT USED

      • poolPreparedStatements

        private boolean poolPreparedStatements

      • maxIdle

        private int maxIdle

      • timeBetweenEvictionRunsMillis

        private long timeBetweenEvictionRunsMillis

      • numTestsPerEvictionRun

        private int numTestsPerEvictionRun

      • minEvictableIdleTimeMillis

        private int minEvictableIdleTimeMillis

      • maxPreparedStatements

        private int maxPreparedStatements

      • getConnectionCalled

        private volatile boolean getConnectionCalled
        Whether or not getConnection has been called

      • connectionProperties

        private java.util.Properties connectionProperties
        Connection properties passed to JDBC Driver

      • accessToUnderlyingConnectionAllowed

        private boolean accessToUnderlyingConnectionAllowed
        Controls access to the underlying connection

    • Constructor Detail

      • DriverAdapterCPDS

        public DriverAdapterCPDS()
        Default no-arg constructor for Serialization

    • Method Detail

      • assertInitializationAllowed

        private void assertInitializationAllowed()
                                  throws java.lang.IllegalStateException
        Throws an IllegalStateException, if a PooledConnection has already been requested.
        Throws:
        java.lang.IllegalStateException

      • getBooleanContentString

        private boolean getBooleanContentString​(javax.naming.RefAddr ra)

      • getConnectionProperties

        public java.util.Properties getConnectionProperties()
        Gets the connection properties passed to the JDBC driver.
        Returns:
        the JDBC connection properties used when creating connections.

      • getDescription

        public java.lang.String getDescription()
        Gets the value of description. This property is here for use by the code which will deploy this datasource. It is not used internally.
        Returns:
        value of description, may be null.
        See Also:
        setDescription(String)

      • getDriver

        public java.lang.String getDriver()
        Gets the driver class name.
        Returns:
        value of driver.

      • getIntegerStringContent

        private int getIntegerStringContent​(javax.naming.RefAddr ra)

      • getLoginTimeout

        public int getLoginTimeout()
        Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. NOT USED.
        Specified by:
        getLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        getLoginTimeout in interface javax.sql.ConnectionPoolDataSource

      • getLogWriter

        public java.io.PrintWriter getLogWriter()
        Gets the log writer for this data source. NOT USED.
        Specified by:
        getLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        getLogWriter in interface javax.sql.ConnectionPoolDataSource

      • getMaxIdle

        public int getMaxIdle()
        Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
        Returns:
        the value of maxIdle

      • getMaxPreparedStatements

        public int getMaxPreparedStatements()
        Gets the maximum number of prepared statements.
        Returns:
        maxPrepartedStatements value

      • getMinEvictableIdleTimeMillis

        public int getMinEvictableIdleTimeMillis()
        Gets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any).
        Returns:
        the minimum amount of time a statement may sit idle in the pool.
        See Also:
        setMinEvictableIdleTimeMillis(int), setTimeBetweenEvictionRunsMillis(long)

      • getNumTestsPerEvictionRun

        public int getNumTestsPerEvictionRun()
        Gets the number of statements to examine during each run of the idle object evictor thread (if any.)
        Returns:
        the number of statements to examine during each run of the idle object evictor thread (if any.)
        See Also:
        setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(long)

      • getObjectInstance

        public java.lang.Object getObjectInstance​(java.lang.Object refObj,
                                          javax.naming.Name name,
                                          javax.naming.Context context,
                                          java.util.Hashtable<?,​?> env)
                                   throws java.lang.Exception
        Implements ObjectFactory to create an instance of this class
        Specified by:
        getObjectInstance in interface javax.naming.spi.ObjectFactory
        Throws:
        java.lang.Exception

      • getParentLogger

        public java.util.logging.Logger getParentLogger()
                                         throws java.sql.SQLFeatureNotSupportedException
        Specified by:
        getParentLogger in interface javax.sql.CommonDataSource
        Throws:
        java.sql.SQLFeatureNotSupportedException

      • getPassword

        public java.lang.String getPassword()
        Gets the value of password for the default user.
        Returns:
        value of password.

      • getPasswordCharArray

        public char[] getPasswordCharArray()
        Gets the value of password for the default user.
        Returns:
        value of password.
        Since:
        2.4.0

      • getPooledConnection

        public javax.sql.PooledConnection getPooledConnection()
                                               throws java.sql.SQLException
        Attempts to establish a database connection using the default user and password.
        Specified by:
        getPooledConnection in interface javax.sql.ConnectionPoolDataSource
        Throws:
        java.sql.SQLException

      • getPooledConnection

        public javax.sql.PooledConnection getPooledConnection​(java.lang.String pooledUserName,
                                                      java.lang.String pooledUserPassword)
                                               throws java.sql.SQLException
        Attempts to establish a database connection.
        Specified by:
        getPooledConnection in interface javax.sql.ConnectionPoolDataSource
        Parameters:
        pooledUserName - name to be used for the connection
        pooledUserPassword - password to be used fur the connection
        Throws:
        java.sql.SQLException

      • getReference

        public javax.naming.Reference getReference()
                                    throws javax.naming.NamingException
        Implements Referenceable.
        Specified by:
        getReference in interface javax.naming.Referenceable
        Throws:
        javax.naming.NamingException

      • getStringContent

        private java.lang.String getStringContent​(javax.naming.RefAddr ra)

      • getTimeBetweenEvictionRunsMillis

        public long getTimeBetweenEvictionRunsMillis()
        Gets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Returns:
        the value of the evictor thread timer
        See Also:
        setTimeBetweenEvictionRunsMillis(long)

      • getUrl

        public java.lang.String getUrl()
        Gets the value of url used to locate the database for this datasource.
        Returns:
        value of url.

      • getUser

        public java.lang.String getUser()
        Gets the value of default user (login or user name).
        Returns:
        value of user.

      • isAccessToUnderlyingConnectionAllowed

        public boolean isAccessToUnderlyingConnectionAllowed()
        Returns the value of the accessToUnderlyingConnectionAllowed property.
        Returns:
        true if access to the underlying is allowed, false otherwise.

      • isNotEmpty

        private boolean isNotEmpty​(javax.naming.RefAddr ra)

      • isPoolPreparedStatements

        public boolean isPoolPreparedStatements()
        Whether to toggle the pooling of PreparedStatements
        Returns:
        value of poolPreparedStatements.

      • setAccessToUnderlyingConnectionAllowed

        public void setAccessToUnderlyingConnectionAllowed​(boolean allow)
        Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to the underlying connection. (Default: false)
        Parameters:
        allow - Access to the underlying connection is granted when true.

      • setConnectionProperties

        public void setConnectionProperties​(java.util.Properties props)
        Sets the connection properties passed to the JDBC driver.

        If props contains "user" and/or "password" properties, the corresponding instance properties are set. If these properties are not present, they are filled in using getUser(), getPassword() when getPooledConnection() is called, or using the actual parameters to the method call when getPooledConnection(String, String) is called. Calls to setUser(String) or setPassword(String) overwrite the values of these properties if connectionProperties is not null.

        Parameters:
        props - Connection properties to use when creating new connections.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setDescription

        public void setDescription​(java.lang.String v)
        Sets the value of description. This property is here for use by the code which will deploy this datasource. It is not used internally.
        Parameters:
        v - Value to assign to description.

      • setDriver

        public void setDriver​(java.lang.String v)
               throws java.lang.ClassNotFoundException
        Sets the driver class name. Setting the driver class name cause the driver to be registered with the DriverManager.
        Parameters:
        v - Value to assign to driver.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called
        java.lang.ClassNotFoundException - if the class cannot be located

      • setLoginTimeout

        public void setLoginTimeout​(int seconds)
        Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. NOT USED.
        Specified by:
        setLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        setLoginTimeout in interface javax.sql.ConnectionPoolDataSource

      • setLogWriter

        public void setLogWriter​(java.io.PrintWriter out)
        Sets the log writer for this data source. NOT USED.
        Specified by:
        setLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        setLogWriter in interface javax.sql.ConnectionPoolDataSource

      • setMaxIdle

        public void setMaxIdle​(int maxIdle)
        Gets the maximum number of statements that can remain idle in the pool, without extra ones being released, or negative for no limit.
        Parameters:
        maxIdle - The maximum number of statements that can remain idle
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setMaxPreparedStatements

        public void setMaxPreparedStatements​(int maxPreparedStatements)
        Sets the maximum number of prepared statements.
        Parameters:
        maxPreparedStatements - the new maximum number of prepared statements

      • setMinEvictableIdleTimeMillis

        public void setMinEvictableIdleTimeMillis​(int minEvictableIdleTimeMillis)
        Sets the minimum amount of time a statement may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). When non-positive, no objects will be evicted from the pool due to idle time alone.
        Parameters:
        minEvictableIdleTimeMillis - minimum time to set (in ms)
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called
        See Also:
        getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(long)

      • setNumTestsPerEvictionRun

        public void setNumTestsPerEvictionRun​(int numTestsPerEvictionRun)
        Sets the number of statements to examine during each run of the idle object evictor thread (if any).

        When a negative value is supplied, ceil({*link #numIdle})/abs({*link #getNumTestsPerEvictionRun}) tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.

        Parameters:
        numTestsPerEvictionRun - number of statements to examine per run
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called
        See Also:
        getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(long)

      • setPassword

        public void setPassword​(char[] userPassword)
        Sets the value of password for the default user.
        Parameters:
        userPassword - Value to assign to password.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setPassword

        public void setPassword​(java.lang.String userPassword)
        Sets the value of password for the default user.
        Parameters:
        userPassword - Value to assign to password.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setPoolPreparedStatements

        public void setPoolPreparedStatements​(boolean poolPreparedStatements)
        Whether to toggle the pooling of PreparedStatements
        Parameters:
        poolPreparedStatements - true to pool statements.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setTimeBetweenEvictionRunsMillis

        public void setTimeBetweenEvictionRunsMillis​(long timeBetweenEvictionRunsMillis)
        Sets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Parameters:
        timeBetweenEvictionRunsMillis - The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called
        See Also:
        getTimeBetweenEvictionRunsMillis()

      • setUrl

        public void setUrl​(java.lang.String v)
        Sets the value of URL string used to locate the database for this datasource.
        Parameters:
        v - Value to assign to url.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • setUser

        public void setUser​(java.lang.String v)
        Sets the value of default user (login or user name).
        Parameters:
        v - Value to assign to user.
        Throws:
        java.lang.IllegalStateException - if getPooledConnection() has been called

      • toString

        public java.lang.String toString()
        Does not print the userName and userPassword field nor the 'user' or 'password' in the connectionProperties.
        Overrides:
        toString in class java.lang.Object
        Since:
        2.6.0

      • update

        private void update​(java.util.Properties properties,
                    java.lang.String key,
                    java.lang.String value)