|
1.51.2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--interbase.interclient.DataSource
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.
ObjectFactory
, Serialized FormConstructor 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 |
public DataSource()
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 Detail |
public String getDatabaseName()
databaseName
property value.
See DataSource properties.public void setDatabaseName(String databaseName)
databaseName
property value.
See DataSource properties.public String getDataSourceName()
dataSourceName
property value.
See DataSource properties.public void setDataSourceName(String dataSourceName)
dataSourceName
property value.
See DataSource properties.public String getDescription()
description
property value.
See DataSource properties.public void setDescription(String description)
description
property value.
See DataSource properties.public String getNetworkProtocol()
networkProtocol
property value.
See DataSource properties.public void setNetworkProtocol(String networkProtocol)
networkProtocol
property value.
See DataSource properties.public String getPassword()
password
property value.
See DataSource properties.public void setPassword(String password)
password
property value.
See DataSource properties.public int getPortNumber()
portNumber
property value.
See DataSource properties.public void setPortNumber(int portNumber)
portNumber
property value.
See DataSource properties.public String getRoleName()
roleName
property value.
See DataSource properties.public void setRoleName(String roleName)
roleName
property value.
See DataSource properties.public String getServerName()
serverName
property value.
See DataSource properties.public void setServerName(String serverName)
serverName
property value.
See DataSource properties.public String getUser()
user
property value.
See DataSource properties.public void setUser(String user)
user
property value.
See DataSource properties.public String getCharSet()
charSet
property value.
See DataSource properties.public void setCharSet(String charSet)
charSet
property value.
See DataSource properties.public String getInterBaseLicense()
interBaseLicense
property value.
See DataSource properties.public void setInterBaseLicense(String interBaseLicense)
interBaseLicense
property value.
See DataSource properties.public String getServerManagerHost()
serverManagerHost
property value.
See DataSource properties.public void setServerManagerHost(String serverManagerHost)
serverManagerHost
property value.
See DataSource properties.public int getSuggestedCachePages()
suggestedCachePages
property value.
See DataSource properties.public void setSuggestedCachePages(int suggestedCachePages)
suggestedCachePages
property value.
See DataSource properties.public boolean getSweepOnConnect()
sweepOnConnect
property value.
See DataSource properties.public void setSweepOnConnect(boolean sweepOnConnect)
sweepOnConnect
property value.
See DataSource properties.public Connection getConnection() throws SQLException
public Connection getConnection(String user, String password) throws SQLException
user
- the database user on whose behalf the Connection is being madepassword
- the user's passwordpublic void setLogWriter(PrintWriter out) throws SQLException
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.
out
- the new log writer; to disable, set to nullpublic PrintWriter getLogWriter() throws SQLException
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.
public void setLoginTimeout(int seconds) throws SQLException
seconds
- the data source login time limitpublic int getLoginTimeout() throws SQLException
public javax.naming.Reference getReference() throws javax.naming.NamingException
public ServerManager getServerManager() throws SQLException
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).
public ServerManager getServerManager(String user, String password) throws SQLException
|
1.51.2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |