com.ibm.db.beans
Class DBConnectionSpec

java.lang.Object
  |
  +--com.ibm.db.beans.DBConnectionSpec
All Implemented Interfaces:
java.io.Serializable

public class DBConnectionSpec
extends java.lang.Object
implements java.io.Serializable

This bean contains the specifictions for a database connection. You set the properties of this bean before actually connecting to the database. Those properties will determine how the database connection is established (such as using a DataSource or using the DriverManager).

You associate a statement with a DBConnectionSpec via the DBStatement.setConnectionSpec() method. The statement will then use the specification in the DBConnectionSpec to obtain a connection. Setting a statement's DBConnectionSpec is an alternative to setting the connection properties directly on the statement. It is useful if more than one statement will be using the same connection specifications.

The DBConnectionSpec only contains connection properties that cannot be changed after a connection has been obtained. You set connection properties (like autoCommit and transactionIsolation) that can be changed after a connection has been obtained directly on the statement.

If a DataSourceName is specified, a reference to the DataSource found through the JNDI lookup when a connection is obtained is saved in the DBConnectionSpec. If the DBConnectionSpec is used again to obtain a connection, the connection can be obtained from the DataSource without requiring a JNDI lookup again.

If two beans share the same DBConnectionSpec, it does not mean that they will share the same database connection. To make two beans share the same connection use the DBStatement.shareConnectionWith() method.

See Also:
Serialized Form

Constructor Summary
DBConnectionSpec()
          The default constructor
 
Method Summary
 java.lang.String getDataSourceName()
          Gets the JNDI name of the javax.sql.DataSource to use when opening a database connection.
 java.lang.String getDriverName()
          Gets the class name of the JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.
 java.lang.String getInitialContextFactory()
          Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.
 java.lang.Object getInternalUseObject(int aType)
          For Internal Use only.
 java.io.PrintWriter getLogWriter()
          Gets the PrintWriter being used to log any error information written by this bean.
 java.lang.String getPassword()
          Returns a String of asterisks (*) the length of the password used to create a database connection.
 boolean getPromptUID()
          Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.
 java.util.Properties getProperties()
          Returns the connection properties for this DBConnectionSpec.
 java.lang.String getProviderUrl()
          Gets the URL of the machine where the naming service should look for a javax.sql.DataSource.
 java.lang.String getUrl()
          Gets the url of the database to connect to using the DriverManager.
 java.lang.String getUsername()
          Gets the user name used to create a database connection.
 void setDataSourceName(java.lang.String aName)
          Specifies the name of a javax.sql.DataSource to use when opening a database connection, and clears any value previously set for the url property.
 void setDriverName(java.lang.String aDriverName)
          Specifies the class name of a JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.
 void setInitialContextFactory(java.lang.String aInitialContextFactory)
          Specifies the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.
 void setInternalUseObject(java.lang.Object aDataSource)
          For Internal Use only.
 void setLogWriter(java.io.PrintWriter out)
          Provides the PrintWriter that will be used to log any error information written by this bean.
 void setPassword(java.lang.String aPassword)
          Sets the password used to create a database connection.
 void setPassword(java.lang.String aPassword, boolean decode)
          Sets the password used to create a database connection.
 void setProperties(java.util.Properties properties)
          Sets the connection properties to use when establishing a connection.
 void setProviderUrl(java.lang.String aProviderUrl)
          Specifies the URL of the machine where the naming service should look for a javax.sql.DataSource.
 void setUrl(java.lang.String aUrl)
          Specifies the url of the database to connect to using the DriverManager, and clears any value previously set for the dataSourceName property.
 void setUsername(java.lang.String aName)
          Sets the user name used to create a database connection.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DBConnectionSpec

public DBConnectionSpec()
The default constructor

Method Detail

getDataSourceName

public java.lang.String getDataSourceName()
Gets the JNDI name of the javax.sql.DataSource to use when opening a database connection. Users should set either the url or dataSourceName property.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

Returns:
the name of the javax.sql.DataSource
See Also:
setDataSourceName(java.lang.String), getInitialContextFactory(), getProviderUrl()

getDriverName

public java.lang.String getDriverName()
Gets the class name of the JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.

If this property is null or an empty string, no driver will be automaticaly loaded and registered. It may still be possible to connect via the DriverManager if an appropriate driver has been loaded and registered independently of this bean.

This property is only used if the url property is not null. If the url property is null, then this field is ignored and the connection is obtained using the DataSource specified in the dataSourceName property.

Returns:
the class name of the JDBC driver to load and register
See Also:
setDriverName(java.lang.String), getUrl()

getInitialContextFactory

public java.lang.String getInitialContextFactory()
Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.

If this property is null, the default InitialContextFactory identified by the java.naming.factory.initial property in your java environment will be used.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Returns:
the class name of the InitialContexFactory used to locate the DataSource.
See Also:
setInitialContextFactory(java.lang.String), getDriverName(), getProviderUrl()

getInternalUseObject

public java.lang.Object getInternalUseObject(int aType)
For Internal Use only. Do not use.


getLogWriter

public java.io.PrintWriter getLogWriter()
Gets the PrintWriter being used to log any error information written by this bean.

The default log writer logs to the Java console. When this property is set to null, no information is logged.

See Also:
setLogWriter(java.io.PrintWriter)

getPassword

public java.lang.String getPassword()
Returns a String of asterisks (*) the length of the password used to create a database connection. The actual password is not returned so that the return value of this method can be displayed in a GUI without compromising security.

