Class Hierarchy    Previous  Next  Index

Class COM.cloudscape.core.AbstractDataSource

java.lang.Object
    |
    +----COM.cloudscape.core.AbstractDataSource

public abstract class AbstractDataSource
extends java.lang.Object
implements javax.naming.Referenceable, java.io.Serializable
Copyright © 1998-2000, Informix Software, 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 equals(Object)
 
 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 setDatabaseProperties(Properties)
 
 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.

Field Detail

 o driver
protected static transient java.sql.Driver driver

Method Detail

 o getReference
public javax.naming.Reference getReference() throws javax.naming.NamingException
          Referenceable method.
Throws:
javax.naming.NamingException - cannot find named object
 o equals
public boolean equals(java.lang.Object p0)
Overrides:
equals in class java.lang.Object
 o setDatabaseName
public void setDatabaseName(java.lang.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 will be booted if it is not already running in the system.
Parameters:
dbname - the name of the database
 o getDatabaseName
public java.lang.String getDatabaseName()
Returns:
database name
 o setDataSourceName
public void setDataSourceName(java.lang.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 java.lang.String getDataSourceName()
Returns:
data source name
 o setDescription
public void setDescription(java.lang.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 java.lang.String getDescription()
Returns:
description
 o setCreateDatabase
public void setCreateDatabase(java.lang.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 java.lang.String getCreateDatabase()
Returns:
"create" if create is set, or null if not
 o setShutdownDatabase
public void setShutdownDatabase(java.lang.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 java.lang.String getShutdownDatabase()
Returns:
"shutdown" if shutdown is set, or null if not
 o setCloudscapeProperties
public void setCloudscapeProperties(java.lang.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 java.lang.String getCloudscapeProperties()
Returns:
cloudscape specific connection URL attributes
 o setRemoteDataSourceProtocol
public void setRemoteDataSourceProtocol(java.lang.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 java.lang.String getRemoteDataSourceProtocol()
Returns:
remote access protocol
 o getLoginTimeout
public int getLoginTimeout() throws java.sql.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:
java.sql.SQLException - if a database access error occurs.
 o setLoginTimeout
public void setLoginTimeout(int seconds) throws java.sql.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:
java.sql.SQLException - if a database access error occurs.
 o getLogWriter
public java.io.PrintWriter getLogWriter() throws java.sql.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:
java.sql.SQLException - if a database-access error occurs.
 o setLogWriter
public void setLogWriter(java.io.PrintWriter out) throws java.sql.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:
java.sql.SQLException - if a database-access error occurs.
 o getDatabaseConnection
public java.sql.Connection getDatabaseConnection() throws java.sql.SQLException
          

Attempt to establish a database connection.

Returns:
a Connection to the database
Throws:
java.sql.SQLException - if a database-access error occurs.
 o getDatabaseConnection
public java.sql.Connection getDatabaseConnection(java.lang.String username,
                                        java.lang.String password) throws java.sql.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:
java.sql.SQLException - if a database-access error occurs.
 o populateInfo
public void populateInfo(java.util.Properties info)
 o setDatabaseProperties
public void setDatabaseProperties(java.util.Properties info)
 o findDriver
protected void findDriver(java.lang.String url) throws java.sql.SQLException
 o makeURL
public java.lang.String makeURL()

  Class Hierarchy    Previous  Next  Index