    All Packages    This Package  Previous  Next

# Class sqlj.runtime.profile.Profile

    java.lang.Object
       |
       +----sqlj.runtime.profile.Profile

public abstract class Profile
extends Object
implements Serializable

A Profile object is a resource which contains the "constant" information describing a set of sql operations. It also provides a mechanism to add a jdbc connection to a profile, and in so doing, create a "ConnectedProfile" which can be used to create executable statement objects corresponding to the sql operations contained within the profile.

A profile may have a number of associated connected-profiles, each of which represents a customization for a particular data source connection. Profile customization will typically involve vendor-specific profile transformations that allow more efficient sql execution such a precompilation of sql text or use of stored procedures. A profile resolves a connected-profile from a data source connection via the use of a profile Customization object. A profile maintains a set of customization objects in much the same way that the JDBC DriverManager manages a set of JDBC drivers. A profile which has no customizations will default to a JDBC-based dynamic SQL connected profile implementation.

##

Profile(Loader)
  Creates a new profile associated with the given loader.

##

deregisterCustomization(Customization)
  Drop a customization from the profile's list.
getConnectedProfile(Connection)
  Resolves the contents of this profile with the passed JDBC connection and returns the result.
getContextName()
  Returns the fully qualified name of the connection context for this profile.
getCustomizations()
getJavaType(String)
  Returns a Java Class representation of the passed type name loaded using this profile's loader.
getJavaType(TypeInfo)
  Returns a Java Class representation of the passed type info object loaded using this profile's loader.
getLoader()
getProfileData()
getProfileName()
getTimestamp()
  Returns the creation time of the profile, as given by System.currentTimeMillis.
instantiate(Loader, InputStream)
  Instantiates a profile object from a serialized format stored in the passed input stream using the passed profile loader.
instantiate(Loader, String)
  Instantiates a profile object corresponding to a profile name using the passed profile loader.
registerCustomization(Customization)
  Registers a customization for this profile instance.
registerCustomization(Customization, Customization)
  Registers a customization for this profile instance.
replaceCustomization(Customization, Customization)
  Registers a customization for this profile instance.

##

Profile

     public Profile(Loader loader)

  Creates a new profile associated with the given loader. If the passed loader is null, then a DefaultLoader which uses the system class loader is used.

  A profile is an abstract object that only directly implements and manages those methods involving a loader. All other methods are implemented by subclasses.

  Note that this method is only used when creating new profile objects. To instantiate an existing profile object, use the `instantiate` method.

  Parameters:
    loader - the loader to associate with this instance of the profile
  See Also:
    instantiate, DefaultLoader

##

getProfileName

     public abstract String getProfileName()

  Returns:
    the fully qualified name of the profile.

getContextName

     public abstract String getContextName()

  Returns the fully qualified name of the connection context for this profile. Each profile is associated with a particular connection context class.

getTimestamp

     public abstract long getTimestamp()

  Returns the creation time of the profile, as given by System.currentTimeMillis. A profile for a particular application and context may evolve over time. The timestamp is intended to properly identify which profile should be used.

  Returns:
    the timestamp of the profile.

getProfileData

     public abstract ProfileData getProfileData()

  Returns:
    a data object describing each of the sql operations contained in this profile.

getConnectedProfile

     public abstract ConnectedProfile getConnectedProfile(Connection conn) throws SQLException

  Resolves the contents of this profile with the passed JDBC connection and returns the result. The implementation of this method will return the connected-profile associated with the first registered customization that accepts the passed connection. If no customization is found that accepts the connection, a default connected-profile implementation based on JDBC dynamic SQL will be returned.

  An exception is raised if a customization that accepts the connection is found, but is unable to create a connected profile. For example, a profile contains entries which cannot be executed on the particular connection.

  Parameters:
    conn - a JDBC Connection over which to perform operations.
  Returns:
    the result of attaching this profile to the given connection.
  Throws: SQLException
    if a connected-profile cannot be created for the supplied connection.
  See Also:
    Customization

registerCustomization

     public abstract void registerCustomization(Customization customization)

  Registers a customization for this profile instance. The customization is added after all currently registered customizations.

  Generally, a runtime environment will not call this method directly. Rather, this method may be called by customization utilities which operate on application profiles during an "installation" phase.

  Throws: NullPointerException
    if the customization argument is null

registerCustomization

     public abstract void registerCustomization(Customization newCustomization,
                                                Customization nextCustomization)

  Registers a customization for this profile instance. The new customization is added to the list just prior to the next customization argument. If the next customization is not currently registered, an exception is raised.

  Generally, a runtime environment will not call this method directly. Rather, this method may be called by customization utilities which operate on application profiles during an "installation" phase.

  Parameters:
    newCustomization - the customization to register
    nextCustomization - the customization before which to add the new customization
  Throws: NullPointerException
    if the new customization argument is null
  Throws: IllegalArgumentException
    if the next customization argument is not currently registered

