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