The SQLJ language provides direct support for static SQL operations that are known at the time the program is written. If some or all of a particular SQL statement cannot be determined until run time, it is a dynamic operation. To perform dynamic SQL operations from an SQLJ program, use JDBC. A ConnectionContext object contains a JDBC Connection object which can be used to create JDBC Statement objects needed for dynamic SQL operations.
Every SQLJ ConnectionContext class includes a constructor that takes as an argument a JDBC Connection. This constructor is used to create an SQLJ connection context instance that shares its underlying database connection with that of the JDBC connection.
Every SQLJ ConnectionContext instance has a getConnection() method that returns a JDBC Connection instance. The JDBC Connection returned shares the underlying database connection with the SQLJ connection context. It may be used to perform dynamic SQL operations as described in the JDBC API.
The interoperability methods described above provide a conversion between the connection abstractions used in SQLJ and those used in JDBC. Both abstractions share the same database session, that is, the underlying database connection. Accordingly, calls to methods that affect session state on one object will also be reflected in the other object, as it is actually the underlying shared session that is being affected.
JDBC defines the default values for session state of newly created connections. In most cases, SQLJ adopts these default values. However, whereas a newly created JDBC connection has auto commit mode on by default, an SQLJ connection context requires the auto commit mode to be specified explicitly upon construction.
Calling the close() method of a connection context instance causes the associated JDBC connection instance and the underlying database connection to be closed. Since connection contexts may share the underlying database connection with other connection contexts and/or JDBC connections, it may not be desirable to close the underlying database connection when a connection context is closed. A programmer may wish to release the resources maintained by the connection context (for example, statement handles) without actually closing the underlying database connection. To this end, connection context classes also support a close() method which takes a Boolean argument indicating whether or not to close the underlying database connection: the constant CLOSE_CONNECTION if the database connection should be closed, and KEEP_CONNECTION if it should be retained. The variant of close() that takes no arguments is a shorthand for calling close(CLOSE_CONNECTION).
If a connection context instance is not explicitly closed before it is garbage collected, then close(KEEP_CONNECTION) is called by the finalize method of the connection context. This allows connection related resources to be reclaimed by the normal garbage collection process while maintaining the underlying database connection for other JDBC and SQLJ objects that may be using it. Note that if no other JDBC or SQLJ objects are using the connection, then the database connection is closed and reclaimed by the garbage collection process.
Both SQLJ connection context objects and JDBC connection objects respond to the close() method. When writing an SQLJ program, it is sufficient to call the close() method on only the connection context object. This is because closing the connection context also closes the JDBC connection associated with it. However, it is not sufficient to close only the JDBC connection returned by the getConnection() method of a connection context. This is because the close() method of a JDBC connection does not cause the containing connection context to be closed, and therefore resources maintained by the connection context are not released until it is garbage collected.
The isClosed() method of a connection context returns true if any variant of the close() method has been called on the connection context instance. If isClosed() returns true, then calling close() has no effect, and calling any other method is undefined.