com.ibm.connector2.ims.db
Class IMSJdbcDataSource

java.lang.Object
  |
  +--com.ibm.connector2.ims.db.IMSJdbcDataSource
All Implemented Interfaces:
javax.sql.DataSource, javax.naming.Referenceable, java.io.Serializable

public class IMSJdbcDataSource
extends java.lang.Object
implements javax.sql.DataSource, java.io.Serializable, javax.naming.Referenceable

A IMSJdbcDataSource provides a mechanism to create a Connection from an object stored in the JNDI namespace. The DataSource object is either deployed into the name space by a deployment tool, such as that for WebSphere Application Server, or it can be deployed by an application different from the application using the DataSource. IMSJdbcDataSource can also be created directly in an application, rather than loading it from the name space. The following code snippet demonstrates how to create an IMS DataSource from an IMSJdbcManagedConnectionFactory and use it to create a Connection:

 IMSJdbcManagedConnectionFactory mcf = new IMSJdbcManagedConnectionFactory();
 mcf.setDatabaseViewName("MyDatabaseView");
 mcf.setDRAName("IMS1");
 DataSource dataSource = (DataSource)mcf.createConnectionFactory();
 Connection connection = dataSource.getConnection();
 
IMSJdbcDataSource implements both the Serializable and Referenceable interfaces, although the Referenceable interface is currently only supported in a managed-server environment.

See Also:
IMSJdbcManagedConnectionFactory, Connection, ManagedConnectionFactory, ConnectionManager, Reference, Referenceable, Serialized Form

Constructor Summary
IMSJdbcDataSource(javax.resource.spi.ConnectionManager connectionManager, IMSJdbcManagedConnectionFactory managedConnectionFactory)
          Creates an IMSJdbcDataSource from a ConnectionManager and an IMSJdbcManagedConnectionFactory.
