SQLJ-Specific DataSources

SQLJ-specific datasources are available in runtime12ee.jar or runtime12ee.zip. Currently, SQLJ-specific data sources can only be used in client-side SQLJ programs.

SQLJ-specific data sources extend Oracle JDBC data sources by providing new APIs that return SQLJ connection contexts. This enables a SQLJ developer to manage connection contexts the same way a JDBC developer manages connections. In general, each SQLJ-specific data source interface or class is based on a JDBC data source interface or an Oracle JDBC data source class.
 

SQLJ-Specific DataSource Interfaces
Compared to JDBC counterparts, the SQLJ-specific data sources implement additional APIs that support connection context instantiation. Those APIs are defined in the sqlj.runtime.ConnectionContextFactory interface:
package sqlj.runtime;
public interface ConnectionContextFactory
{
sqlj.runtime.ref.DefaultContext getDefaultContext();
sqlj.runtime.ref.DefaultContext getDefaultContext(boolean autoCommit);
sqlj.runtime.ref.DefaultContext getDefaultContext(String user,String password);
sqlj.runtime.ref.DefaultContext getDefaultContext(String user,String password, boolean autoCommit);

// For instances of specific data context classes:
sqlj.runtime.ConnectionContext getContext(Class aContextClass);
sqlj.runtime.ConnectionContext getContext(Class aContextClass, boolean autoCommit);
sqlj.runtime.ConnectionContext getContext(Class aContextClass, String user, String password);
sqlj.runtime.ConnectionContext getContext(Class aContextClass, String user, String password, boolean autoCommit);
}

A getDefaultContext method call creates and returns a DefaultContext instance.  A getContext method call creates and returns a connection context of the type specified by aContextClass. The arguments for getDefaultContext and getContext specify the autoCommit, user, and password settings for the JDBC connection associated with the returned DefaultContext instance.

By default, the autoCommit property for the JDBC connection associated with a returned connection context will be disabled, unless the i autoCommit property is set to be true for the data source that generates the JDBC connection.

JDBC provides several data source interfaces: javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, and javax.sql.XADataSource. To make it convinent to utilize both JDBC data source APIs and the ConnectionContextFactory APIs, we provide one SQLJ data source interface corresponding to each JDBC data source interface.  Below is the declaration of three SQLJ-specific data source interface SqljDataSource, SqljConnectionPoolDataSource, and SqljXADataSource:

package sqlj.runtime;
public interface SqljDataSource extends javax.sql.DataSource, ConnectionContextFactory { };
public interface SqljDataSource extends javax.sql.ConnectionPoolDataSource, ConnectionContextFactory { };
public interface SqljXADataSource extends javax.sql.XADataSource, ConnectionContextFactory { };
SQLJ-Specific DataSource Classes
We provide the SQLJ counterparts for the six Oracle JDBC data source implementations. The list below shows that each SQLJ-specific data source corresponds to and extends an Oracle JDBC data source.  All SQLJ-specific data sources are in the packages oracle.sqlj.runtime amd oracle.sqlj.runtime.client.
package oracle.sqlj.runtime;

public class OracleSqljDataSource
    extends oracle.jdbc.pool.OracleDataSource
    implements ConnectionContextFactory;

public class OracleSqljConnectionPoolDataSource
    extends oracle.jdbc.pool.OracleConnectionPoolDataSource
    implements ConnectionContextFactory;

public abstract class OracleSqljXADataSource
    extends oracle.jdbc.xa.OracleXADataSource
    implements ConnectionContextFactory;

public class OracleSqljXADataSource
    extends oracle.jdbc.xa.client.OracleXADataSource
    implements ConnectionContextFactory;

public class OracleSqljConnectionCacheImpl
    extends oracle.jdbc.pool.OracleConnectonCacheImpl
    implements ConnectionContextFactory;

public class OracleSqljXAConnectionCacheImpl
    extends oracle.jdbc.pool.OracleXAConnectonCacheImpl
    implements ConnectionContextFactory;

public class OracleSqljOCIConnectionPool
    extends oracle.jdbc.pool.OracleOCIConnectonPool
    implements ConnectionContextFactory;

Since each SQLJ-specific data source extends a Oracle JDBC data source, SQLJ-specific data sources can be used to substitute the corresponding Oralce JDBC data sources. The getDefaultContext and getContext methods in those SQLJ-specific data sources is implemented similarly: First, a new logical JDBC connection is acquired from the present data source; Then, a connection context instance is created and returned.
Closing Connections or Connection Contexts
Closing a connection context using close() or close(ConnectionContext.CLOSE_CONNECTION) will free that connection context and the associated logical JDBC connection. Closing a connection context using close(ConnectionContext.KEEP_CONNECTION) will shutdown the connection context but not the associated logical JDBC connection.

Closing a logical JDBC connection will shut down the associated connetion context.

Application


When used in middle-tier environments, SQLJ-specific data sources, like JDBC data sources, are bound to JNDI locations. The binding can be done explicitly, e.g.:

//Initialize datasource
SqljXADataSource sqljDS = new OracleSqljXADataSource();
sqljDS.setUser("scott");
sqljDS.setPassword("tigher");
sqljDS.setServerName("dlsun960");
sqljDS.setDatabaseName("ORCL");
sqljDS.setDataSourceName("jdbc/OracleSqljXADS");

//Bind the datasource to JNDI
Context ctx = new InitialContext();
ctx.bind("jdbc/OracleSqljXADS");

Alternatively, in OC4J, data sources can be instantiated and bound to JNDI through specification in ${J2EE_HOME}/config/data-sources.xml. For instance, the following entry in data-sources.xml creates an OracleSqljXADataSource instance and binds it to the JNDI location jdbc/OracleSqljXADS.
<data-source
class="oracle.sqlj.runtime.OracleSqljXADataSource"
name="jdbc/OracleSqljXADS"
location="jdbc/OracleSqljXADS"
xa-location="jdbc/OracleSqljXADS/xa"
username="scott"
password="tiger"
url="jdbc:oracle:thin:@dlsun960:1521:ORCL"
/>
A SQLJ-specific data source bound to a JNDI location can be looked up and be used in creating connection contexts. Below are two code segments that create two connection contexts respectively, a DefaultContext instance and a connection context of a user-defined type MyCtx.
== getDefaultContext ==
sqlj.runtime.SqljDataSource sqljDS;
InitialContext initCtx = new InitialContext();
sqljDS = (sqlj.runtime.SqljDataSource) initCtx.lookup("jdbc/OracleSqljXADS");
DefaultContext ctx = sqljDS.getDefaultContext();

== getContext ==
sqlj.runtime.SqljDataSource sqljDS;
#sql public static context MyCtx with (..any properties other than dataSource..);
InitialContext initCtx = new InitialContext();
sqljDS = (sqlj.runtime.SqljDataSource) initCtx.lookup("jdbc/OracleSqljXADS");
MyCtx ctx = (MyCtx) sqljDS.getContext(MyCtx.class);