All Packages This Package Previous Next
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.
Beans.instantiate()
.
Introspector
class. Property values are set according to the
caller's needs using the property's read and write methods.
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.
customize
method is called, passing
the profile to customize, a JDBC connection, and an error log.
customize
method returns true if the profile is
changed, false is the profile is unchanged.
customize
call are reported as appropriate by the calling
utility.
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.
public abstract boolean acceptsConnection(Connection conn)
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.
public abstract boolean customize(Profile profile, Connection conn, ErrorLog log)
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.
All Packages This Package Previous Next