com.jnetdirect.datasource
Class BaseDatasource

java.lang.Object
  extended by com.jnetdirect.datasource.BaseDatasource
All Implemented Interfaces:
java.io.Serializable, javax.naming.Referenceable
Direct Known Subclasses:
JSQLDataSource

public class BaseDatasource
extends java.lang.Object
implements javax.naming.Referenceable, java.io.Serializable

A Datasource is a factory for connections to a physical data source. Since JDBC 2.0 a DataSource object is the preferred means of creating a database connection. An object that implements the DataSource interface will typically be registered with a naming service based on the JavaTM Naming and Directory (JNDI) API. It will be instantiated in the application code via a JNDI lookup.

Data source properties are set and retrieved using the setXXX() and getXXX() methods. This API reference documents properties specific to this datasource. For frequently used properties common to all datasources (such as serverName, databaseName etc) please see the documentation for the super class BaseDatasource.

A plain datasource does not implement connection pooling directly. If connection pooling is required there are two cases:-

Managed Environment - If the application runs in a managed environment that already supports integrated connection pooling (EG an application server) then you should use that built in connection pooling implemenation. The application server will typically only require a third party vendor's datasource to create physical connections for its connection pool. Check the application server documentation to determine what type of datasource is required to create the physical connections. This datasource is a javax.sql.DataSource object.

No Managed Environment - If your application does not run in a managed environment and require connection pooling do not use this datasource. Use the pooling datasource instead. Your application code requires no changes and the pooling datasource will perform connection pooling automatically.

Please Note:The BaseDatasource implements frequently used properties common to all datasources. However you should not instantiate this datasource directly but always instantiate a datasource specific to the driver you are using. The driver specific datasource provides additional properties available only for that driver. Please see the API documentation for the driver specific datasource in use for a list of all driver specifc properties.

See Also:
Serialized Form

Field Summary
static boolean debugLog
           
 
Method Summary
 java.sql.Connection getConnection()
          Obtain a database connection using the datasource user and password properties.
 java.sql.Connection getConnection(java.lang.String username, java.lang.String password)
          Obtain a database connection using the supplied user and password properties.
 java.lang.String getConnectionVerifyTable()
          Get the verify table.
 java.lang.String getDatabase()
          Deprecated. - Use getDatabaseName.
 java.lang.String getDatabaseName()
          Get the database name for the datasource.
 java.lang.String getDescription()
          Get the description of the datasource.
 int getInitialPoolSize()
          Get the initial pool size.
 java.lang.String getLogfile()
          Retrieves the log file for this DataSource.
 int getLoginTimeout()
          Gets the maximum time that the data source will wait while attempting to connect to a database.
 java.io.PrintWriter getLogWriter()
          Retrieves the log writer for this DataSource.
 int getManagementCycleTime()
          Deprecated. - use getPropertyCycle()
 java.lang.String getMaxConnectionBacklog()
          Get the connection retry wait time.
 int getMaxIdleTime()
          Get the maximum idle time.
 int getMaxPoolSize()
          Get the maximum number of connections allowed in the connection pool.
 int getMinPoolSize()
          Get the minimum number of connections allowed in the connection pool.
 java.lang.String getPassword()
          Get the password for this datasource.
 int getPortNumber()
          Get the port number for the connection
 java.util.Properties getProperties()
          Get property values for the datasource.
 int getPropertyCycle()
          Get the property cycle interval for the datasource.
 javax.naming.Reference getReference()
           
 java.lang.String getServerName()
          Get the server name for the datasource.
 java.lang.String getUrl()
          Get the url for the datasource.
 java.lang.String getURL()
          Synonymous with getUrl();
 java.lang.String getUser()
          Get the user name for this datasource.
 void setConnectionVerifyTable(java.lang.String table)
          Set the connection verification table.
 void setDatabase(java.lang.String databaseName)
          changed to use setDatabaseName.
 void setDatabaseName(java.lang.String databaseName)
          Set the database name for the datasource.
 void setDescription(java.lang.String description)
          Set the description of the datasource.
 void setInitialPoolSize(int size)
          Set the initial pool size of the connection pool.
 void setLogfile(java.lang.String file)
          Sets the log file for this DataSource.
 void setLoginTimeout(int seconds)
          Sets the maximum time the data source will wait while attempting to connect to a database.
 void setLogWriter(java.io.PrintWriter out)
          Sets the log writer for this DataSource.
 void setManagementCycleTime(int seconds)
          changed to use the setPropertyCycle()
 void setMaxConnectionBacklog(java.lang.String number)
           
 void setMaxIdleTime(int seconds)
          Set the maximum idle time that controls when idle connections are removed from the pool.
 void setMaxPoolSize(int maxConnections)
          Set the maximum number of connections allowed in the connection pool.
 void setMinPoolSize(int minSize)
          Set the minimum number of connections required in the connection pool.
 void setPassword(java.lang.String password)
          Set the password for the connection.
 void setPortNumber(int portNumber)
          Set the port number for the connection
 void setProperties(java.util.Properties properties)
          Set property values from a set of properties.
 void setProperty(java.lang.String propertyName, java.lang.String propertyValue)
          Set the value of any datasource property.
 void setPropertyCycle(int seconds)
          Sets the interval that the pool should wait before enforcing the current policy defined by the values of connection pool properties.
 void setServerName(java.lang.String serverName)
          Set the server name for the machine running the database
 void setUrl(java.lang.String url)
          Set property values from a driver URL.
 void setURL(java.lang.String url)
          Synonymous with setUrl();
 void setUser(java.lang.String user)
          Set the user name for the connection.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debugLog