replaceCustomization

     public abstract void replaceCustomization(Customization newCustomization,
                                               Customization oldCustomization)

  Registers a customization for this profile instance. The new customization is added to the list in place of the old customization argument. The new customization retains the position of the old customization. If the old customization is not currently registered, an exception is raised.

  Generally, a runtime environment will not call this method directly. Rather, this method may be called by customization utilities which operate on application profiles during an "installation" phase.

  Parameters:
    newCustomization - the customization to register
    oldCustomization - the customization to replace
  Throws: NullPointerException
    if the new customization argument is null
  Throws: IllegalArgumentException
    if the old customization argument is not currently registered

deregisterCustomization

     public abstract void deregisterCustomization(Customization customization)

  Drop a customization from the profile's list.

  Throws: IllegalArgumentException
    if the customization argument is not currently registered

getCustomizations

     public abstract Enumeration getCustomizations()

  Returns:
    an enumeration of all customizations currently registered with the profile.

getLoader

     public Loader getLoader()

  Returns:
    the profile-loader used to instantiate this profile

getJavaType

     public Class getJavaType(TypeInfo type)

  Returns a Java Class representation of the passed type info object loaded using this profile's loader. Each type appears in the original source file as a Java expression (variable) or cursor column whose type can be determined at compile time. The returned class may be used to determine an appropriate JDBC mapping into a SQL type.

  This profile's loader instance is used to load new class instances (for non-primitive types). The class is loaded based on the name of the java type given by the type info object. If the class cannot be loaded, a NoClassDefFoundError is raised. This would only be the case if the classes with which the profile was created are not available to the profile's loader.

  Parameters:
    type - the type info object describing the Java class to load
  Returns:
    a Java Class representation of the type
  See Also:
    getJavaTypeName, loadClass

getJavaType

     public Class getJavaType(String className)

  Returns a Java Class representation of the passed type name loaded using this profile's loader. This profile's loader instance is used to load new class instances (for non-primitive types). If the class cannot be loaded, a NoClassDefFoundError is raised.

  String names starting with "[" are interpreted as array names. Note that unlike Java VM array naming, array names passed to this method are expected to have the form "[" + . Accordingly, an array of array of int is named "[[int".

  Parameters:
    className - the name of the Java class to load
  Returns:
    a Java Class representation of the type
  See Also:
    getJavaTypeName, getResultSetName, loadClass

instantiate

     public static Profile instantiate(Loader loader,
                                       String profileName) throws IOException, ClassNotFoundException

  Instantiates a profile object corresponding to a profile name using the passed profile loader. If the passed loader is null, a DefaultLoader which uses the system class loader is used.

  In general, Profiles are not instantiated directly by the programmer. Rather, they are employed by the runtime implementation and generated code. It is the responsibility of the runtime and generated code to ensure that the profile-loader used to find a profile is able to unambiguoulsy resolve the profile name associated with a particular application. For example, if a particular application is loaded from a JAR file, the profiles associated with that application will be loaded from the same JAR file.

  The profile is created based on a name relative to a profile loader. This name should be a dot-separated name such as "a.b.c".

  The given name can indicate either a serialized object or a class. The profileName is first treated as a serialized object name and then as a class name.

  When using the profileName as a serialized object name we convert the given profileName to a resource pathname and add a trailing ".ser" suffix. We then try to load a serialized object from that resource.

  When using the profileName as a class name, the type of the class loaded is considered. If the class represents a sqlj.runtime.profile.Profile class or subclass, the class is instantiated and the result returned. If the class loaded implements the sqlj.runtime.profile.SerializedProfile interface, then the class is instantiated as a SerializedProfile and the getProfileAsStream method is called to read and instantiate a profile from the resulting stream. If the class loaded does not adhere to one of these cases, an error is raised.

  For example, given a profileName of "x.y", this method would first try to read a serialized object from the resource "x/y.ser" and if that failed it would try to load the class "x.y" and create an instance of that class. Note that if both a serialized object and a class share the same profile name, only the serialized object will be instantiated and returned.

  A new profile instance is created each time the instantiate method is called. Thus, passing the same profile loader and profile name as a previously instantiated profile instance will not return the same object as the previous call but rather will instantiate a new object.

  Parameters:
    loader - the profile-loader from which we should create the profile.
    profileName - the name of the profile within the profile-loader. For example "sqlj.app.profile1"
  Throws: ClassNotFoundException
    if the class or a serialized object could not be found.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    SerializedProfile, DefaultLoader

instantiate

     public static Profile instantiate(Loader loader,
                                       InputStream serProfile) throws ClassNotFoundException, IOException

  Instantiates a profile object from a serialized format stored in the passed input stream using the passed profile loader. If the passed loader is null, a DefaultLoader which uses the system class loader is used.

  This routine is generally used at installation time to create a profile instance from serialized form in a resource file. The profile will often be customized, and then reserialied to the same resource file. The installation process relies on knowing the resource file with which a particular profile is associated.

  Note: The passed input stream is closed by this method, even when an exception is raised.

  Parameters:
    loader - the profile-loader from which we should create the profile.
    serProfile - an input stream containing a profile in serialized format.
  Throws: ClassNotFoundException
    if a serialized profile could not be found.
  Throws: IOException
    if an I/O error occurs.
  See Also:
    DefaultLoader

    All Packages    This Package  Previous  Next