sqlj.runtime
Interface ConnectionContext

public interface ConnectionContext

A connection context manages a set of SQL operations performed during a session with a specific database. A connection context maintains an JDBC Connection instance on which dynamic SQL operations may be performed. It also contains a default execution context object by which sql operation execution semantics may be queried and modified.

In addition to those methods defined by this interface, each concrete implementation of a connection context, UserCtx, will provide the following methods:

• public static Object getProfileKey(sqlj.runtime.profile.Loader l, String profileName) throws SQLException;

  Returns a profile key for a particular profile loader and name. Note: this method is for internal use by the SQLJ runtime only.

• public static sqlj.runtime.profile.Profile getProfile(Object key);

  Returns a top-level profile for a particular profile key. Note: this method is for internal use by the SQLJ runtime only.

• public static UserCtx getDefaultContext();

  Returns the default context for the UserCtx class. Note: Open SQL / SQLJ does not support a default context.

• public static void setDefaultContext(UserCtx dflt);

  Sets the default context for the UserCtx class. Note: Open SQL / SQLJ does not support a default context.

• public UserCtx(java.sql.Connection conn) throws SQLException;

• public UserCtx(ConnectionContext other) throws SQLException;

• If a generated connection context class is associated with a data source (i.e. the declaration contains the with keyword dataSource), then, it will have the following constructors:

  • public UserCtx() throws SQLException;

  • public UserCtx(String user, String password) throws SQLException;
    

• Otherwise; the generates connection context class UserCtx will have the following constructors:

  • public UserCtx(String url, String user, String pwd, boolean autoCommit) throws SQLException;

  • public UserCtx(String url, Properties info, boolean autoCommit) throws SQLException;

  • public UserCtx(String url, boolean autoCommit) throws SQLException;

Note that for any context constructor which creates a JDBC connection during construction, that connection will be automatically closed if the constructor call throws an exception. For any context constructor which uses an already opened JDBC connection (or context) passed from the client, that connection (or context) will remain open even if the constructor call throws an exception.

Field Summary

static boolean	CLOSE_CONNECTION Underlying JDBC Connection should be closed
static boolean	KEEP_CONNECTION Underlying JDBC Connection should not be closed

Method Summary

void	close() Releases all resources used in maintaining database state on this context, closes any open connected profiles, and closes the underlying jdbc connection.
void	close(boolean closeConnection) Releases all resources used in maintaining database state on this context and closes any open connected profiles manages by this context.
sqlj.runtime.profile.ConnectedProfile	getConnectedProfile(java.lang.Object profileKey) Returns the connected profile associated with a profileKey for this connection context instance.
java.sql.Connection	getConnection() Returns the underlying jdbc connection object associated with this context instance.
ExecutionContext	getExecutionContext() Returns the default ExecutionContext object used by this connection context.
java.util.Map	getTypeMap() Type maps are not supported by Open SQL / SQLJ.
boolean	isClosed() returns true if this context has been closed; false otherwise.

Field Detail

CLOSE_CONNECTION

public static final boolean CLOSE_CONNECTION

Underlying JDBC Connection should be closed

See Also:

close(boolean)

KEEP_CONNECTION

public static final boolean KEEP_CONNECTION

Underlying JDBC Connection should not be closed

See Also:

close(boolean)

Method Detail

getConnectedProfile

public sqlj.runtime.profile.ConnectedProfile getConnectedProfile(java.lang.Object profileKey)
                                                          throws java.sql.SQLException

Returns the connected profile associated with a profileKey for this connection context instance. Each connection context maintains a set of connected profiles on which sql operation statements are prepared. Collectively, the set of connected profiles contained in a connection context represent the set of all possible sql operations that may be performed in the lifetime of this context instance.

The profileKey object must be an object that was returned via a prior call to getProfileKey(). An exception is raised if a connected profile instance could not be created for this connection context.

Parameters:

profileKey - the key asscoiated with the desired profile.

Throws:

java.lang.IllegalArgumentException - if the profileKey is null or invalid.

java.sql.SQLException - if the connected profile instance could not be created.

getConnection

public java.sql.Connection getConnection()

Returns the underlying jdbc connection object associated with this context instance. Note that depending on construction, the returned connection may be shared between many connection context instances.

close

public void close()
           throws java.sql.SQLException

Releases all resources used in maintaining database state on this context, closes any open connected profiles, and closes the underlying jdbc connection. This method is equivalent to close(CLOSE_CONNECTION)

Throws:

java.sql.SQLException - if unable to close the context

See Also:

close(boolean)

close

public void close(boolean closeConnection)
           throws java.sql.SQLException

Releases all resources used in maintaining database state on this context and closes any open connected profiles manages by this context. Since the underlying JDBC connection managed by this context may be shared between mutliple context objects, it is not always desireable to close the underlying JDBC Connection close is called. If the constant KEEP_CONNECTION is passed, the underlying jdbc connection is not closed. Otherwise, if the constant CLOSE_CONNECTION, the underlying connection is closed.

Note: A context is not automatically closed when it is garbage collected. Therefore, it should be closed in a finally block. Also, the underlying JDBC connection will not be automatically closed when it is garbage collected.

Parameters:

closeConnection - is true if the underlying Connection should also be closed.

Throws:

java.sql.SQLException - if unable to close the context

See Also:

KEEP_CONNECTION, CLOSE_CONNECTION

isClosed

public boolean isClosed()

returns true if this context has been closed; false otherwise.

See Also:

close(), close(boolean)

getExecutionContext

public ExecutionContext getExecutionContext()

Returns the default ExecutionContext object used by this connection context. The default execution context is the execution context used if no explicit context is supplied during the execution of a particular sql operation.

Returns:

the default excution context

getTypeMap

public java.util.Map getTypeMap()
                         throws java.sql.SQLException

Type maps are not supported by Open SQL / SQLJ.