# package sqlj.runtime.ref

## Class Index

- ConnectionContextImpl
- DefaultContext
- ProfileGroup
- ResultSetIterImpl
Class sqlj.runtime.ref.ConnectionContextImpl

# Class sqlj.runtime.ref.ConnectionContextImpl

    java.lang.Object
       |
       +----sqlj.runtime.ref.ConnectionContextImpl

public abstract class ConnectionContextImpl
extends Object

The connection context impl class is an abstract implementation of the connection context interface. It does not implement the connection context interface directly, but rather just defines the connection context method implementations. Subclasses must be defined which provide the static methods and constructors described in the connection context documentation.

Generated context classes will extend this class and implement the connection context interface.

See Also:
  ConnectionContext

## Constructor Index

o ConnectionContextImpl(ProfileGroup, Connection)
  Creates a new connection context impl class with the given profile group and connection.
o ConnectionContextImpl(ProfileGroup, ConnectionContext)
  Creates a new connection context impl class with the given profile group which uses the same connection as that of the passed context.
o ConnectionContextImpl(ProfileGroup, String, boolean)
  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url.
o ConnectionContextImpl(ProfileGroup, String, Properties, boolean)
  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url and properties.
o ConnectionContextImpl(ProfileGroup, String, String, String, boolean)
  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url, user and password.

## Method Index

o close()
  closes the context, its underlying connection and connected profiles.
o close(boolean)
  Releases all resources used in maintaining database state on this context.
o finalize()
  Calls the finalize method of the super and closes this context if it has not already been closed.
o getConnectedProfile(Object)
  Returns the connected profile associated with a profileKey for this connection context instance.
o getConnection()
  Returns the underlying connection for this connection context.
o getExecutionContext()
  Returns the default execution context used by this connection context.
o isClosed()
  Returns true if this context has been closed, false otherwise.

## Constructors

o ConnectionContextImpl

     protected ConnectionContextImpl(ProfileGroup profiles,
                                     Connection conn)

  Creates a new connection context impl class with the given profile group and connection. The auto commit mode of the connection is used unchanged. Each subclass must define its own profile group that will manage the set of profiles associated with that context class.

  Parameters:
    profiles - the profile group for the context subclass.
    conn - the underlying connection for this context instance.

o ConnectionContextImpl

     protected ConnectionContextImpl(ProfileGroup profiles,
                                     String url,
                                     String user,
                                     String password,
                                     boolean autoCommit) throws SQLException

  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url, user and password. Each subclass must define its own profile group that will manage the set of profiles associated with that context class.

  Parameters:
    profiles - the profile group for the context subclass.
    url - the database url
    user - the username
    password - the user password
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise.
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    getConnection, setAutoCommit

o ConnectionContextImpl

     protected ConnectionContextImpl(ProfileGroup profiles,
                                     String url,
                                     Properties info,
                                     boolean autoCommit) throws SQLException

  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url and properties. Each subclass must define its own profile group that will manage the set of profiles associated with that context class.

  Parameters:
    profiles - the profile group for the context subclass.
    url - the database url
    properties - the properties for creating a connection
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise.
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    setAutoCommit, getConnection

o ConnectionContextImpl

     protected ConnectionContextImpl(ProfileGroup profiles,
                                     String url,
                                     boolean autoCommit) throws SQLException

  Creates a new connection context impl class with the given profile group and creates a new connection using the passed url. Each subclass must define its own profile group that will manage the set of profiles associated with that context class.

  Parameters:
    profiles - the profile group for the context subclass.
    url - the database url
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise.
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    getConnection, setAutoCommit

o ConnectionContextImpl

     protected ConnectionContextImpl(ProfileGroup profiles,
                                     ConnectionContext other)

  Creates a new connection context impl class with the given profile group which uses the same connection as that of the passed context. The auto commit mode of the shared connection is unchanged. Each subclass must define its own profile group that will manage the set of profiles associated with that context class.

  Parameters:
    profiles - the profile group for the context subclass.
    other - a connection context instance with which to share a connection.
  See Also:
    getConnection

## Methods

o getConnectedProfile

     public ConnectedProfile getConnectedProfile(Object profileKey) throws SQLException

  Returns the connected profile associated with a profileKey for this connection context instance.

  Parameters:
    profileKey - the key asscoiated with the desired profile.
  Throws: IllegalArgumentException
    if the profileKey is null or invalid.
  Throws: SQLException
    if a connected profile instance could not be created
  See Also:
    getConnectedProfile

