Class ClientDataSource

java.lang.Object
org.apache.derby.jdbc.BasicClientDataSource40
org.apache.derby.jdbc.ClientDataSource
All Implemented Interfaces:
Serializable, Wrapper, Referenceable, CommonDataSource, DataSource
Direct Known Subclasses:
ClientConnectionPoolDataSource, ClientXADataSource
public class ClientDataSource extends BasicClientDataSource40 implements Referenceable
This data source is suitable for a client/server use of Derby, running on full Java SE 6 and higher, corresponding to JDBC 4.0 and higher.

ClientDataSource is a simple data source implementation that can be used for establishing connections in a non-pooling, non-distributed environment. The class ClientConnectionPoolDataSource can be used in a connection pooling environment, and the class ClientXADataSource can be used in a distributed, and pooling environment.

The example below registers a DNC data source object with a JNDI naming service. 

org.apache.derby.client.ClientDataSource dataSource = new org.apache.derby.client.ClientDataSource ();
dataSource.setServerName ("my_derby_database_server");
dataSource.setDatabaseName ("my_derby_database_name");
javax.naming.Context context = new javax.naming.InitialContext();
context.bind ("jdbc/my_datasource_name", dataSource);
The first line of code in the example creates a data source object. The next two lines initialize the data source's properties. Then a Java object that references the initial JNDI naming context is created by calling the InitialContext() constructor, which is provided by JNDI. System properties (not shown) are used to tell JNDI the service provider to use. The JNDI name space is hierarchical, similar to the directory structure of many file systems. The data source object is bound to a logical JNDI name by calling Context.bind(). In this case the JNDI name identifies a subcontext, "jdbc", of the root naming context and a logical name, "my_datasource_name", within the jdbc subcontext. This is all of the code required to deploy a data source object within JNDI. This example is provided mainly for illustrative purposes. We expect that developers or system administrators will normally use a GUI tool to deploy a data source object.

Once a data source has been registered with JNDI, it can then be used by a JDBC application, as is shown in the following example. 

javax.naming.Context context = new javax.naming.InitialContext ();
javax.sql.DataSource dataSource = (javax.sql.DataSource) context.lookup ("jdbc/my_datasource_name");
java.sql.Connection connection = dataSource.getConnection ("user", "password");
The first line in the example creates a Java object that references the initial JNDI naming context. Next, the initial naming context is used to do a lookup operation using the logical name of the data source. The Context.lookup() method returns a reference to a Java Object, which is narrowed to a javax.sql.DataSource object. In the last line, the DataSource.getConnection() method is called to produce a database connection.

This simple data source subclass of BasicClientDataSource40 maintains it's own private password property.

The specified password, along with the user, is validated by DERBY. This property can be overwritten by specifying the password parameter on the DataSource.getConnection() method call.

This password property is not declared transient, and therefore may be serialized to a file in clear-text, or stored to a JNDI server in clear-text when the data source is saved. Care must taken by the user to prevent security breaches.

