1.51.2

interbase.interclient
Class DataSource

java.lang.Object
  |
  +--interbase.interclient.DataSource

public class DataSource
extends Object
implements javax.sql.DataSource, javax.naming.Referenceable, Serializable

A factory for Connection and ServerManager objects. An object that implements the DataSource interface will typically be registered with a JNDI service provider. A JDBC driver that is accessed via the DataSource API does not automatically register itself with the DriverManager.

A DataSource class implements the javax.sql.DataSource interface. The javax.sql.DataSource interface provides a pair of getConnection() methods that can be invoked directly by user-level application code. A DataSource class should also implement the javax.naming.Referenceable and java.io.Serializable interfaces. These interfaces make it possible for instances of the DataSource class to be bound in a JNDI namespace. JNDI supports two separate mechanisms for storing objects that are bound in a namespace. The first is based on the javax.naming.Referenceable interface. The second approach is simply to store a serializable Java object as a sequence of bytes. For maximum portability a data source implementation should support both styles.

This DataSource class provides a set of properties that need to be given values so that a connection to a particular data source can be made. These properties, which follow the design pattern specified for JavaBeans TM components, are usually set when a data source object is deployed. Examples of data source properties include the location of the database server, the name of the database, the network protocol to use to communicate with the server, and so on.

The JDBC 2.0 Standard Extension specifies a simple policy for assigning JNDI names to data sources. All JDBC data sources should be registered in the jdbc naming subcontext of a JNDI namespace, or in one of its child subcontexts. The parent of the jdbc subcontext is the root naming context.

As an implementation of the javax.naming.Referenceable interface, a data source object can provide a Reference to itself. A Reference represents a way of recording address information about objects which themselves are not directly bound to the naming system. Such objects can implement the Referenceable interface as a way for programs that use that object to determine what its Reference is. For example, when binding an object, if an object implements the Referenceable interface, getReference() can be invoked on the object to get its Reference to use for binding.

The javax.naming.Referenceable interface contains a single method, getReference(), which is called by JNDI to obtain a Reference for a data source object when that object is bound in a JNDI naming service. The Reference object contains all of the information needed to reconstruct the data source object when it is later retrieved from JNDI.

The DataSource facility provides an alternative to the JDBC DriverManager, essentially duplicating all of the driver manager’s useful functionality. Although, both mechanisms may be used by the same application if desired, JavaSoft encourages developers to regard the DriverManager as a legacy feature of the JDBC API. Applications should use the DataSource API whenever possible. A JDBC implementation that is accessed via the DataSource API is not automatically registered with the DriverManager. The DriverManager, Driver, and DriverPropertyInfo interfaces may be deprecated in the future.

Note that the getter and setter methods for a property are defined on the implementation class and not in the DataSource interface. This creates some separation between the management API for DataSource objects and the API used by applications. Applications shouldn't need to access/change properties, but management tools can get at them using introspection.

InterClient Notes: See DataSource and Connection Properties for a specification of the InterClient and JDBC Standard Extension data source properties.

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

 interbase.interclient.DataSource dataSource = new interbase.interclient.DataSource ();
 dataSource.setServerName (“pongo”);
 dataSource.setDatabaseName (“/databases/employee.gdb”);
 javax.naming.Context context = new javax.naming.InitialContext();
 context.bind (“jdbc/EmployeeDB”, 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, “EmployeeDB”, 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/EmployeeDB”);
 java.sql.Connection con = dataSource.getConnection (“sysdba”, “masterkey”);
 
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.

Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0
Version:
Std Ext 0.7, JNDI 1.1.1
See Also:
ObjectFactory, Serialized Form

Constructor Summary
DataSource()
          Create a data source with default property values.
 
