All Packages    This Package  Previous  Next  

Interface sqlj.runtime.profile.util.ProfileCustomizer

public interface interface ProfileCustomizer
A profile customizer is a JavaBean component that customizes a profile to allow vendor-specific features, extensions and/or behavior. A class is a profile customizer if it implements the ProfileCustomizer interface, provides an accessible no-arg constructor, and conforms to the JavaBeans API to expose its properties.

Most profile customizers extend the functionality of a profile by creating and registering an appropriate profile customization object with the profile. However, it is not required that all profile customizers install customization objects. Some customizers may only inspect the contents of a profile to verify conformance with a particular SQL dialect. Other customizers might install profile-specific data into a schema to be accessed at runtime without modifying the profile itself.

Profile Customizer Usage

Because profile customizers are JavaBeans components, they may be used within generic tools that operate on profiles. A profile customizer instance is typically created and used by a profile customization utility with the following steps.

The same profile customizer may be used to customize different profiles and/or customize the same profile using different properties and/or database connections. Any properties affecting the current customize call will be set before the call is made. The customize method will only be called with connections for which acceptsConnection has previously returned true.

Interpreting Customize Results

A profile is typically saved whenever it has been updated. Before saving the profile, it may be customized further using other customizers or settings. A profile should only be saved or customized further if it is in an appropriate state. The following table summarizes the possible outcomes of a call to customize and the corresponding state of the profile. Note that warnings and informational messages logged during a call to customize do not affect the state of the profile.

Customize Return Value Did Customize Log an Error? Should the Profile be Saved? Is it Safe to Customize Further? Comment

true

no

yes

yes

Customization successfully updated profile.

false

no

no

yes

Customization successful but did not require a profile change.

true

yes

no

no

Customization unsuccessfully updated profile. The profile contains erroneous data.

false

yes

no

yes

Customization unsuccessful but did not update profile.

Customizer Properties

A profile customizer uses the JavaBeans component model to describe the properties it contains. The beans Introspector class is used to discover all properties supported by a customizer. A property's read method (if available) is used to query the property's current value. A property's write method (if available) is used to set the property to a new value. No explicit processing of a property file or argument array is required on the part of the profile customizer. Because the Introspector class is used to discover properties, a profile customizer can publish its properties in many ways. Most profile customizers will use the JavaBeans default getXXX() and setXXX() method patterns to publish properties. A custom BeanInfo class could also be used if the default property mappings are insufficient. Note that profile customizers without properties do not require any special modification.

See Also:
Customization, instantiate, Introspector, BeanInfo

Method Index

 o acceptsConnection(Connection)
Returns true if this customizer is able to customize profiles using the passed JDBC connection, false otherwise.
 o customize(Profile, Connection, ErrorLog)
Customizes the passed profile.

Methods

 o acceptsConnection
 public abstract boolean acceptsConnection(Connection conn)
Returns true if this customizer is able to customize profiles using the passed JDBC connection, false otherwise. A null connection indicates that customization will be performed "offline" (without a connection).

Most customizers will customize profiles strictly offline (accepting only null connections) or strictly online (accepting only non-null connections). For those customizers that are able to operate both online and offline, this method returns true for both null and non-null connections. The definition of what constitutes an acceptable non-null connection is determined by the customizer implementation. Some will accept only connections to a particular database vendor. Others will accept only connections created by a particular JDBC driver.

This method allows customizers to be pooled and queried dynamically as to whether or not they can perform a particular customization, in much the same way that JDBC drivers are pooled with the driver manager and report whether or not they understand a particular URL.

Parameters:
conn - the JDBC connection to use during customization. A null connection indicates offline customization.
Returns:
true if customization can be performed using the passed connection, false otherwise.
 o customize
 public abstract boolean customize(Profile profile,
                                   Connection conn,
                                   ErrorLog log)
Customizes the passed profile. If the profile was modified in the process of customization, then true is returned. Otherwise false is returned. Note that the return value does not indicate success or failure but rather indicates whether or not the profile will need to be re-serialized to save its state. Accordingly, this method will only return true if the state of the profile object itself has been modified.

The passed profile is the instance to customize. This routine may register or deregister one or more customization objects with the profile. Note that the passed profile may have been previously customized by this customizer. Typical customization objects will only be installed once, and thus any previously registered customization objects may be removed or overwritten.

The passed connection is used to perform any database installation required for customization. Only connections for which acceptsConnection has previously returned true will be passed. Note that a null connection indicates that the profile is customized offline and does not require any database access.

The passed log is used to report information, warnings and errors that occur during the customization process. Logging an error indicates that this call was unsuccessful.

Parameters:
profile - the profile object to customize
conn - a JDBC connection to be used in the customization process.
log - a log into which error messages are written.
Returns:
true if profile was changed, false if unchanged.

All Packages    This Package  Previous  Next