Returns:
a String of asterisks (*) the length of the password
See Also:
setPassword(String), setPassword(String, boolean)

getPromptUID

public boolean getPromptUID()
Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.

If this property is null, the default InitialContextFactory identified by the java.naming.factory.initial property in your java environment will be used.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Returns:
the class name of the InitialContexFactory used to locate the DataSource.
See Also:
setInitialContextFactory(java.lang.String), getDriverName(), getProviderUrl()

getProperties

public java.util.Properties getProperties()
Returns the connection properties for this DBConnectionSpec. Properties specify keyword/value pairs other than username and password required for connecting to the database. Username and password can be set separately.

Returns:
the connection properties
See Also:
setProperties(java.util.Properties), getUsername(), getPassword()

getProviderUrl

public java.lang.String getProviderUrl()
Gets the URL of the machine where the naming service should look for a javax.sql.DataSource.

If this property is null, the naming service will look on the local host.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Returns:
the URL of the machine where the naming service should look for a DataSource
See Also:
setProviderUrl(java.lang.String), getDataSourceName(), getInitialContextFactory()

getUrl

public java.lang.String getUrl()
Gets the url of the database to connect to using the DriverManager. The default value is null.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

Returns:
the url of the database
See Also:
setUrl(java.lang.String), getDriverName()

getUsername

public java.lang.String getUsername()
Gets the user name used to create a database connection.

Returns:
a user name
See Also:
setUsername(java.lang.String)

setDataSourceName

public void setDataSourceName(java.lang.String aName)
Specifies the name of a javax.sql.DataSource to use when opening a database connection, and clears any value previously set for the url property.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

See Also:
getDataSourceName(), setInitialContextFactory(java.lang.String), setProviderUrl(java.lang.String)

setDriverName

public void setDriverName(java.lang.String aDriverName)
Specifies the class name of a JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection. The name must be fully qualified with the package containing the driver. For example, the DB2 application JDBC driver is COM.ibm.db2.jdbc.appDB2Driver.

If this property is null or an empty string, no driver will be automaticaly loaded and registered. It may still be possible to connect via the DriverManager if an appropriate driver has been loaded and registered independently of this bean.

This property is only used if the url property is not null. If the url property is null, then this field is ignored and the connection is obtained using the DataSource specified in the dataSourceName property.

See Also:
getDriverName(), setUrl(java.lang.String)

setInitialContextFactory

public void setInitialContextFactory(java.lang.String aInitialContextFactory)
Specifies the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource. The name must be fully qualified with the package containing the class. For example, the InitialContextFactory for the WebSphere naming service is com.ibm.ejs.ns.jndi.CNInitialContextFactory.

If you set this property to null, the default InitialContextFactory identified by the property java.naming.factory.initial in your java environment will be used.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

See Also:
getInitialContextFactory(), setDataSourceName(java.lang.String), setProviderUrl(java.lang.String)

setInternalUseObject

public void setInternalUseObject(java.lang.Object aDataSource)
For Internal Use only. Do not use.


setLogWriter

public void setLogWriter(java.io.PrintWriter out)
Provides the PrintWriter that will be used to log any error information written by this bean.

If you do not explicitly use this method to provide a PrintWriter, information is logged by default to the Java console. If you wish to have no information logged, you can provide a null value here. If you wish to have log information for this bean and log information for your database written to the same place, provide the same PrintWriter for both the DriverManager.setLogWriter() method and this method.

Parameters:
out - the PrintWriter that will be used for logging
See Also:
getLogWriter()

setPassword

public void setPassword(java.lang.String aPassword)
Sets the password used to create a database connection. If the value passed in is a String of asterisks (*) the length of the current password, the value is not set. It is assumed in this case that a property editor has used getPassword() to get the password shape, and has used that same value to set the password, without real intent to change the password.

See Also:
getPassword(), setPassword(String, boolean)

setPassword

public void setPassword(java.lang.String aPassword,
                        boolean decode)
                 throws DBException
Sets the password used to create a database connection. If requested, the password is decoded before it is saved.

Throws:
DBException - decodeError - if password cannot be decoded
See Also:
getPassword(), setPassword(String)

setProperties

public void setProperties(java.util.Properties properties)
Sets the connection properties to use when establishing a connection. Use properties to specify keyword/value pairs other than username and password required for connecting to the database. Username and password can be set separately.

Parameters:
properties - the connection properties
See Also:
getProperties(), setPassword(java.lang.String), setUsername(java.lang.String)

setProviderUrl

public void setProviderUrl(java.lang.String aProviderUrl)
Specifies the URL of the machine where the naming service should look for a javax.sql.DataSource.

If you set this property to null, the naming service will look on the local host.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

See Also:
getProviderUrl(), setDataSourceName(java.lang.String), setInitialContextFactory(java.lang.String)

setUrl

public void setUrl(java.lang.String aUrl)
Specifies the url of the database to connect to using the DriverManager, and clears any value previously set for the dataSourceName property. The default value is null.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

To connect using the Driver Manager, you must either insure that a driver that accepts the url has been loaded and registered, or use the setDriverName method to cause such a driver to be automatically loaded and registered for you.

See Also:
getUrl(), setDriverName(java.lang.String)

setUsername

public void setUsername(java.lang.String aName)
Sets the user name used to create a database connection.

See Also:
getUsername()