public static final boolean debugLog
See Also:
Constant Field Values
Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
Obtain a database connection using the datasource user and password properties.

Returns:
A new JDBC connection
Throws:
java.sql.SQLException - The database connection failed.

getConnection

public java.sql.Connection getConnection(java.lang.String username,
                                         java.lang.String password)
                                  throws java.sql.SQLException
Obtain a database connection using the supplied user and password properties. The supplied username and password will override any username or password set as datasource properties.

Parameters:
username - The user name for the connection
password - The password for the connection
Returns:
A new JDBC Connection
Throws:
java.sql.SQLException - The database connection failed.

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.String propertyValue)
Set the value of any datasource property.

Parameters:
propertyName - The property name, must be a valid property name for the driver
propertyValue - The property value

setProperties

public void setProperties(java.util.Properties properties)
Set property values from a set of properties.

Parameters:
properties - The property name-value pairs

setUrl

public void setUrl(java.lang.String url)
Set property values from a driver URL.

Parameters:
url - Any legal URL for the underlying driver.

getUrl

public java.lang.String getUrl()
Get the url for the datasource.

Returns:
url The url

setURL

public void setURL(java.lang.String url)
Synonymous with setUrl();


getURL

public java.lang.String getURL()
Synonymous with getUrl();


getProperties

public java.util.Properties getProperties()
Get property values for the datasource.

Returns:
properties The property name-value pairs

setServerName

public void setServerName(java.lang.String serverName)
Set the server name for the machine running the database

Parameters:
serverName - The name (or IP address) of the machine running the database to connect to. Used 'localhost' (or 127.0.0.1) for the local machine

getServerName

public java.lang.String getServerName()
Get the server name for the datasource.

Returns:
serverName The server name

setPortNumber

public void setPortNumber(int portNumber)
Set the port number for the connection

Parameters:
portNumber - The port number for the connection. The port number only needs to be set if you have changed the default configuration to use a port number other than the driver's default.

getPortNumber

public int getPortNumber()
Get the port number for the connection

Parameters:
portNumber - The port number for the connection. The port number only needs to be set if you have changed the default configuration to use a port number other than the driver's default.

setDatabaseName

public void setDatabaseName(java.lang.String databaseName)
Set the database name for the datasource.

Parameters:
databaseName - The name of the database, catalog or other configured datasource for the connection

getDatabaseName

public java.lang.String getDatabaseName()
Get the database name for the datasource.

Returns:
databaseName The name of the database.

setDatabase

public void setDatabase(java.lang.String databaseName)
changed to use setDatabaseName.


getDatabase

public java.lang.String getDatabase()
Deprecated. - Use getDatabaseName.


setUser

public void setUser(java.lang.String user)
Set the user name for the connection.

Parameters:
userName - The user name for authentication.

getUser

public java.lang.String getUser()
Get the user name for this datasource.

Returns:
The user name

setPassword

public void setPassword(java.lang.String password)
Set the password for the connection.

Parameters:
password - The user name for authentication.

getPassword

public java.lang.String getPassword()
Get the password for this datasource.

Returns:
The password

setDescription

public void setDescription(java.lang.String description)
Set the description of the datasource.

Parameters:
description - The description.

getDescription

public java.lang.String getDescription()
Get the description of the datasource.

Returns:
The datasource description.

setLoginTimeout

public void setLoginTimeout(int seconds)
Sets the maximum time the data source will wait while attempting to connect to a database.

