All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class interbase.interclient.Driver

java.lang.Object
   |
   +----interbase.interclient.Driver

public final class Driver
extends Object
implements Driver

The Java SQL framework allows for multiple database drivers.

Each driver should supply a class that implements the Driver interface.

The DriverManager will try to load as many drivers as it can find and then for any given connection request, it will ask each driver in turn to try to connect to the target URL.

It is strongly recommended that each Driver class should be small and standalone so that the Driver class can be loaded and queried without bringing in vast quantities of supporting code.

When a Driver class is loaded, it should create an instance of itself and register it with the DriverManager. This means that a user can load and register a driver by doing Class.forName("interbase.interclient.Driver").

There are three ways to load the InterClient driver.

Add "interbase.interclient.Driver" to your System jdbc.drivers properties list. The JDBC driver manager will automatically load an anonymous driver instance when you reference an InterBase database URL as in
```
 DriverManager.getConnection ("jdbc:interbase://server//database-dir/atlas.gdb", 
                              "sysdba", "masterkey");
 
```

Load the driver yourself

 Class.forName ("interbase.interclient.Driver");
 DriverManager.getConnection ("jdbc:interbase://server//database-dir/atlas.gdb", 
                              "sysdba", "masterkey");

When the Driver class is loaded, an anonymous driver instance is automatically created and registered with the driver manager. The driver manager will locate the driver instance based on the URL prefix "jdbc:interbase:".

A handle to the registered driver instance may be obtained as follows

 java.sql.Driver registeredDriver = DriverManager.getDriver ("jdbc:interbase:");

Now you can use Driver methods or InterClient Driver extensions such as the Monitor.

 interbase.interclient.Monitor monitor = 
   ((interbase.interclient.Driver) registeredDriver).getMonitor ();
 monitor.enableAllTraces (true);
 monitor.setTraceStream (System.out);
 DriverManager.getConnection ("jdbc:interbase://server//database-dir/atlas.gdb", 
                              "sysdba", "masterkey"); // jdbc calls are traced.

Create a named driver instance explicitly using

 Driver unregisteredDriver = new interbase.interclient.Driver ();
 java.sql.Connection connection = 
   unregisteredDriver.connect ("jdbc:interbase://server//database-dir/atlas.gdb", 
                               properties);

In this case, the named driver is not registered with the driver manager and can be used directly to get a connection. Here's an example of its use.

 import interbase.interclient.*;
 Driver unregisteredDriver = new Driver ();
 Monitor monitor = unregisteredDriver.getMonitor ();
 monitor.setTraceStream (System.out);
 monitor.enableAllTraces (true);
 ConnectionProperties properties = new ConnectionProperties ();
 properties.setUser ("sysdba", "masterkey");
 java.sql.Connection connection = 
   unregisteredDriver.connect ("jdbc:interbase://server//databases/atlas.gdb", 
                               properties);

Keep in mind that even if you use an unregistered driver, an anonymous driver instance is still created and registered with the driver manager when the interbase.interclient.Driver class is loaded into memory. A call to DriverManager.getConnection() would be using a different driver instance than a call to unregisteredDriver.connect() as above.

You can register a named driver instance with the driver manager in addition to the automatically registered anonymous instance.

 Driver driver = new interbase.interclient.Driver ();
 java.sql.DriverManager.registerDriver (driver);

However, registering multiple InterClient driver instances would only be necessary if different instances recognized different URL prefixes. For now, the InterClient driver only recognizes "jdbc:interbase:".

Note for JBuilder users:

In order to use the InterClient driver with JBuilder, you should modify CLASSPATH and IDECLASSPATH in your JBuilder.INI file to include

   interclient-install-dir\classes

   interclient-install-dir\interclient.jar.

The JBuilder.INI file is located in JBuilder's bin directory.

Here is how to establish a database connection with the JBuilder dataset package.

 import java.sql.*;
 import borland.jbcl.dataset.*;
 borland.jbcl.dataset.Database database = new Database ();
 database.setConnection (
   new ConnectionDescriptor ("jdbc:interbase://server//databases/atlas.gdb",
                             "sysdba",
                             "masterkey", 
                             false, 
                             "interbase.interclient.Driver"));
 borland.jbcl.dataset.QueryDataSet queryDataSet = new QueryDataSet ();
 queryDataSet.setQuery (new QueryDescriptor (database, "select * from employee", null, true, false));

For further information, see the JBuilder Programmer's guide, Chapter 5.

Although an InterClient driver may have an expiration date, for most general releases InterClient itself will not expire. Instead the InterServer component has an expiration date defined in the InterServer license file (ic_license.dat). Newer releases of InterServer may refuse to talk with older releases of InterClient. In this way, an older release of InterClient is effectively expired when all compatible versions of InterServer expire. A customer wishing to continue using a older version of InterServer/InterClient, may substitute in a new ic_license.dat file with an extended license.

See Also:: DriverManager, Connection

Driver(): Create an explicit driver instance.

