Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## interbase.interclient
Class DataSource

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

All Implemented Interfaces:
  javax.sql.DataSource, javax.naming.Referenceable, Serializable

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()`
`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` | `getSQLDialect()` Gets the `sqlDialect` 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` | `setSQLDialect(int sqlDialect)` Sets the `sqlDialect` 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 3.0, not yet supported

### setInterBaseLicense

    public void setInterBaseLicense(String interBaseLicense)

  Sets the `interBaseLicense` property value. See DataSource properties.
  Since:
    Extension, proposed for InterClient 3.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 3.0, not yet supported

### setSuggestedCachePages

    public void setSuggestedCachePages(int suggestedCachePages)

  Sets the `suggestedCachePages` property value. See DataSource properties.
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getSweepOnConnect

    public boolean getSweepOnConnect()

  Gets the `sweepOnConnect` property value. See DataSource properties.
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### setSweepOnConnect

    public void setSweepOnConnect(boolean sweepOnConnect)

  Sets the `sweepOnConnect` property value. See DataSource properties.
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getSQLDialect

    public int getSQLDialect()

  Gets the `sqlDialect` property value. See DataSource properties.
  Since:
    JDBC 2 Standard Extension, proposed for InterClient 2.0

### setSQLDialect

    public void setSQLDialect(int sqlDialect)

  Sets the `sqlDialect` property value. See DataSource properties.
  Since:
    JDBC 2 Standard Extension, proposed for InterClient 2.0

### getConnection

    public Connection getConnection()
                             throws SQLException

  Specified by:
    `getConnection` in interface `javax.sql.DataSource`

### 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

Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Send comments or suggestions to interclient@borland.com