See Also:

  • Field Details

    • className__

      public static final String className__
      See Also:

    • 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:

    • TRACE_CONNECTION_CALLS

      public static final int TRACE_CONNECTION_CALLS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_STATEMENT_CALLS

      public static final int TRACE_STATEMENT_CALLS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_RESULT_SET_CALLS

      public static final int TRACE_RESULT_SET_CALLS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_DRIVER_CONFIGURATION

      public static final int TRACE_DRIVER_CONFIGURATION
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_CONNECTS

      public static final int TRACE_CONNECTS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_PROTOCOL_FLOWS

      public static final int TRACE_PROTOCOL_FLOWS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_RESULT_SET_META_DATA

      public static final int TRACE_RESULT_SET_META_DATA
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_PARAMETER_META_DATA

      public static final int TRACE_PARAMETER_META_DATA
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_DIAGNOSTICS

      public static final int TRACE_DIAGNOSTICS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_XA_CALLS

      public static final int TRACE_XA_CALLS
      See documentation at TRACE_NONE.
      See Also:

    • TRACE_ALL

      public static final int TRACE_ALL
      See documentation at TRACE_NONE.
      See Also:

    • propertyDefault_traceLevel

      public static final int propertyDefault_traceLevel
      See documentation at TRACE_NONE.
      See Also:

    • 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:

    • CLEAR_TEXT_PASSWORD_SECURITY

      public static final short CLEAR_TEXT_PASSWORD_SECURITY
      See documentation at USER_ONLY_SECURITY
      See Also:

    • ENCRYPTED_PASSWORD_SECURITY

      public static final short ENCRYPTED_PASSWORD_SECURITY
      See documentation at USER_ONLY_SECURITY
      See Also:

    • ENCRYPTED_USER_AND_PASSWORD_SECURITY

      public static final short ENCRYPTED_USER_AND_PASSWORD_SECURITY
      See documentation at USER_ONLY_SECURITY
      See Also:

    • STRONG_PASSWORD_SUBSTITUTE_SECURITY

      public static final short STRONG_PASSWORD_SUBSTITUTE_SECURITY
      See documentation at USER_ONLY_SECURITY
      See Also:

    • SSL_OFF

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

    • SSL_BASIC

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

    • SSL_PEER_AUTHENTICATION

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

    • propertyDefault_portNumber

      static final int propertyDefault_portNumber
      See Also:

    • propertyDefault_serverName

      static final String propertyDefault_serverName
      See Also:

    • propertyDefault_user

      static final String propertyDefault_user
      See Also:

    • propertyDefault_retrieveMessageText

      static final boolean propertyDefault_retrieveMessageText
      See Also:

    • propertyDefault_securityMechanism

      static final short propertyDefault_securityMechanism
      Default security mechanism is USER_ONLY_SECURITY.
      See Also:

    • propertyDefault_traceFileAppend

      static final boolean propertyDefault_traceFileAppend
      See Also:

  • Constructor Details

    • ClientDataSource

      public ClientDataSource()
      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 Details

    • getReference

      public Reference getReference() throws NamingException
      Specified by:
      getReference in interface Referenceable
      Throws:
      NamingException

    • setLoginTimeout

      public void setLoginTimeout(int seconds)
      Specified by:
      setLoginTimeout in interface CommonDataSource
      Specified by:
      setLoginTimeout in interface DataSource

    • getLoginTimeout

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

    • setLogWriter

      public void setLogWriter(PrintWriter logWriter)
      Specified by:
      setLogWriter in interface CommonDataSource
      Specified by:
      setLogWriter in interface DataSource

    • getLogWriter

      public PrintWriter getLogWriter()
      Specified by:
      getLogWriter in interface CommonDataSource
      Specified by:
      getLogWriter in interface DataSource

    • getSSLModeFromString

      public static int getSSLModeFromString(String s) throws org.apache.derby.client.am.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:
      org.apache.derby.client.am.SqlException - if the string has an invalid value

    • getClientSSLMode

      public static int getClientSSLMode(Properties properties) throws org.apache.derby.client.am.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:
      org.apache.derby.client.am.SqlException - if an invalid value for the SSL mode is specified in the property object

    • getUser

      public static String getUser(Properties properties)

    • getSecurityMechanism

      public static short getSecurityMechanism(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

    • getRetrieveMessageText

      public static boolean getRetrieveMessageText(Properties properties)

    • getTraceFile

      public static String getTraceFile(Properties properties)

    • getTraceDirectory

      public static String getTraceDirectory(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

    • getTraceFileAppend

      public static boolean getTraceFileAppend(Properties properties)

    • getPassword

      public static String getPassword(Properties properties)

    • setPassword

      public void setPassword(String password)

    • getPassword

      public String getPassword()

    • computeDncLogWriterForNewConnection

      public static org.apache.derby.client.am.LogWriter computeDncLogWriterForNewConnection(PrintWriter logWriter, String traceDirectory, String traceFile, boolean traceFileAppend, int traceLevel, String logWriterInUseSuffix, int traceFileSuffixIndex) throws org.apache.derby.client.am.SqlException
      Throws:
      org.apache.derby.client.am.SqlException

    • tokenizeAttributes

      public static Properties tokenizeAttributes(String attributeString, Properties properties) throws org.apache.derby.client.am.SqlException
      Throws:
      org.apache.derby.client.am.SqlException

    • setDatabaseName

      public void setDatabaseName(String databaseName)

    • getDatabaseName

      public String getDatabaseName()

    • setDataSourceName

      public void setDataSourceName(String dataSourceName)

    • getDataSourceName

      public String getDataSourceName()

    • setDescription

      public void setDescription(String description)

    • getDescription

      public String getDescription()

    • setPortNumber

      public void setPortNumber(int portNumber)

    • getPortNumber

      public int getPortNumber()

    • setServerName

      public void setServerName(String serverName)

    • getServerName

      public String getServerName()

    • setUser

      public void setUser(String user)

    • getUser

      public String getUser()

    • setRetrieveMessageText

      public void setRetrieveMessageText(boolean retrieveMessageText)

    • getRetrieveMessageText

      public boolean getRetrieveMessageText()

    • setSecurityMechanism

      public void setSecurityMechanism(short securityMechanism)
      Sets the security mechanism.
      Parameters:
      securityMechanism - to set

    • getSecurityMechanism

      public short getSecurityMechanism()
      Return the security mechanism. If security mechanism has not been set explicitly on datasource, then upgrade the security mechanism to a more secure one if possible.
      Returns:
      the security mechanism
      See Also:
      • BasicClientDataSource.getUpgradedSecurityMechanism(String)

    • getSecurityMechanism

      public short getSecurityMechanism(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.
      Parameters:
      password - password of user
      Returns:
      the security mechanism
      See Also:
      • BasicClientDataSource.getUpgradedSecurityMechanism(String)

    • setSsl

      public void setSsl(String mode) throws org.apache.derby.client.am.SqlException
      Specifies the SSL encryption mode to use.

      Valid values are off, basic and peerAuthentication.

      Parameters:
      mode - the SSL mode to use (off, basic or peerAuthentication)
      Throws:
      org.apache.derby.client.am.SqlException - if the specified mode is invalid

    • getSsl

      public String getSsl()
      Returns the SSL encryption mode specified for the data source.
      Returns:
      off, basic or peerAuthentication.

    • setCreateDatabase

      public void setCreateDatabase(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.
      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.

    • getCreateDatabase

      public String getCreateDatabase()
      Returns:
      "create" if create is set, or null if not

    • setShutdownDatabase

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

    • getShutdownDatabase

      public String getShutdownDatabase()
      Returns:
      "shutdown" if shutdown is set, or null if not

    • setConnectionAttributes

      public void setConnectionAttributes(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.
      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.

    • getConnectionAttributes

      public String getConnectionAttributes()
      Returns:
      Derby specific connection URL attributes

    • getTraceLevel

      public static int getTraceLevel(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

    • setTraceLevel

      public void setTraceLevel(int traceLevel)

    • getTraceLevel

      public int getTraceLevel()

    • setTraceFile

      public void setTraceFile(String traceFile)

    • getTraceFile

      public String getTraceFile()

    • setTraceDirectory

      public void setTraceDirectory(String traceDirectory)

    • getTraceDirectory

      public String getTraceDirectory()

    • setTraceFileAppend

      public void setTraceFileAppend(boolean traceFileAppend)

    • getTraceFileAppend

      public boolean getTraceFileAppend()

    • 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).

    • getConnection

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

    • getConnection

      public Connection getConnection(String user, String password) throws SQLException
      Attempt to establish a database connection in a non-pooling, non-distributed environment.
      Specified by:
      getConnection in interface 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:
      SQLException - if a database-access error occurs.

    • isWrapperFor

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

    • unwrap

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

    • getParentLogger

      public Logger getParentLogger() throws SQLFeatureNotSupportedException
      /////////////////////////////////////////////////////////////////
      Specified by:
      getParentLogger in interface CommonDataSource
      Throws:
      SQLFeatureNotSupportedException

    • getProperties

      public static Properties getProperties(org.apache.derby.client.BasicClientDataSource ths)