o close

     public void close() throws SQLException

  closes the context, its underlying connection and connected profiles.

  Throws: SQLException
    if an error occurs while closing
  See Also:
    close

o isClosed

     public boolean isClosed()

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

  See Also:
    isClosed

o getConnection

     public Connection getConnection()

  Returns the underlying connection for this connection context.

  See Also:
    getConnection

o close

     public void close(boolean closeConnection) throws SQLException

  Releases all resources used in maintaining database state on this context.

  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:
    close

o getExecutionContext

     public 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

o finalize

     protected void finalize() throws Throwable

  Calls the finalize method of the super and closes this context if it has not already been closed. The underlying connection is not closed.

  Throws: Throwable
    if an error occurs during finalization
  Overrides:
    finalize in class Object

Class sqlj.runtime.ref.DefaultContext

# Class sqlj.runtime.ref.DefaultContext

    java.lang.Object
       |
       +----sqlj.runtime.ref.ConnectionContextImpl
               |
               +----sqlj.runtime.ref.DefaultContext

public class DefaultContext
extends ConnectionContextImpl
implements ConnectionContext

The default context class provides a complete default implementation of a connection context. This is the same class definition that would have been generated by the reference translator for the clause: `#sql public context DefaultContext;` The reference implementation defaults to this class when no connection context instance variable exists in an executable sql clause and no other default class name was provided to the translator.

## Constructor Index

o DefaultContext(Connection)
  Creates a new default context instance which uses the passed connection as its underlying connection.
o DefaultContext(ConnectionContext)
  Creates a new default context instance which uses the same underlying connection as the passed connection context instance.
o DefaultContext(String, boolean)
  Creates a new default context instance whose underlying connection is created based on the passed url.
o DefaultContext(String, Properties, boolean)
  Creates a new default context instance whose underlying connection is created based on the passed url, and properties information.
o DefaultContext(String, String, String, boolean)
  Creates a new default context instance whose underlying connection is created based on the passed url, user and password.

## Method Index

o getDefaultContext()
  Returns the default context instance associated with this context class.
o getProfile(Object)
  Returns a top-level profile associated with profile key returned by an earlier call to `getProfileKey` in this context class.
o getProfileKey(Loader, String)
  Returns a key associated with the profile having the given name.
o setDefaultContext(DefaultContext)
  Sets the default connection context to be used for this class.

## Constructors

o DefaultContext

     public DefaultContext(Connection conn) throws SQLException

  Creates a new default context instance which uses the passed connection as its underlying connection. The auto commit mode of the connection is used unchanged.

  Note that the passed connection will not be closed if a call to this constructor results in an exception

  Parameters:
    conn - the underlying connection for this context instance.
  Throws: SQLException
    if an instance could not be constructed

o DefaultContext

     public DefaultContext(String url,
                           String user,
                           String password,
                           boolean autoCommit) throws SQLException

  Creates a new default context instance whose underlying connection is created based on the passed url, user and password.

  Note that if an exception occurs during construction, the underlying connection created during this call will be automatically closed.

  Parameters:
    url - the database url
    user - the username
    password - the user password
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    getConnection, setAutoCommit

o DefaultContext

     public DefaultContext(String url,
                           Properties info,
                           boolean autoCommit) throws SQLException

  Creates a new default context instance whose underlying connection is created based on the passed url, and properties information.

  Note that if an exception occurs during construction, the underlying connection created during this call will be automatically closed.

  Parameters:
    url - the database url
    info - a list of properties for the connection
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    getConnection, setAutoCommit

o DefaultContext

     public DefaultContext(String url,
                           boolean autoCommit) throws SQLException

  Creates a new default context instance whose underlying connection is created based on the passed url.

  Note that if an exception occurs during construction, the underlying connection created during this call will be automatically closed.

  Parameters:
    url - the database url
    autoCommit - true if the connection should be created in auto-commit mode, false otherwise
  Throws: SQLException
    the underlying connection could not be created.
  See Also:
    getConnection, setAutoCommit

o DefaultContext

     public DefaultContext(ConnectionContext other) throws SQLException

  Creates a new default context instance which uses the same underlying connection as the passed connection context instance. The auto commit mode of the shared connection is used unchanged.

  Note that the passed other ConnectionContext (and its underlying connection) will not be closed if a call to this constructor results in an exception.

  Parameters:
    other - the context with which to share an underlying connection.
  Throws: SQLException
    if an instance could not be constructed
  See Also:
    sqlj.runtime.ref.DefaultContext, getConnection

