Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## interbase.interclient
Interface Adaptor

All Known Implementing Classes:
  ResultSet

public interface Adaptor

Provides a means to modify the standard behavior of an InterClient JDBC object.

The Adaptor interface is used to modify, or adapt, the behavior of an InterClient JDBC object in order to improve performance for certain applications which do not require the full implementation of JDBC standard behavior for that object.

A JDBC class which implements this interface is said to be adaptable. Currently, only the InterClient `ResultSet` class implements this interface. Hence InterClient result set objects are adaptable.

The Adaptor interface can be implemented by any JDBC class which can be adapted for improved performance under certain assumptions. An adaptation modifies the default behavior for a JDBC object by compromising standard JDBC behavior in favor of performance.

Certain JDBC driver classes may choose to implement this interface for enhanced performance with the JBuilder dataset components. Currently, JBuilder only looks for ResultSet adaptations. Future versions of JBuilder and InterClient may allow for the behavior of other driver objects to be adaptable as well.

Here's an example adaptation of a result set object which instructs the driver to right trim `SQL CHAR` string instances (`RIGHT_TRIM_STRINGS`), and to avoid constructing multiple java.sql.Date instances by reusing the first Date fetched on each subsequent fetch (`SINGLE_INSTANCE_TIME`). By reusing a single java.sql.Date instance, the `SINGLE_INSTANCE_TIME` adaptation avoids the overhead associated with the driver calling the java.sql.Date constructor for each row selected. The `RIGHT_TRIM_STRINGS` adaptation relieves an application from having to right trim `CHAR` strings which are padded according the JDBC standard.

     import interbase.interclient.Adaptor;

     java.sql.Statement s = c.createStatement ();
     java.sql.ResultSet rs = s.executeQuery ("select NAME, BIRTHDAY from BIRTHDAYS");

     Adaptor rsAdaptor = (Adaptor) rs;
     rsAdaptor.adapt (Adaptor.RIGHT_TRIM_STRINGS, null);
     rsAdaptor.adapt (Adaptor.SINGLE_INSTANCE_TIME, null);

     while (rs.next ()) {
       System.out.println (rs.getString ("NAME"));    // no need to call String.trim()
       System.out.println (rs.getDate ("BIRTHDAY"));  // The first Date object constructed is reused
     }                                                // and modified throughout the iterations.

A third party tool built to run with any or multiple JDBC drivers could be compiled with this interface in its class path in order to leverage performance improvements when using the InterClient driver as follows:

     java.sql.ResultSet resultSetToProcess = ...
     try {
       Class.forName ("interbase.interclient.Adaptor");
       interbase.interclient.Adaptor adaptor = (interbase.interclient.Adaptor) resultSetToProcess;
       adaptor.adapt (SINGLE_INSTANCE_TIME, null);
     }
     catch (ClassNotFoundException e) {
       // no adaptor found, that's ok, just use default driver behavior
     }
     process (resultSetToProcess);

The performance of the 3rd party application will be improved when InterClient is loaded as the JDBC driver backend, even if no other InterClient extensions are used, and the application makes only portable java.sql method calls.

Notice that a 3rd party tool provider needs to compile with the interbase.interclient.Adaptor interface in the class path, but does not need to compile with the complete interbase.interclient package unless it is using other InterClient extensions to the JDBC API.

Also notice that the Adaptor interface does NOT need to be shipped along with the 3rd party product. If the InterClient driver is loaded then the Adaptor interface will be loaded as well. If the InterClient Adaptor interface is not present in the application class path then the adaptation will not be performed. This allows for adaptations to be made in JDBC applications which use only portable JDBC calls, so that the application will still run against any driver, but may have performance adaptations when running against InterClient.

InterClient VARs or those wishing to redistribute the Adaptor interface with a 3rd party app may prefer the following code:

     import interbase.interclient.Adaptor;

     java.sql.ResultSet resultSetToProcess = ...
     if (resultSetToProcess instanceof Adaptor) {
       Adaptor adaptor = (Adaptor) resultSetToProcess;
       adaptor.adapt (SINGLE_INSTANCE_TIME, null);
     }
     process (resultSetToProcess);

Also see `borland.jdbc.SQLAdapter` and `com.inprise.sql.SQLAdapter` interfaces which are all identical to the InterClient Adaptor interface, and are all implemented by the InterClient `ResultSet` class.

Since:
  Extension, since InterClient 1.0

Field Summary
`static int` | `RIGHT_TRIM_STRINGS` This modifier instructs an adaptable result set object to create String instances for `SQL CHAR` fields with white space already trimmed from the end of the String.
`static int` | `SINGLE_INSTANCE_TIME` This modifier instructs an adaptable result set object to reuse a single instance of a Java `Time`, `Date`, or `Timestamp` object for the life of the result set.

Method Summary
`boolean` | `adapt(int modifier, Object extraInfo)` Adapt a JDBC object as described by one of the Adaptor modifiers.
`void` | `revert(int modifier)` Revert back to the default JDBC behavior for this previously adapted object.

Field Detail

### RIGHT_TRIM_STRINGS

    public static final int RIGHT_TRIM_STRINGS

  This modifier instructs an adaptable result set object to create String instances for `SQL CHAR` fields with white space already trimmed from the end of the String. This adaptation affects the behavior of `ResultSet.getString(column)`.
  Since:
    Extension, since InterClient 1.0

### SINGLE_INSTANCE_TIME

    public static final int SINGLE_INSTANCE_TIME

  This modifier instructs an adaptable result set object to reuse a single instance of a Java `Time`, `Date`, or `Timestamp` object for the life of the result set. This adaptation affects the behavior of `ResultSet.getDate(column)`, `ResultSet.getTime(column)` and `ResultSet.getTimestamp(column)`.
  Since:
    Extension, since InterClient 1.0

Method Detail

### adapt

    public boolean adapt(int modifier,
                         Object extraInfo)
                  throws SQLException

  Adapt a JDBC object as described by one of the Adaptor modifiers. The `extraInfo` parameter is currently unused.
  Parameters:
    `modifier` - is either `RIGHT_TRIM_STRINGS` or `SINGLE_INSTANCE_TIME`
    `extraInfo` - any extra information that needs to be specified along with the modifier, currently unused.
  Returns:
    true if the modifier is supported, false otherwise.
  Throws:
    `SQLException` - if the driver is unable to adapt to the modification
  Since:
    Extension, since InterClient 1.0

### revert

    public void revert(int modifier)
                throws SQLException

  Revert back to the default JDBC behavior for this previously adapted object.
  Parameters:
    `modifier` - is either `RIGHT_TRIM_STRINGS` or `SINGLE_INSTANCE_TIME`
  Throws:
    `SQLException` - if the driver is unable to revert the modification back to the standard JDBC behavior.
  Since:
    Extension, since InterClient 1.0

Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Send comments or suggestions to interclient@borland.com