    All Packages    This Package  Previous  Next

# Interface sqlj.runtime.ConnectionContext

public interface 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.

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

  Returns a top-level profile for a particular profile key

-     public static UserCtx getDefaultContext();

  Returns the default context for the UserCtx class.

-     public static void setDefaultContext(UserCtx dflt);

  Sets the default context for the UserCtx class.

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

-     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;

-     public UserCtx(ConnectionContext other) 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.

##

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

##

close()
  Releases all resources used in maintaining database state on this context, closes any open connected profiles, and closes the underlying jdbc connection.
close(boolean)
  Releases all resources used in maintaining database state on this context and closes any open connected profiles manages by this context.
getConnectedProfile(Object)
  Returns the connected profile associated with a profileKey for this connection context instance.
getConnection()
  Returns the underlying jdbc connection object associated with this context instance.
getExecutionContext()
  Returns the default execution context used by this connection context.
isClosed()
  returns true if this context has been closed, false otherwise.

##

CLOSE_CONNECTION

     public static final boolean CLOSE_CONNECTION

  Underlying JDBC Connection should be closed

  See Also:
    close

KEEP_CONNECTION

     public static final boolean KEEP_CONNECTION

  Underlying JDBC Connection should not be closed

  See Also:
    close

##

getConnectedProfile

     public abstract ConnectedProfile getConnectedProfile(Object profileKey) throws 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: IllegalArgumentException
    if the profileKey is null or invalid.
  Throws: SQLException
    if the connected profile instance could not be created.

getConnection

     public abstract 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 abstract void close() throws 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: SQLException
    if unable to close the context
  See Also:
    close

close

     public abstract void close(boolean closeConnection) throws 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 automatically closed when it is garbage collected. A context closed in such a way does not close the underlying JDBC connection since it will also be automatically closed when it is garbage collected.

  Parameters:
    closeConnection - is true if the underlying Connection should also be closed.
  Throws: SQLException
    if unable to close the context
  See Also:
    KEEP_CONNECTION, CLOSE_CONNECTION

isClosed

     public abstract boolean isClosed()

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

  See Also:
    close, close

getExecutionContext

     public abstract ExecutionContext getExecutionContext()

  Returns the default execution context 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

    All Packages    This Package  Previous  Next