INTERCLIENT 1

Opening a Database Connection

After loading the driver (or explicitly creating one), you can open a connection to the database. There are two ways to do this: with the DriverManager's getConnection() method or the driver object's connect() method.

Using the DriverManager to Get a Connection

When you want to access a database, you can get a java.sql.Connection object from the JDBC management layer's java.sql.DriverManager.getConnection() method. The getConnection() method takes a URL string and a java.util.Properties object as arguments. For each connection request, the DriverManager uses the URL to locate a driver that can connect to the database represented by the URL. If the connection is successful, a java.sql.Connection object is returned. The following example shows the syntax for establishing a database connection:

Connection c = DriverManager.getConnection (url,properties);

The Connection object in turn provides access to all of the InterClient classes and methods that allow you to execute SQL statements and get back the results.

Using InterClient Driver Object to Get a Connection

If you're using a named driver object to get a connection, use the connect() method. This method does the same thing and takes the same arguments as getConnection(). For example:

// Create the InterClient driver object explicitly
Driver d = new interbase.interclient.Driver();

//Open a database connection using the driver's connect method of the 
Connection connection = d.connect(url, properties);

Which Method to Use: the Driver's or DriverManager's?

Suppose that you've created an explicit driver object. Even though you could use the driver's connect() method, always use the generic JDBC methods and classes unless there is some specific reason (such as the ones discussed previously) not to. For example, suppose you declared an explicit driver object so you could get driver version numbers, but now you need to create a connection to the database. You should still use the DriverManager.getConnection() method to create a connection object (instead of the driver.connect() method).

Defining Connection Parameters

The arguments to connect() or getConnection() must be defined before trying to create the connection. They are the database URL and the connection properties.

Syntax for Specifying Database URLs

InterClient follows the JDBC standard for specifying databases using URLs. The JDBC URL standard provides a framework so that different drivers can use different naming systems that are appropriate for their own needs. Each driver only needs to understand its own URL naming syntax; it can reject any other URLs that it encounters. A JDBC URL is structured as follows:

jdbc:subprotocol:subname

The subprotocol names a particular kind of database connection, which is in turn supported by one or more database drivers. The DriverManager decides which driver to use based on which subprotocol is registered for each driver. The contents and syntax of subname in turn depend upon the subprotocol. If the network address is included in the subname, the naming convention for the subname is:

//hostname:/subsubname

subsubname can have any arbitrary syntax.

Defining an InterClient URL

InterClient URLs have the following format:

jdbc:interbase://server/full_db_path

"interbase" is the subprotocol, and server is the hostname of the InterBase server. Full_db_path (i.e., "subsubname") is the full pathname of a database file, including the server's root (/) directory. If the InterBase server is a Windows NT system, you must include the drive name as well. InterClient doesn't support passing any attributes in the URL. For local connections, use:

server = "localhost"

Note: The "/" between the server and full_db_path is treated as a delimiter only. When specifying the path for a Unix-based database, you must include the initial "/" for the root directory in addition to the "/" for the delimiter.

Examples

For example, with a Unix-based database, the URL

dbURL = "jdbc:interbase://accounts//dbs/orders.gdb"

refers to the database "orders.gdb" in the directory "/dbs" on the Unix server "accounts." The URL

dbURL = "jdbc:interbase://support/C:/dbs/customer.gdb"

refers to the database "customer.gdb" in the directory "/dbs" on drive C of the Wings or Win95 or NT server "support."

Defining the Connection Properties

Connection properties must also be defined before trying to open a database connection. To do this, you pass in a java.util.Properties object, which maps between tag strings and value strings. Two typical properties are "user" and "password." First, create the Properties object:

java.util.Properties properties = new java.util.Properties();

Now create the connection arguments. user and password are either literal strings or string variables. They must be the username and password on the InterBase database that you are connecting to:

properties.put ("user", user);

properties.put ("password", password);

Now create the connection with the URL and connection properties parameters:

Connection c = DriverManager.getConnection(url, properties);

Security

Client applications use standard database user name and password verification to access an InterBase database. InterClient encrypts the user name and password for transmission over the network.