Class Hierarchy Index
Class COM.cloudscape.core.AbstractDataSource
java.lang.Object
|
+----COM.cloudscape.core.AbstractDataSource
- public abstract class AbstractDataSource
- extends Object
- implements Referenceable, Serializable
Copyright © 1998-1999, Cloudscape, Inc. All rights reserved.
This is the base abstract class extended by all DataSources.
A DataSource object is a factory for Connection 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.
This object has 2 purposes:
- to be referenceable by a JNDI server
- to act as a base for a subclass to satisfy different DataSource interfaces
The following is a list of properties that can be set on a cloudscape
DataSource object:
- DatabaseName: Mandatory. This property must be set and it
identifies which database to access. If a database named wombat located at
g:/db/wombat is to be accessed, then one should call
setDatabaseName("g:/db/wombat") on the data source object.
- CreateDatabase: Optional. If set to the string "create", this will
cause a new database of DatabaseName if that database does not already
exist. The database is created when a connection object is obtained from
the data source.
- ShutdownDatabase: Optional. If set to the string "shutdown",
this will cause the database to shutdown when a java.sql.Connection object
is obtained from the data source. E.g., If the data source is an
XADataSource, a getXAConnection().getConnection() is necessary to cause the
database to shutdown.
- DataSourceName: Optional. Name for ConnectionPooledDataSource
or XADataSource. Not used by the data source object. Used for
informational purpose only.
- Description: Optional. Description of the data source. Not
used by the data source object. Used for informational purpose only.
- RemoteDataSourceProtocol: Optional. If the database is remote
and the data source accesses the database via client server, set this
property to specify what client/server protocol to use. Currently, only
BasicDataSource and ConnectionPoolDataSource support remote access, and
the only protocol supported is "rmi". To use a ConnectionPoolDataSource
on a remote data base, either tools.jar or cloudscape.jar must be in the
classpath. Client.jar alone does not have the necessary classes for remote
ConnectionPoolDataSource access.
- CloudscapeProperties: Optional. Connection attributes specific
to cloudscape. Please see cloudscape documentation for a complete list of
features.
Examples.
This is an example of setting a property directly using cloudscape
DataSource object. This code is typically written by a system integrator :
import COM.cloudscape.core.*;
// dbname is the database name
// if create is true, create the database if necessary
javax.sql.DataSource makeDataSource (String dbname, boolean create)
throws Throwable
{
BasicDataSource ds = DataSourceFactory.getDataSource();
ds.setDatabaseName(dbname);
if (create)
ds.setCreateDatabase("create");
return ds;
}
Example of using a DataSource object to connect to a remote machine
named alpha, at port number 1099.
This code is typically written by a system integrator :
import COM.cloudscape.core.*;
javax.sql.DataSource
makeRemoteDataSource (String dbname, String machine, int port)
throws Throwable
{
BasicDataSource ds = DataSourceFactory.getDataSource();
ds.setDatabaseName(dbname);
ds.setRemoteDataSourceProtocol("rmi://alpha:1099/");
return ds;
}
Example of setting properties thru reflection. This code is typically
generated by tools or written by a system integrator:
javax.sql.DataSource makeCloudscapeDataSource(String dbname)
throws Throwable
{
Class[] parameter = new Class[1];
parameter[0] = dbname.getClass();
DataSource ds = DataSourceFactory.getDataSource();
Class cl = ds.getClass();
Method setName = cl.getMethod("setDatabaseName", parameter);
Object[] arg = new Object[1];
arg[0] = dbname;
setName.invoke(ds, arg);
return ds;
}
Example on how to register a data source object with a JNDI naming
service.
DataSource ds = makeCloudscapeDataSource("mydb");
Context ctx = new InitialContext();
ctx.bind("jdbc/MyDB", ds);
Example on how to retrieve a data source object from a JNDI naming
service.
Context ctx = new InitialContext();
DataSoruce ds = (DataSource)ctx.lookup("jdbc/MyDB");
-
driver
-
-
findDriver(String)
-
-
getCloudscapeProperties()
-
-
getCreateDatabase()
-
-
getDatabaseConnection()
-
Attempt to establish a database connection.
-
getDatabaseConnection(String, String)
-
Attempt to establish a database connection.
-
getDatabaseName()
-
-
getDataSourceName()
-
-
getDescription()
-
-
getLoginTimeout()
- Gets the maximum time in seconds that this data source can wait
while attempting to connect to a database.
-
getLogWriter()
-
Get the log writer for this data source.
-
getReference()
- Referenceable method.
-
getRemoteDataSourceProtocol()
-
-
getShutdownDatabase()
-
-
makeURL()
-
-
populateInfo(Properties)
-
-
setCloudscapeProperties(String)
- Set this property to pass in more cloudscape specific
connection URL attributes.
-
setCreateDatabase(String)
- Set this property to create a new database.
-
setDatabaseName(String)
-
Set the database name.
-
setDataSourceName(String)
-
Set the data source name.
-
setDescription(String)
- Set the data source descripton.
-
setLoginTimeout(int)
-
Sets the maximum time in seconds that this data source will wait
while attempting to connect to a database.
-
setLogWriter(PrintWriter)
-
Set the log writer for this data source.
-
setRemoteDataSourceProtocol(String)
- Set this property to access a database on a remote site.
-
setShutdownDatabase(String)
- Set this property if one wishes to shutdown the database identified by
databaseName.
driver
protected static transient Driver driver
getReference
public Reference getReference() throws NamingException
- Referenceable method.
- Throws: NamingException
- cannot find named object
setDatabaseName
public void setDatabaseName(String dbname)
- Set the database name. Setting this property is mandatory. If a
database named wombat at g:/db needs to be accessed, database name
should be set to "g:/db/wombat". The database must be local, a data
source cannot access a remote database via client/server. The database
will be booted if it is not already running in the
system.
- Parameters:
- dbname - the name of the database
getDatabaseName
public String getDatabaseName()
- Returns:
- database name
setDataSourceName
public void setDataSourceName(String dsn)
- Set the data source name. The property is not mandatory. It is used
for informational purposes only.
- Parameters:
- dsn - the name of the data source
getDataSourceName
public String getDataSourceName()
- Returns:
- data source name
setDescription
public void setDescription(String desc)
- Set the data source descripton. This property is not mandatory.
It is used for informational purposes only.
- Parameters:
- desc - the description of the data source
getDescription
public String getDescription()
- Returns:
- description
setCreateDatabase
public void setCreateDatabase(String create)
- Set this property to create a new database. If this
property is not set, the database (identified by databaseName) is
assumed to be already existing.
- Parameters:
- create - if set to the string "create", this data source will try
to create a new database of databaseName, or boot the database if one
by that name already exists.
getCreateDatabase
public String getCreateDatabase()
- Returns:
- "create" if create is set, or null if not
setShutdownDatabase
public void setShutdownDatabase(String shutdown)
- Set this property if one wishes to shutdown the database identified by
databaseName.
- Parameters:
- shutdown - if set to the string "shutdown", this data source will
shutdown the database if it is running.
getShutdownDatabase
public String getShutdownDatabase()
- Returns:
- "shutdown" if shutdown is set, or null if not
setCloudscapeProperties
public void setCloudscapeProperties(String prop)
- Set this property to pass in more cloudscape specific
connection URL attributes.
- Parameters:
- prop - set to the list of cloudcape connection
attributes separated by semi-colons. E.g., to specify an encryption
bootPassword of "cloudscape", and set upgrade to true, do the following:
ds.setCloudscapeProperties("bootPassword=cloudscape;upgrade=true");
See cloudscape documentation for complete list.
getCloudscapeProperties
public String getCloudscapeProperties()
- Returns:
- cloudscape specific connection URL attributes
setRemoteDataSourceProtocol
public void setRemoteDataSourceProtocol(String protocol)
- Set this property to access a database on a remote site.
- Parameters:
- protocol - Remote access protocol, rmi is the only protocol
currently supported. The protocol string is of the form
"rmi[://rmiHostname:port/]".
// to connect to database on the same machine using rmi (for security
// reasons maybe)
datasource.setRemoteDataSourceProtocol("rmi");
// to connect to database on another machine xyz using cloudscape
// default port number 1099
datasource.setRemoteDataSourceProtocol("rmi://xyz:1099/");
getRemoteDataSourceProtocol
public String getRemoteDataSourceProtocol()
- Returns:
- remote access protocol
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 data source object is created, the login timeout is
initially zero.
- Returns:
- the data source login time limit
- Throws: SQLException
- if a database access error occurs.
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 data source object is created, the login timeout is
initially zero.
- Parameters:
- seconds - the data source login time limit
- Throws: SQLException
- if a database access error occurs.
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 data source object is
created the log writer is initially null, in other words, logging
is disabled.
- Returns:
- the log writer for this data source, null if disabled
- Throws: SQLException
- if a database-access error occurs.
setLogWriter
public void setLogWriter(PrintWriter out) throws SQLException
-
Set 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 data source object is
created the log writer is initially null, in other words, logging
is disabled.
- Parameters:
- out - the new log writer; to disable, set to null
- Throws: SQLException
- if a database-access error occurs.
getDatabaseConnection
public Connection getDatabaseConnection() throws SQLException
-
Attempt to establish a database connection.
- Returns:
- a Connection to the database
- Throws: SQLException
- if a database-access error occurs.
getDatabaseConnection
public Connection getDatabaseConnection(String username,
String password) throws SQLException
-
Attempt to establish a database connection.
- 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.
populateInfo
public void populateInfo(Properties info)
findDriver
protected void findDriver(String url) throws SQLException
makeURL
public String makeURL()
Class Hierarchy Index