acceptsURL(String): Returns true if the driver thinks that it can open a connection to the given URL.
asString(SQLException): Get the String representation for a SQLException chain. InterClient Extension.
clientServerEdition(): Are remote connections allowed? InterClient Extension.
connect(String, Properties): Try to make a database connection to the given URL.
expiredDriver(): Has the InterClient driver expired? InterClient Extension.
getBuildNumber(): Get the build number for this driver. InterClient Extension.
getCompanyName(): Who developed this driver? InterClient Extension.
getExpirationDate(): Get the expiration date for this driver. InterClient Extension.
getJDBCNetProtocol(): Get the database URL prefix to use for InterBase connections. InterClient Extension.
getJDBCNetProtocolVersion(): Get the version of the messaging protocol between InterClient and InterServer. InterClient Extension.
getMajorVersion(): Get the driver's major version number.
getMinorVersion(): Get the driver's minor version number.
getMonitor(): Get a monitor for tracing jdbc calls. InterClient Extension.
getPropertyInfo(String, Properties): The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database.
getServer(String, String, String): Attach to the InterBase administration service. InterClient Extension.
jdbcCompliant(): Report whether the Driver is a genuine JDBC COMPLIANT (tm) driver.

Driver

  public Driver()

Create an explicit driver instance.

connect

  public synchronized Connection connect(String url,
                                         Properties properties) throws SQLException

Try to make a database connection to the given URL. The driver should return "null" if it realizes it is the wrong kind of driver to connect to the given URL. This will be common, as when the JDBC driver manager is asked to connect to a given URL it passes the URL to each loaded driver in turn.

The driver should raise a SQLException if it is the right driver to connect to the given URL, but has trouble connecting to the database.

The java.util.Properties argument can be used to passed arbitrary string tag/value pairs as connection arguments. Normally at least "user" and "password" properties should be included in the Properties. The ConnectionProperties class is supplied as a convenience for setting connection properties before requesting a connection.

Parameters:: url - The URL of the database to connect to.; info - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included.
Returns:: a Connection to the URL.
See Also:: ConnectionProperties

acceptsURL

  public boolean acceptsURL(String url) throws SQLException

Returns true if the driver thinks that it can open a connection to the given URL. Typically drivers will return true if they understand the subprotocol specified in the URL and false if they don't.

Parameters:: url - The URL of the database.
Returns:: True if this driver can connect to the given URL.

getPropertyInfo

  public synchronized DriverPropertyInfo[] getPropertyInfo(String url,
                                                           Properties properties)

The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database. Note that depending on the values the human has supplied so far, additional values may become necessary, so it may be necessary to iterate though several calls to getPropertyInfo.

Parameters:: url - The URL of the database to connect to.; info - A proposed list of tag/value pairs that will be sent on connect open.
Returns:: An array of DriverPropertyInfo objects describing possible properties. This array may be an empty array if no properties are required.

getMajorVersion

  public int getMajorVersion()

Get the driver's major version number. Initially this should be 1.

getMinorVersion

  public int getMinorVersion()

Get the driver's minor version number. Initially this should be 0.

jdbcCompliant

  public boolean jdbcCompliant()

Report whether the Driver is a genuine JDBC COMPLIANT (tm) driver. A driver may only report "true" here if it passes the JDBC compliance tests, otherwise it is required to return false.

JDBC compliance requires full support for the JDBC API and full support for SQL 92 Entry Level. It is expected that JDBC compliant drivers will be available for all the major commercial databases.

This method is not intended to encourage the development of non-JDBC compliant drivers, but is a recognition of the fact that some vendors are interested in using the JDBC API and framework for lightweight databases that do not support full database functionality, or for special databases such as document information retrieval where a SQL implementation may not be feasible.

InterBase is only two features shy of compliance:

Quoted SQL identifiers.
Asynchronous cancel and statement timeout.

Returns:: false; true for 1.0

getBuildNumber

  public int getBuildNumber()

InterClient Extension

Get the build number for this driver.

getExpirationDate

  public Date getExpirationDate()

InterClient Extension

Get the expiration date for this driver.

Returns null if the InterClient driver does not expire.

Note: Although InterClient may not expire, InterServer may.

See Also:: ExpiredDriverException, getServerExpirationDate

expiredDriver

  public boolean expiredDriver()

InterClient Extension

Has the InterClient driver expired?

clientServerEdition

  public boolean clientServerEdition()

InterClient Extension

Are remote connections allowed?

The non-client/server edition allows only "localhost" connections.

Returns:: true if remote connections are allowed, false for localhost only.

getJDBCNetProtocol

  public String getJDBCNetProtocol()

InterClient Extension

Get the database URL prefix to use for InterBase connections.

A type 3 JDBC driver, such as InterClient, establishes a DBMS independent communication layer between the JDBC client and a middleware server (InterServer). Of course, InterServer uses a DBMS specific protocol for talking with the InterBase server on the backend.

Returns:: jdbc:interbase:

getJDBCNetProtocolVersion

  public int getJDBCNetProtocolVersion()

InterClient Extension

Get the version of the messaging protocol between InterClient and InterServer.

See Also:: getServerJDBCNetProtocolVersion

getCompanyName

  public String getCompanyName()

InterClient Extension

Who developed this driver?

Returns:: The company that produced this driver.
See Also:: getServerCompanyName

asString

  public static String asString(SQLException e)

InterClient Extension

Get the String representation for a SQLException chain.

getMonitor

  public Monitor getMonitor()

InterClient Extension

Get a monitor for tracing jdbc calls.

getServer

  public Server getServer(String serverURL,
                          String sysdba,
                          String password) throws SQLException

InterClient Extension for future release

Attach to the InterBase administration service.

You must pass SYSDBA user and password to obtain a Server object.

Note: This does not start the InterBase service. The InterBase service is started with the Server.startup () method.

Throws: SQLException: Not yet implemented.

All Packages  Class Hierarchy  This Package  Previous  Next  Index