## Methods

o getProfileKey

     public static Object getProfileKey(Loader loader,
                                        String profileName) throws SQLException

  Returns a key associated with the profile having the given name. If the key for a profile with this name already exists, it is returned. Otherwise, a new profile is registered with the given name and loader and a new key for this profile is returned. An exception is raised a profile cannot be loaded with the given name and loader.

  Parameters:
    loader - the profile loader from which the profile should be loaded if it doesn't already exist.
    profileName - the fully qualified name of the profile.
  Returns:
    a key for the profile with the given name in this context.
  Throws: SQLException
    if a profile with this name cannot be loaded.
  See Also:
    getProfile, getConnectedProfile

o getProfile

     public static Profile getProfile(Object profileKey)

  Returns a top-level profile associated with profile key returned by an earlier call to `getProfileKey` in this context class. Each connection context class maintains a set of profiles that collectively define all possible sql operations that may be performed on this context.

  Parameters:
    profileKey - the key asscoiated with the desired profile.
  Throws: IllegalArgumentException
    if the profileKey is null or invalid.
  See Also:
    getProfileKey

o getDefaultContext

     public static DefaultContext getDefaultContext()

  Returns the default context instance associated with this context class. If a default context has been explicitely installed via a call to `setDefaultContext`, that context is returned. Otherwise, if a default JDBC connection exists in the current runtime context, a new default context object is created, installed and returned which uses the default JDBC connection as its underlying connection. If no default connection exists in the runtime, null is returned.

  See Also:
    setDefaultContext, getDefaultConnection

o setDefaultContext

     public static void setDefaultContext(DefaultContext ctx)

  Sets the default connection context to be used for this class. Any previous default context is replaced.

  Parameters:
    ctx - the new default context instance.

Class sqlj.runtime.ref.ProfileGroup

# Class sqlj.runtime.ref.ProfileGroup

    java.lang.Object
       |
       +----sqlj.runtime.ref.ProfileGroup

public class ProfileGroup
extends Object

A profile group object manages a set of profiles and connected profiles. Each profile group instance contains a collection of profiles. Additionally it contains a collection of open connections. For each open connection it contains, there exists an instance of a connected group. A connected group instance manages a set of connected profiles, one for each profile in the containing profile group instance.

This class is created to encapsulate the management of profiles that must be handled by all connection context objects. It is intended for internal use by the reference runtime implementation and reference translator generated code, and is therefore not expected to be directly referenced by SQLJ programmers.

## Constructor Index

o ProfileGroup()

## Method Index

o addConnection(Connection)
  Returns a connected group that manages the connected profiles associated with the passed connection and the current profile group's profiles.
o getProfile(Object)
  Returns the profile associated with a particular key in this profile group.
o getProfileKey(Loader, String)
  Returns key object for the profile of given a name.

## Constructors

o ProfileGroup

     public ProfileGroup()

## Methods

o getProfileKey

     public synchronized Object getProfileKey(Loader loader,
                                              String profileName) throws SQLException

  Returns key object for the profile of given a name. If a profile with the given name has not yet been instantiated by this profile group, then a new one is instantiated using the passed name and loader; a key associated with the newly instantiated profile is created and returned. If a profile with the given name is already known to the profile group, then its associated key is returned directly.

  Throws: SQLException
    if the profile cannot be instantiated
  See Also:
    instantiate

o getProfile

     public Profile getProfile(Object key)

  Returns the profile associated with a particular key in this profile group.

  Throws: IllegalArgumentException
    if the key is null or invalid

o addConnection

     public synchronized ProfileGroup. ConnectedGroup addConnection(Connection conn)

  Returns a connected group that manages the connected profiles associated with the passed connection and the current profile group's profiles. Profiles registered after this call is made are automatically made known to the connected group returned.

Class sqlj.runtime.ref.ResultSetIterImpl

# Class sqlj.runtime.ref.ResultSetIterImpl

    java.lang.Object
       |
       +----sqlj.runtime.ref.ResultSetIterImpl

public class ResultSetIterImpl
extends Object
implements ResultSetIterator

The result set iter(ator) impl(ementation) class implements the functionality of both a positioned iterator, and a named iterator. However, it does not directly implement either of these interfaces. Rather, the translator will generate iterator classes which subclass this class and implement only the iterator interface that they were declared to implement (thus avoiding iterators which appear to be both positional and named).