IMSJdbcDataSource(IMSJdbcManagedConnectionFactory managedConnectionFactory)
          Creates an IMSJdbcDataSource in an unmanaged-server environment (e.g.
 
Method Summary
 java.sql.Connection getConnection()
          Gets a connection from the application server on behalf of the client.
 java.sql.Connection getConnection(java.lang.String userid, java.lang.String password)
          This function is not supported
 java.lang.String getDatabaseViewName()
          Returns the name of the DLIDatabaseView used by this DataSource object.
 java.lang.String getDRAName()
          Returns the DRA name of the IMS system this datasource is using.
 int getLoginTimeout()
          This function is not supported
 java.io.PrintWriter getLogWriter()
          Gets the PrintWriter contained in the associated IMSJdbcManagedConnectionFactory if one exists.
 javax.naming.Reference getReference()
          Returns stored reference.
 void setDatabaseViewName(java.lang.String databaseViewName)
          Sets the fully-qualified name of the DLIDatabaseView to be used by this DataSource object.
 void setDRAName(java.lang.String draName)
          Sets the DRA name of the IMS system for this datasource
 void setLoginTimeout(int timeout)
          This function is not supported
 void setLogWriter(java.io.PrintWriter printWriter)
          Sets the XMLTrace OutputWriter object to the passed PrintWriter.
 void setReference(javax.naming.Reference reference)
          Stores a reference.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IMSJdbcDataSource

public IMSJdbcDataSource(javax.resource.spi.ConnectionManager connectionManager,
                         IMSJdbcManagedConnectionFactory managedConnectionFactory)
Creates an IMSJdbcDataSource from a ConnectionManager and an IMSJdbcManagedConnectionFactory. This constructor is normally used in a managed-server environment (e.g. WebSphere Application Server).
Parameters:
connectionManager - a ConnectionManager supplied by the server runtime.
managedConnectionFactory - an IMSJdbcManagedConnectionFactory containing the properties necessary to create a Connection object.
See Also:
IMSJdbcManagedConnectionFactory, ConnectionManager, ManagedConnectionFactory

IMSJdbcDataSource

public IMSJdbcDataSource(IMSJdbcManagedConnectionFactory managedConnectionFactory)
Creates an IMSJdbcDataSource in an unmanaged-server environment (e.g. IMS). This constructor will create and use the default connection manager IMSJdbcConnectionManager.
Parameters:
managedConnectionFactory - an IMSJdbcManagedConnectionFactory containing the properties necessary to create a Connection object.
See Also:
IMSJdbcManagedConnectionFactory, ManagedConnectionFactory
Method Detail

getConnection

public final java.sql.Connection getConnection()
                                        throws java.sql.SQLException
Gets a connection from the application server on behalf of the client.
Specified by:
getConnection in interface javax.sql.DataSource
Returns:
a Connection object.
Throws:
java.sql.Exception - an SQLException that was thrown from the resource adapter's attempt to get a connection.
See Also:
Connection

getConnection

public final java.sql.Connection getConnection(java.lang.String userid,
                                               java.lang.String password)
                                        throws java.sql.SQLException
This function is not supported
Specified by:
getConnection in interface javax.sql.DataSource
Parameters:
userid - not used.
password - not used.
Returns:
not supported.
Throws:
java.sql.SQLException - a java.sql.SQLException indicating the method is not supported.
See Also:
Connection

getDatabaseViewName

public java.lang.String getDatabaseViewName()
Returns the name of the DLIDatabaseView used by this DataSource object.

setDatabaseViewName

public void setDatabaseViewName(java.lang.String databaseViewName)
Sets the fully-qualified name of the DLIDatabaseView to be used by this DataSource object.
Parameters:
databaseViewName - the fully-qualified DLIDatabaseView subclass

getDRAName

public java.lang.String getDRAName()
Returns the DRA name of the IMS system this datasource is using.

setDRAName

public void setDRAName(java.lang.String draName)
Sets the DRA name of the IMS system for this datasource
Parameters:
draName - the 4 character DRA ID

setReference

public void setReference(javax.naming.Reference reference)
Stores a reference.
Parameters:
reference - the JNDI Reference to be stored.
See Also:
Reference

getReference

public javax.naming.Reference getReference()
Returns stored reference.
Specified by:
getReference in interface javax.naming.Referenceable
Returns:
the JNDI Reference.
See Also:
Reference

getLogWriter

public final java.io.PrintWriter getLogWriter()
                                       throws java.sql.SQLException
Gets the PrintWriter contained in the associated IMSJdbcManagedConnectionFactory if one exists.
Specified by:
getLogWriter in interface javax.sql.DataSource
Returns:
a java.io.PrintWriter to the client.
Throws:
java.sql.SQLException - an SQLException that was thrown from the resource adapter's attempt to retrieve the PrintWriter.
See Also:
ManagedConnectionFactory.getLogWriter(), PrintWriter

getLoginTimeout

public final int getLoginTimeout()
                          throws java.sql.SQLException
This function is not supported
Specified by:
getLoginTimeout in interface javax.sql.DataSource
Throws:
java.sql.SQLException - Throws an SQLException indicating the method is not supported.

setLogWriter

public final void setLogWriter(java.io.PrintWriter printWriter)
                        throws java.sql.SQLException
Sets the XMLTrace OutputWriter object to the passed PrintWriter.

The design of tracing in the J2EE Connection Architecture (JCA) and that in the IMS Java class libraries does not mesh cleanly. In JCA, all tracing is tied to a PrintWriter from a particular ManagedConnectionFactory object. Different ManagedConnectionFactory objects can use different PrintWriter objects. This is reflected in the final trace log by headers that identify the ManagedConnectionFactory.

All tracing in the IMS Java class libraries occurs on a single Writer object. There is no ability to distinguish trace entries by the ManagedConnectionFactory object that resulted in those entries.

To accomodate these design differences, the IMS Java objects that implement JCA (the com.ibm.connector2.ims.db package), write a minimal amount of trace information to the PrintWriter associated with a ManagedConnectionFactory as well as writing the normal tracing to the XMLTrace object. By default, these trace entries are independent.

This method allows you to merge the tracing that occurs to XMLTrace with that of the ManagedConnectionFactory PrintWriter object. You do this by calling this method with the PrintWriter returned from a call to DataSource.getPrintWriter as follows:

 DataSource dataSource = (DataSource)mcf.createConnectionFactory();
 dataSource.setLogWriter(dataSource.getLogWriter());
 
The only PrintWriter that can be passed to DataSource.setLogWriter is the one returned from DataSource.getLogWriter. Any other PrintWriter is ignored.

Using this method does have side affects. In particular, all IMS Java tracing will appear in the log prepended with the ManagedConnectionFactory used by this DataSource whether it was a result of it or not. You can use the method XMLTrace.setTIDTracing(true) to help distinguish tracing that occurs on one EJB from that of another.

Specified by:
setLogWriter in interface javax.sql.DataSource
Parameters:
printWriter - The PrintWriter returned from DataSource.getLogWriter().
Throws:
java.sql.SQLException - on an error
See Also:
IMSTrace.setOutputWriter(Writer), XMLTrace.setTIDTracing(boolean), ManagedConnectionFactory, PrintWriter

setLoginTimeout

public final void setLoginTimeout(int timeout)
                           throws java.sql.SQLException
This function is not supported
Specified by:
setLoginTimeout in interface javax.sql.DataSource
Parameters:
timeout - not used.
Throws:
java.sql.SQLException - an SQLException indicating the method is not supported.


(C) International Business Machines Corporation 2004. All rights reserved.