Parameters:
seconds - The maximum time in seconds. Zero means no maximum is set.

getLoginTimeout

public int getLoginTimeout()
Gets the maximum time that the data source will wait while attempting to connect to a database.

Returns:
The maximum time in seconds. Zero means no maximum is set.

setLogWriter

public void setLogWriter(java.io.PrintWriter out)
Sets the log writer for this DataSource.

Parameters:
out - The given java.io.PrintWriter object.

getLogWriter

public java.io.PrintWriter getLogWriter()
Retrieves the log writer for this DataSource.

Returns:
The java.io.PrintWriter object

setLogfile

public void setLogfile(java.lang.String file)
Sets the log file for this DataSource.

Parameters:
file - The file name and path for the JDBC log file.

getLogfile

public java.lang.String getLogfile()
Retrieves the log file for this DataSource.

Returns:
The logfile

setMaxPoolSize

public void setMaxPoolSize(int maxConnections)
Set the maximum number of connections allowed in the connection pool. Attempts to connect more connections than the maximum will fail. Only available for connection pool datasources.

Parameters:
maxConnections - The maximum number. Zero means no maximum and is the default.

getMaxPoolSize

public int getMaxPoolSize()
Get the maximum number of connections allowed in the connection pool. Only available for connection pool datasources.


setMinPoolSize

public void setMinPoolSize(int minSize)
Set the minimum number of connections required in the connection pool. The pool manager will ensure that the pool always has this number of connections as a minimum. Only available for connection pool datasources.

Parameters:
minConnections - The minimum number. Zero means no minimum and is the default.

getMinPoolSize

public int getMinPoolSize()
Get the minimum number of connections allowed in the connection pool. Only available for connection pool datasources.


setMaxIdleTime

public void setMaxIdleTime(int seconds)
Set the maximum idle time that controls when idle connections are removed from the pool. If a physical connection remains unused longer than this value it will be closed. This property does not affect logical connections since they are in use. Only available for connection pool datasources.

Parameters:
seconds - The idle time in seconds. Zero means no maximum and is the default.

getMaxIdleTime

public int getMaxIdleTime()
Get the maximum idle time. Only available for connection pool datasources.


setInitialPoolSize

public void setInitialPoolSize(int size)
Set the initial pool size of the connection pool. When the pool is created this number of physical connections will created immediately. Only available for connection pool datasources.

Parameters:
size - The initial number of connections. Zero means no connections are created.

getInitialPoolSize

public int getInitialPoolSize()
Get the initial pool size.


setPropertyCycle

public void setPropertyCycle(int seconds)
Sets the interval that the pool should wait before enforcing the current policy defined by the values of connection pool properties.

Parameters:
seconds - The time in seconds

getPropertyCycle

public int getPropertyCycle()
Get the property cycle interval for the datasource.

Returns:
The time in seconds

setManagementCycleTime

public void setManagementCycleTime(int seconds)
changed to use the setPropertyCycle()


getManagementCycleTime

public int getManagementCycleTime()
Deprecated. - use getPropertyCycle()


setConnectionVerifyTable

public void setConnectionVerifyTable(java.lang.String table)
Set the connection verification table. The verify table is used in the following scenario:- Physical connections will exist in the connection pool when the application has closed the logical connections. If the database these physical connections are connected to is shut down (either deliberately or due to a system crash) these connections will be invalid. However, the connection pool does not continually monitor each connection to check it is still connected since this process would be very slow.

If verify table is set the pool will issue a SELECT * FROM on each physical connection that the pool uses to issue a logical connection to an application. If no errors are encountered the logical connection is issued. If an error is encountered the pool will discard the connection and recreate the physical connection.

This process will empty the connection pool of invalid connections and also ensure that the logical connection passed to the application is valid at the time it was issued. Of course, it is possible that the connection goes down while the application has it open but that is an exception the application must deal with. In this case the connection will be removed automatically from the pool.

Please note that only NetDirect pool managers will use this property.

If verify table is used it must exist in the database. For performance reasons it should contain the minimum number of (preferrably zero) rows. If verify table is not set the pool manager attempts no validation of connections before issuing logical connections to the application.


getConnectionVerifyTable

public java.lang.String getConnectionVerifyTable()
Get the verify table.


setMaxConnectionBacklog

public void setMaxConnectionBacklog(java.lang.String number)

getMaxConnectionBacklog

public java.lang.String getMaxConnectionBacklog()
Get the connection retry wait time.


getReference

public javax.naming.Reference getReference()
Specified by:
getReference in interface javax.naming.Referenceable