Package org.apache.derby.jdbc

Class BasicClientDataSource40

  • All Implemented Interfaces:
    java.io.Serializable, java.sql.Wrapper, javax.sql.CommonDataSource, javax.sql.DataSource, ClientDataSourceInterface
    Direct Known Subclasses:
    BasicClientConnectionPoolDataSource40, BasicClientXADataSource40, ClientDataSource
    public class BasicClientDataSource40
extends java.lang.Object
implements javax.sql.DataSource, ClientDataSourceInterface, java.io.Serializable
    This data source is suitable for client/server use of Derby, running on Java 8 Compact Profile 2 or higher.

    BasicClientDataSource40 is similar to ClientDataSource except it can not be used with JNDI, i.e. it does not implement javax.naming.Referenceable.

    * The standard attributes provided are, cf. e.g. table 9.1 in the JDBC 4.2 specification.

    • databaseName
    • dataSourceName
    • description
    • password
    • user
    These standard attributes are not supported:
    • networkProtocol
    • roleName
    The Derby client driver also supports these attributes:
    • loginTimeout
      • @see javax.sql.CommonDataSource set/get
    • logWriter
      • @see javax.sql.CommonDataSource set/get
    • createDatabase
    • connectionAttributes
    • shutdownDatabase
    • attributesAsPassword
    • retrieveMessageText
    • securityMechanism
    • traceDirectory
    • traceFile
    • traceFileAppend
    • traceLevel
    See Also:
    Serialized Form

    • Field Detail

      • TRACE_NONE

        public static final int TRACE_NONE
        The client server protocol can be traced. The constants below define the tracing level, cf. the documentation section "Network Client Tracing" in the "Derby Server and Administration Guide". Cf. the connection attribute (or data source bean property) traceLevel. 
         TRACE_NONE     
 TRACE_CONNECTION_CALLS 
 TRACE_STATEMENT_CALLS  
 TRACE_RESULT_SET_CALLS 
 TRACE _DRIVER_CONFIGURATION    
 TRACE_CONNECTS 
 TRACE_PROTOCOL_FLOWS   
 TRACE _RESULT_SET_META_DATA    
 TRACE _PARAMETER_META_DATA     
 TRACE_DIAGNOSTICS      
 TRACE_XA_CALLS 
 TRACE_ALL
        See Also:
        Constant Field Values

      • USER_ONLY_SECURITY

        public static final short USER_ONLY_SECURITY
        The source security mechanism to use when connecting to a client data source.

        Security mechanism options are:

        • USER_ONLY_SECURITY
        • CLEAR_TEXT_PASSWORD_SECURITY
        • ENCRYPTED_PASSWORD_SECURITY
        • ENCRYPTED_USER_AND_PASSWORD_SECURITY - both password and user are encrypted
        • STRONG_PASSWORD_SUBSTITUTE_SECURITY
        The default security mechanism is USER_ONLY SECURITY

        If the application specifies a security mechanism then it will be the only one attempted. If the specified security mechanism is not supported by the conversation then an exception will be thrown and there will be no additional retries.

        Both user and password need to be set for all security mechanism except USER_ONLY_SECURITY.

        See Also:
        Constant Field Values

      • loginTimeout

        private int loginTimeout
        The time in seconds to wait for a connection request on this data source. The default value of zero indicates that either the system time out be used or no timeout limit.

      • logWriter

        private transient java.io.PrintWriter logWriter
        The log writer is declared transient, and is not serialized or stored under JNDI.
        See Also:
        traceLevel

      • databaseName

        private java.lang.String databaseName
        Stores the relational database name, RDBNAME. The length of the database name may be limited to 18 bytes and therefore may throw an SQLException.

      • description

        private java.lang.String description
        A description of this data source.

      • dataSourceName

        private java.lang.String dataSourceName
        A data source name; used to name an underlying XADataSource, or ConnectionPoolDataSource when pooling of connections is done.

      • portNumber

        private int portNumber

      • serverName

        private java.lang.String serverName

      • SSL_OFF

        public static final int SSL_OFF
        The constant indicating that SSL encryption won't be used.
        See Also:
        Constant Field Values

      • SSL_BASIC

        public static final int SSL_BASIC
        The constant indicating that SSL encryption will be used.
        See Also:
        Constant Field Values

      • SSL_PEER_AUTHENTICATION

        public static final int SSL_PEER_AUTHENTICATION
        The constant indicating that SSL encryption with peer authentication will be used.
        See Also:
        Constant Field Values

      • SSL_PEER_AUTHENTICATION_STR

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

      • user

        private java.lang.String user
        This property can be overwritten by specifing the username parameter on the DataSource.getConnection() method call. If user is specified, then password must also be specified, either in the data source object or provided on the DataSource.getConnection() call. Each data source implementation subclass will maintain it's own password property. This password property may or may not be declared transient, and therefore may be serialized to a file in clear-text, care must taken by the user to prevent security breaches. Derby-406 fix

      • SECMEC_HAS_NOT_EXPLICITLY_SET

        private static final short SECMEC_HAS_NOT_EXPLICITLY_SET
        See Also:
        Constant Field Values

      • securityMechanism

        private short securityMechanism
        Security Mechanism can be specified explicitly either when obtaining a connection via a DriverManager or via Datasource. Via DriverManager, securityMechanism can be set on the connection request using the 'securityMechanism' attribute. Via DataSource, securityMechanism can be set by calling setSecurityMechanism() on the ClientDataSource If the security mechanism is not explicitly set as mentioned above, in that case the Client will try to upgrade the security mechanism to a more secure one, if possible. See getUpgradedSecurityMechanism(java.lang.String). Therefore, need to keep track if the securityMechanism has been explicitly set.

      • retrieveMessageText

        private boolean retrieveMessageText

      • traceFile

        private java.lang.String traceFile

      • traceFileSuffixIndex_

        private transient int traceFileSuffixIndex_

      • traceDirectory

        private java.lang.String traceDirectory

      • traceFileAppend

        private boolean traceFileAppend

      • password

        private java.lang.String password

      • sslMode

        private int sslMode

      • createDatabase

        private boolean createDatabase
        Set to true if the database should be created.

      • shutdownDatabase

        private boolean shutdownDatabase
        Set to true if the database should be shutdown.

      • connectionAttributes

        private java.lang.String connectionAttributes

      • traceLevel

        private int traceLevel

    • Constructor Detail

      • BasicClientDataSource40

        public BasicClientDataSource40()
        Creates a simple DERBY data source with default property values for a non-pooling, non-distributed environment. No particular DatabaseName or other properties are associated with the data source.

        Every Java Bean should provide a constructor with no arguments since many beanboxes attempt to instantiate a bean by invoking its no-argument constructor.

    • Method Detail

      • setLoginTimeout

        public void setLoginTimeout​(int seconds)
        Specified by:
        setLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        setLoginTimeout in interface javax.sql.DataSource

      • getLoginTimeout

        public int getLoginTimeout()
        Specified by:
        getLoginTimeout in interface javax.sql.CommonDataSource
        Specified by:
        getLoginTimeout in interface javax.sql.DataSource

      • setLogWriter

        public void setLogWriter​(java.io.PrintWriter logWriter)
        Specified by:
        setLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        setLogWriter in interface javax.sql.DataSource

      • getLogWriter

        public java.io.PrintWriter getLogWriter()
        Specified by:
        getLogWriter in interface javax.sql.CommonDataSource
        Specified by:
        getLogWriter in interface javax.sql.DataSource

      • getSSLModeFromString

        public static int getSSLModeFromString​(java.lang.String s)
                                throws SqlException
        Parses the string and returns the corresponding constant for the SSL mode denoted.

        Valid values are off, basic and peerAuthentication.

        Parameters:
        s - string denoting the SSL mode
        Returns:
        A constant indicating the SSL mode denoted by the string. If the string is null, SSL_OFF is returned.
        Throws:
        SqlException - if the string has an invalid value

      • getClientSSLMode

        public static int getClientSSLMode​(java.util.Properties properties)
                            throws SqlException
        Returns the SSL mode specified by the property object.
        Parameters:
        properties - data source properties
        Returns:
        A constant indicating the SSL mode to use. Defaults to SSL_OFF if the SSL attribute isn't specified.
        Throws:
        SqlException - if an invalid value for the SSL mode is specified in the property object

      • getUser

        public static java.lang.String getUser​(java.util.Properties properties)

      • getSecurityMechanism

        public static short getSecurityMechanism​(java.util.Properties properties)
        Return security mechanism if it is set, else upgrade the security mechanism if possible and return the upgraded security mechanism
        Parameters:
        properties - Look in the properties if securityMechanism is set or not if set, return this security mechanism
        Returns:
        security mechanism

      • getUpgradedSecurityMechanism

        private static short getUpgradedSecurityMechanism​(java.lang.String password)
        This method has logic to upgrade security mechanism to a better (more secure) one if it is possible. Currently derby server only has support for USRIDPWD, USRIDONL, EUSRIDPWD and USRSSBPWD (10.2+) - this method only considers these possibilities. USRIDPWD, EUSRIDPWD and USRSSBPWD require a password, USRIDONL is the only security mechanism which does not require password. 1. if password is not available, then security mechanism possible is USRIDONL 2. if password is available,then USRIDPWD is returned.
        Parameters:
        password - password argument
        Returns:
        upgraded security mechanism if possible

      • getRetrieveMessageText

        public static boolean getRetrieveMessageText​(java.util.Properties properties)

      • getTraceFile

        static java.lang.String getTraceFile​(java.util.Properties properties)

      • getTraceDirectory

        static java.lang.String getTraceDirectory​(java.util.Properties properties)
        Check if derby.client.traceDirectory is provided as a JVM property. If yes, then we use that value. If not, then we look for traceDirectory in the the properties parameter.
        Parameters:
        properties - jdbc url properties
        Returns:
        value of traceDirectory property

      • readSystemProperty

        private static java.lang.String readSystemProperty​(java.lang.String key)
        Read the value of the passed system property. If we are running under the Java security manager and permission to read the property is missing,a null is returned, and no diagnostic is given (DERBY-6620).
        Parameters:
        key - name of the system property
        Returns:
        value of the system property, null if there is no permission to read the property

      • getTraceFileAppend

        static boolean getTraceFileAppend​(java.util.Properties properties)

      • getPassword

        public static java.lang.String getPassword​(java.util.Properties properties)

      • computeDncLogWriterForNewConnection

        private LogWriter computeDncLogWriterForNewConnection​(java.lang.String logWriterInUseSuffix)
                                               throws SqlException
        Throws:
        SqlException

      • computeDncLogWriterForNewConnection

        static LogWriter computeDncLogWriterForNewConnection​(java.io.PrintWriter logWriter,
                                                     java.lang.String traceDirectory,
                                                     java.lang.String traceFile,
                                                     boolean traceFileAppend,
                                                     int traceLevel,
                                                     java.lang.String logWriterInUseSuffix,
                                                     int traceFileSuffixIndex)
                                              throws SqlException
        Throws:
        SqlException

      • computeDncLogWriter

        private static LogWriter computeDncLogWriter​(java.io.PrintWriter logWriter,
                                             java.lang.String traceDirectory,
                                             java.lang.String traceFile,
                                             boolean traceFileAppend,
                                             java.lang.String logWriterInUseSuffix,
                                             int traceFileSuffixIndex,
                                             int traceLevel)
                                      throws SqlException
        Throws:
        SqlException

      • computePrintWriter

        private static java.io.PrintWriter computePrintWriter​(java.io.PrintWriter logWriter,
                                                      java.lang.String traceDirectory,
                                                      java.lang.String traceFile,
                                                      boolean traceFileAppend,
                                                      java.lang.String logWriterInUseSuffix,
                                                      int traceFileSuffixIndex)
                                               throws SqlException
        Throws:
        SqlException

      • getPrintWriter

        private static java.io.PrintWriter getPrintWriter​(java.lang.String fileName,
                                                  boolean fileAppend)
                                           throws SqlException
        Throws:
        SqlException

      • parseBoolean

        private static boolean parseBoolean​(java.lang.String boolString,
                                    boolean defaultBool)

      • parseString

        private static java.lang.String parseString​(java.lang.String string,
                                            java.lang.String defaultString)

      • parseInt

        private static int parseInt​(java.lang.String intString,
                            int defaultInt)

      • tokenizeAttributes

        static java.util.Properties tokenizeAttributes​(java.lang.String attributeString,
                                               java.util.Properties properties)
                                        throws SqlException
        Throws:
        SqlException

      • checkBoolean

        private static void checkBoolean​(java.util.Properties set,
                                 java.lang.String attribute)
                          throws SqlException
        Throws:
        SqlException

      • checkEnumeration

        private static void checkEnumeration​(java.util.Properties set,
                                     java.lang.String attribute,
                                     java.lang.String[] choices)
                              throws SqlException
        Throws:
        SqlException

      • setSecurityMechanism

        public void setSecurityMechanism​(short securityMechanism)
        Sets the security mechanism.
        Specified by:
        setSecurityMechanism in interface ClientDataSourceInterface
        Parameters:
        securityMechanism - to set

      • getSecurityMechanism

        public short getSecurityMechanism​(java.lang.String password)
        Return the security mechanism for this datasource object. If security mechanism has not been set explicitly on datasource, then upgrade the security mechanism to a more secure one if possible.
        Specified by:
        getSecurityMechanism in interface ClientDataSourceInterface
        Parameters:
        password - password of user
        Returns:
        the security mechanism
        See Also:
        getUpgradedSecurityMechanism(String)

      • setSsl

        public void setSsl​(java.lang.String mode)
            throws SqlException
        Specifies the SSL encryption mode to use.

        Valid values are off, basic and peerAuthentication.

        Specified by:
        setSsl in interface ClientDataSourceInterface
        Parameters:
        mode - the SSL mode to use (off, basic or peerAuthentication)
        Throws:
        SqlException - if the specified mode is invalid

      • getSsl

        public java.lang.String getSsl()
        Returns the SSL encryption mode specified for the data source.
        Specified by:
        getSsl in interface ClientDataSourceInterface
        Returns:
        off, basic or peerAuthentication.

      • setCreateDatabase

        public void setCreateDatabase​(java.lang.String create)
        Set this property to create a new database. If this property is not set, the database (identified by databaseName) is assumed to be already existing.
        Specified by:
        setCreateDatabase in interface ClientDataSourceInterface
        Parameters:
        create - if set to the string "create", this data source will try to create a new database of databaseName, or boot the database if one by that name already exists.

      • setShutdownDatabase

        public void setShutdownDatabase​(java.lang.String shutdown)
        Set this property if one wishes to shutdown the database identified by databaseName.
        Specified by:
        setShutdownDatabase in interface ClientDataSourceInterface
        Parameters:
        shutdown - if set to the string "shutdown", this data source will shutdown the database if it is running.

      • setConnectionAttributes

        public void setConnectionAttributes​(java.lang.String prop)
        Set this property to pass in more Derby specific connection URL attributes.
        Any attributes that can be set using a property of this DataSource implementation (e.g user, password) should not be set in connectionAttributes. Conflicting settings in connectionAttributes and properties of the DataSource will lead to unexpected behaviour.
        Specified by:
        setConnectionAttributes in interface ClientDataSourceInterface
        Parameters:
        prop - set to the list of Derby connection attributes separated by semi-colons. E.g., to specify an encryption bootPassword of "x8hhk2adf", and set upgrade to true, do the following:
        ds.setConnectionAttributes("bootPassword=x8hhk2adf;upgrade=true"); See Derby documentation for complete list.

      • getTraceLevel

        static int getTraceLevel​(java.util.Properties properties)
        Check if derby.client.traceLevel is provided as a JVM property. If yes, then we use that value. If not, then we look for traceLevel in the the properties parameter.
        Parameters:
        properties - jdbc url properties
        Returns:
        value of traceLevel property

      • maxStatementsToPool

        public int maxStatementsToPool()
        Returns the maximum number of JDBC prepared statements a connection is allowed to cache.

        A basic data source will always return zero. If statement caching is required, use a ConnectionPoolDataSource.

        This method is used internally by Derby to determine if statement pooling is to be enabled or not. Not part of public API, so not present in ClientDataSourceInterface.

        Returns:
        Maximum number of statements to cache, or 0 if caching is disabled (default).

      • updateDataSourceValues

        private void updateDataSourceValues​(java.util.Properties prop)
                             throws SqlException
        The dataSource keeps individual fields for the values that are relevant to the client. These need to be updated when set connection attributes is called.
        Throws:
        SqlException

      • handleConnectionException

        private void handleConnectionException​(LogWriter logWriter,
                                       SqlException sqle)
                                throws java.sql.SQLException
        Handles common error situations that can happen when trying to obtain a physical connection to the server, and which require special handling.

        If this method returns normally, the exception wasn't handled and should be handled elsewhere or be re-thrown.

        Parameters:
        logWriter - log writer, may be null
        sqle - exception to handle
        Throws:
        java.sql.SQLException - handled exception (if any)

      • constructUrl

        private java.lang.String constructUrl()
        Constructs the JDBC connection URL from the state of the data source.
        Returns:
        The JDBC connection URL.

      • getConnection

        public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
        Attempt to establish a database connection in a non-pooling, non-distributed environment.
        Specified by:
        getConnection in interface javax.sql.DataSource
        Returns:
        a Connection to the database
        Throws:
        java.sql.SQLException - if a database-access error occurs.

      • getConnection

        public java.sql.Connection getConnection​(java.lang.String user,
                                         java.lang.String password)
                                  throws java.sql.SQLException
        Attempt to establish a database connection in a non-pooling, non-distributed environment.
        Specified by:
        getConnection in interface javax.sql.DataSource
        Parameters:
        user - the database user on whose behalf the Connection is being made
        password - the user's password
        Returns:
        a Connection to the database
        Throws:
        java.sql.SQLException - if a database-access error occurs.

      • getConnectionX

        private java.sql.Connection getConnectionX​(LogWriter dncLogWriter,
                                           java.lang.String user,
                                           java.lang.String password)
                                    throws SqlException
        Throws:
        SqlException

      • isWrapperFor

        public boolean isWrapperFor​(java.lang.Class<?> iface)
                     throws java.sql.SQLException
        Check whether this instance wraps an object that implements the interface specified by iface.
        Specified by:
        isWrapperFor in interface java.sql.Wrapper
        Parameters:
        iface - a class defining an interface
        Returns:
        true if this instance implements iface, or false otherwise
        Throws:
        java.sql.SQLException - if an error occurs while determining if this instance implements iface

      • unwrap

        public <T> T unwrap​(java.lang.Class<T> iface)
             throws java.sql.SQLException
        Returns this if this class implements the specified interface.
        Specified by:
        unwrap in interface java.sql.Wrapper
        Parameters:
        iface - a class defining an interface
        Returns:
        an object that implements the interface
        Throws:
        java.sql.SQLException - if no object is found that implements the interface

      • getParentLogger

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

      • getPooledConnectionMinion

        protected final javax.sql.PooledConnection getPooledConnectionMinion()
                                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getPooledConnectionMinion

        protected final javax.sql.PooledConnection getPooledConnectionMinion​(java.lang.String user,
                                                                     java.lang.String password)
                                                              throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getPooledConnectionX

        private static javax.sql.PooledConnection getPooledConnectionX​(LogWriter dncLogWriter,
                                                               BasicClientDataSource40 ds,
                                                               java.lang.String user,
                                                               java.lang.String password)
                                                        throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getXAConnectionMinion

        protected final javax.sql.XAConnection getXAConnectionMinion()
                                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getXAConnectionMinion

        protected final javax.sql.XAConnection getXAConnectionMinion​(java.lang.String user,
                                                             java.lang.String password)
                                                      throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • getXAConnectionX

        private static javax.sql.XAConnection getXAConnectionX​(LogWriter dncLogWriter,
                                                       BasicClientDataSource40 ds,
                                                       java.lang.String user,
                                                       java.lang.String password)
                                                throws java.sql.SQLException
        Method that establishes the initial physical connection using DS properties instead of CPDS properties.
        Throws:
        java.sql.SQLException