    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.

- A profile customizer bean is created by name using a call to `Beans.instantiate()`.
- The customizer's properties are discovered using the JavaBeans `Introspector` class. Property values are set according to the caller's needs using the property's read and write methods.
- The customizer's `acceptsConnection` method is called to verify whether or not it can be used with a particular JDBC connection. If no connection is to be used, null is passed as an argument to this method.
- The customizer's `customize` method is called, passing the profile to customize, a JDBC connection, and an error log.
- The `customize` method returns true if the profile is changed, false is the profile is unchanged.
- Log entries added by the customizer during the `customize` call are reported as appropriate by the calling utility.
- A successfully updated profile is re-packaged with the application by the calling utility. Successfully updated profiles are those profiles for which the `customize` call returns true and there are no errors reported in the error log.

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

##

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

##

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.

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