Method Summary
 String getCharSet()
          Gets the charSet property value.
 Connection getConnection()
          Attempt to establish a database connection.
 Connection getConnection(String user, String password)
          Attempt to establish a database connection.
 String getDatabaseName()
          Gets the JDBC Standard Extension databaseName property value.
 String getDataSourceName()
          Gets the JDBC Standard Extension dataSourceName property value.
 String getDescription()
          Gets the JDBC Standard Extension description property value.
 String getInterBaseLicense()
          Gets the interBaseLicense property value.
 int getLoginTimeout()
          Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
 PrintWriter getLogWriter()
          Get the log writer for this data source.
 String getNetworkProtocol()
          Gets the JDBC Standard Extension networkProtocol property value.
 String getPassword()
          Gets the JDBC Standard Extension password property value.
 int getPortNumber()
          Gets the JDBC Standard Extension portNumber property value.
 javax.naming.Reference getReference()
          Creates a JNDI naming Reference of this data source.
 String getRoleName()
          Gets the JDBC Standard Extension roleName property value.
 ServerManager getServerManager()
          Creates a special attachment to the datasource for the purpose of managing an InterBase server.
 ServerManager getServerManager(String user, String password)
          Attempts to create a special attachment to the datasource for the purpose of managing an InterBase server.
 String getServerManagerHost()
          Gets the serverManagerHost property value.
 String getServerName()
          Gets the JDBC Standard Extension serverName property value.
 int getSuggestedCachePages()
          Gets the suggestedCachePages property value.
 boolean getSweepOnConnect()
          Gets the sweepOnConnect property value.
 String getUser()
          Gets the JDBC Standard Extension user property value.
 void setCharSet(String charSet)
          Sets the charSet property value.
 void setDatabaseName(String databaseName)
          Sets the JDBC Standard Extension databaseName property value.
 void setDataSourceName(String dataSourceName)
          Sets the JDBC Standard Extension dataSourceName property value.
 void setDescription(String description)
          Sets the JDBC Standard Extension description property value.
 void setInterBaseLicense(String interBaseLicense)
          Sets the interBaseLicense property value.
 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(PrintWriter out)
          Set the log writer for this data source.
 void setNetworkProtocol(String networkProtocol)
          Sets the JDBC Standard Extension networkProtocol property value.
 void setPassword(String password)
          Sets the JDBC Standard Extension password property value.
 void setPortNumber(int portNumber)
          Sets the JDBC Standard Extension portNumber property value.
 void setRoleName(String roleName)
          Sets the JDBC Standard Extension roleName property value.
 void setServerManagerHost(String serverManagerHost)
          Sets the serverManagerHost property value.
 void setServerName(String serverName)
          Sets the JDBC Standard Extension serverName property value.
 void setSuggestedCachePages(int suggestedCachePages)
          Sets the suggestedCachePages property value.
 void setSweepOnConnect(boolean sweepOnConnect)
          Sets the sweepOnConnect property value.
 void setUser(String user)
          Sets the JDBC Standard Extension user property value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataSource

public DataSource()
Create a data source with default property values. 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.

Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0
Method Detail

getDatabaseName

public String getDatabaseName()
Gets the JDBC Standard Extension databaseName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setDatabaseName

public void setDatabaseName(String databaseName)
Sets the JDBC Standard Extension databaseName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getDataSourceName

public String getDataSourceName()
Gets the JDBC Standard Extension dataSourceName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setDataSourceName

public void setDataSourceName(String dataSourceName)
Sets the JDBC Standard Extension dataSourceName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getDescription

public String getDescription()
Gets the JDBC Standard Extension description property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setDescription

public void setDescription(String description)
Sets the JDBC Standard Extension description property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getNetworkProtocol

public String getNetworkProtocol()
Gets the JDBC Standard Extension networkProtocol property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setNetworkProtocol

public void setNetworkProtocol(String networkProtocol)
Sets the JDBC Standard Extension networkProtocol property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getPassword

public String getPassword()
Gets the JDBC Standard Extension password property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setPassword

public void setPassword(String password)
Sets the JDBC Standard Extension password property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getPortNumber

public int getPortNumber()
Gets the JDBC Standard Extension portNumber property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setPortNumber

public void setPortNumber(int portNumber)
Sets the JDBC Standard Extension portNumber property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getRoleName

public String getRoleName()
Gets the JDBC Standard Extension roleName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setRoleName

public void setRoleName(String roleName)
Sets the JDBC Standard Extension roleName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getServerName

public String getServerName()
Gets the JDBC Standard Extension serverName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setServerName

public void setServerName(String serverName)
Sets the JDBC Standard Extension serverName property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getUser

public String getUser()
Gets the JDBC Standard Extension user property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setUser

public void setUser(String user)
Sets the JDBC Standard Extension user property value. See DataSource properties.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getCharSet

public String getCharSet()
Gets the charSet property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0

setCharSet

public void setCharSet(String charSet)
Sets the charSet property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0

getInterBaseLicense

public String getInterBaseLicense()
Gets the interBaseLicense property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

setInterBaseLicense

public void setInterBaseLicense(String interBaseLicense)
Sets the interBaseLicense property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

getServerManagerHost