This class is used internally by the reference translator code generation. It is expected that clients will not directly reference this class.

See Also:
  PositionedIterator, NamedIterator, ForUpdate

## Variable Index

o resultSet
  The underlying reference runtime result set

## Constructor Index

o ResultSetIterImpl(RTResultSet)
  Creates a new result set iter impl object that uses data found in the passed result set.
o ResultSetIterImpl(RTResultSet, int)
  Creates a new result set iter impl object that uses data found in the passed result set.

## Method Index

o checkColumns(RTResultSet, int)
  Verifies that the passed result set has the passed expected number of columns.
o close()
  closes this iterator and the underlying result set.
o endFetch()
  Returns false if currently on a row, true otherwise.
o finalize()
  finalizes the super object and calls close if this iterator has not already been closed.
o findColumn(String)
  Returns the index associated with the passed column name on the underlying result set.
o getCursorName()
  Returns the cursor name of the underlying result set.
o getResultSet()
  Returns the JDBC result set associated with this iterator, if any.
o isClosed()
  Returns true if this iterator has been closed, false otherwise.
o next()
  Fetches the next row in the iterator and returns true if there was a row to fetch, false otherwise.

## Variables

o resultSet

     protected RTResultSet resultSet

  The underlying reference runtime result set

## Constructors

o ResultSetIterImpl

     public ResultSetIterImpl(RTResultSet rs)

  Creates a new result set iter impl object that uses data found in the passed result set.

o ResultSetIterImpl

     public ResultSetIterImpl(RTResultSet rs,
                              int numColumns) throws SQLException

  Creates a new result set iter impl object that uses data found in the passed result set. Verifies that the passed result set contains the same number of columns as is passed in the numColumns parameter.

  Note: If a SQLException is raised by the constructor, the passed result set is automatically closed.

  Parameters:
    rs - the underlying result set
    numColumns - the expected number of columns in the result set
  Throws: SQLException
    if the result set does not contain the expected number of columns
  See Also:
    checkColumns

## Methods

o checkColumns

     public static void checkColumns(RTResultSet rs,
                                     int expectedColumns) throws SQLException

  Verifies that the passed result set has the passed expected number of columns. An exception is raised if not. This method is provided for uniformity of error reporting between select..into and iterators.

  Parameters:
    rs - the result set to check.
    expectedColumns - the expected number of columns in the result set.
  Throws: SQLException
    if the result set does not have the expected number of columns.

o findColumn

     protected int findColumn(String name) throws SQLException

  Returns the index associated with the passed column name on the underlying result set. Throws an exception if the column name does not exist. Used by generated named iterators for uniform treatment of findColumn. Assumes that this method is called during construction

  Note: We assume that this method is only called during subclass construction, and thus if a SQLException is raised during this method, the underlying result set is automatically closed.

  Parameters:
    name - the name of the column in question
  Throws: SQLException
    if the column cannot be found. Underlying result set is closed in this case.

o getResultSet

     public ResultSet getResultSet() throws SQLException

  Returns the JDBC result set associated with this iterator, if any.

  Throws: SQLException
    if there is no JDBC result set associated with this iterator.

o close

     public void close() throws SQLException

  closes this iterator and the underlying result set.

  Throws: SQLException
    if an error occurs during close
  See Also:
    close

o isClosed

     public boolean isClosed() throws SQLException

  Returns true if this iterator has been closed, false otherwise.

  Throws: SQLException
    if a database access error occurs.
  See Also:
    isClosed

o getCursorName

     public String getCursorName() throws SQLException

  Returns the cursor name of the underlying result set.

  Throws: SQLException
    if the underlying result set does not have a cursor name.
  See Also:
    getCursorName

o endFetch

     public boolean endFetch() throws SQLException

  Returns false if currently on a row, true otherwise. Provides a termination condition for FETCH..INTO statements, as endFetch will be true after the last row has been FETCHed.

  Throws: SQLException
    if a database access error occurs.
  See Also:
    endFetch

o next

     public boolean next() throws SQLException

  Fetches the next row in the iterator and returns true if there was a row to fetch, false otherwise.

  Throws: SQLException
    if an error occurs in the underlying result set's call to next.
  See Also:
    next

o finalize

     protected void finalize() throws Throwable

  finalizes the super object and calls close if this iterator has not already been closed.

  Throws: Throwable
    if an error occurs during finalization
  Overrides:
    finalize in class Object
  See Also:
    close, isClosed