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:

The following is a list of properties that can be set on a cloudscape DataSource object:

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");


Variable Index

 o driver

Method Index

 o findDriver(String)
 o getCloudscapeProperties()
 o getCreateDatabase()
 o getDatabaseConnection()

Attempt to establish a database connection.

 o getDatabaseConnection(String, String)

Attempt to establish a database connection.

 o getDatabaseName()
 o getDataSourceName()
 o getDescription()
 o getLoginTimeout()
Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
 o getLogWriter()

Get the log writer for this data source.

 o getReference()
Referenceable method.
 o getRemoteDataSourceProtocol()
 o getShutdownDatabase()
 o makeURL()
 o populateInfo(Properties)
 o setCloudscapeProperties(String)
Set this property to pass in more cloudscape specific connection URL attributes.
 o setCreateDatabase(String)
Set this property to create a new database.
 o setDatabaseName(String)
Set the database name.
 o setDataSourceName(String)
Set the data source name.
 o setDescription(String)
Set the data source descripton.
 o setLoginTimeout(int)

Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.

 o setLogWriter(PrintWriter)

Set the log writer for this data source.

 o setRemoteDataSourceProtocol(String)
Set this property to access a database on a remote site.
 o setShutdownDatabase(String)
Set this property if one wishes to shutdown the database identified by databaseName.

Variables

 o driver
 protected static transient Driver driver

Methods

 o getReference
 public Reference getReference() throws NamingException
Referenceable method.

Throws: NamingException
cannot find named object
 o 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
 o getDatabaseName
 public String getDatabaseName()
Returns:
database name
 o 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
 o getDataSourceName
 public String getDataSourceName()
Returns:
data source name
 o 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
 o getDescription
 public String getDescription()
Returns:
description
 o 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.
 o getCreateDatabase
 public String getCreateDatabase()
Returns:
"create" if create is set, or null if not
 o 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.
 o getShutdownDatabase
 public String getShutdownDatabase()
Returns:
"shutdown" if shutdown is set, or null if not
 o 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.
 o getCloudscapeProperties
 public String getCloudscapeProperties()
Returns:
cloudscape specific connection URL attributes
 o 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/");
  
 o getRemoteDataSourceProtocol
 public String getRemoteDataSourceProtocol()
Returns:
remote access protocol
 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o populateInfo
 public void populateInfo(Properties info)
 o findDriver
 protected void findDriver(String url) throws SQLException
 o makeURL
 public String makeURL()

  Class Hierarchy        Index