public String getServerManagerHost()
Gets the serverManagerHost property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0

setServerManagerHost

public void setServerManagerHost(String serverManagerHost)
Sets the serverManagerHost property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0

getSuggestedCachePages

public int getSuggestedCachePages()
Gets the suggestedCachePages property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

setSuggestedCachePages

public void setSuggestedCachePages(int suggestedCachePages)
Sets the suggestedCachePages property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

getSweepOnConnect

public boolean getSweepOnConnect()
Gets the sweepOnConnect property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

setSweepOnConnect

public void setSweepOnConnect(boolean sweepOnConnect)
Sets the sweepOnConnect property value. See DataSource properties.
Since:
Extension, proposed for InterClient 2.0, not yet supported

getConnection

public Connection getConnection()
                         throws SQLException
Attempt to establish a database connection.
Specified by:
getConnection in interface javax.sql.DataSource
Returns:
a Connection to the database
Throws:
SQLException - if a database-access error occurs.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getConnection

public Connection getConnection(String user,
                                String password)
                         throws SQLException
Attempt to establish a database connection.
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:
SQLException - if a database-access error occurs.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

setLogWriter

public void setLogWriter(PrintWriter out)
                  throws SQLException
Set the log writer for this data source.

This method provides a way to register a character stream to which tracing and error logging information will be written by a JDBC implementation. This allows for DataSource specific tracing. If one wants all Data-Sources to use the same log stream, one must register the stream with each DataSource object individually. Log messages written to a DataSource specific log stream are not written to the log stream maintained by the DriverManager. When a DataSource object is created the log writer is initially null, in other words, logging is disabled.

The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled.

Specified by:
setLogWriter in interface javax.sql.DataSource
Parameters:
out - the new log writer; to disable, set to null
Throws:
SQLException - if a database-access error occurs.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

getLogWriter

public PrintWriter getLogWriter()
                         throws SQLException
Get the log writer for this data source.

The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled.

Specified by:
getLogWriter in interface javax.sql.DataSource
Returns:
the log writer for this data source, null if disabled
Throws:
SQLException - if a database-access error occurs.
Since:
JDBC 2 Standard Extension, proposed for future release, not yet supported

setLoginTimeout

public void setLoginTimeout(int seconds)
                     throws SQLException
Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a DataSource object is created the login timeout is initially zero.
Specified by:
setLoginTimeout in interface javax.sql.DataSource
Parameters:
seconds - the data source login time limit
Throws:
SQLException - if a database access error occurs.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getLoginTimeout

public int getLoginTimeout()
                    throws SQLException
Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. A value of zero means that the timeout is the default system timeout if there is one; otherwise it means that there is no timeout. When a DataSource object is created the login timeout is initially zero.
Specified by:
getLoginTimeout in interface javax.sql.DataSource
Returns:
the data source login time limit
Throws:
SQLException - if a database access error occurs.
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getReference

public javax.naming.Reference getReference()
                                    throws javax.naming.NamingException
Creates a JNDI naming Reference of this data source.
Specified by:
getReference in interface javax.naming.Referenceable
Returns:
the non-null reference of this object
Throws:
javax.naming.NamingException - if a naming exception was encountered while retrieving the reference
Since:
JDBC 2 Standard Extension, proposed for InterClient 2.0

getServerManager

public ServerManager getServerManager()
                               throws SQLException
Creates a special attachment to the datasource for the purpose of managing an InterBase server.

The server manager attachment is to an InterServer host, but a target InterBase host may optionally be specified using the serverManagerHost property. If this property is null, then it is assumed that the InterBase host to be serviced is the same as the InterServer host.

Many server manager operations may require you to pass the SYSDBA user and password.

Note: This does not start the InterBase server. The InterBase server must be started manually, or by using ServerManager.startInterBase(defaultCachePages, defaultPageSize).

Returns:
a service connection to the interserver host in the form of a ServerManager object
Throws:
SQLException - if a server access error occurs
Since:
Extension, proposed for InterClient 2.0

getServerManager

public ServerManager getServerManager(String user,
                                      String password)
                               throws SQLException
Attempts to create a special attachment to the datasource for the purpose of managing an InterBase server. The user and password to be used while servicing the InterBase server are given. See getServerManager() for more details.
Returns:
a service connection to the interserver host in the form of a ServerManager object
Throws:
SQLException - if a server access error occurs
Since:
Extension, proposed for InterClient 2.0

1.51.2

Send comments or suggestions to interclient@interbase.com