interbase.interclient
Interface Adaptor

All Known Implementing Classes:

ResultSet

public abstract 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 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);
 

Since:

Extension

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 this 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 affects the behavior of ResultSet.getString().

Since:

Extension

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 affects the behavior of ResultSet.getDate(), ResultSet.getTime() and ResultSet.getTimestamp().

Since:

Extension

Method Detail

adapt

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

Adapt this JDBC object as described by one of the Adaptor modifiers.

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 driver is unable to adapt to the modification..

Since:

Extension

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 driver is unable to revert the modification back to the standard JDBC behavior.

Since:

Extension