Developing Tools and Using Cloudscape with an IDE
Page 3 of 5

Offering Connection Choices to the User

JDBC's java.sql.Driver.getPropertyInfo method allows a generic GUI tool to determine the properties for which it should prompt a user in order to get enough information to connect to a database. Depending on the values the user has supplied so far, additional values may become necessary, so it may be necessary to iterate though several calls to getPropertyInfo. If no more properties are necessary, the call returns an array of zero length.

In a Cloudscape system, do not use the method against an instance of COM.cloudscape.core.JDBCDriver. Instead, request the JDBC driver from the driver manager:

java.sql.DriverManager.getDriver(
    "jdbc:cloudscape:").getPropertyInfo(URL, Prop)

In a Cloudscape system, the properties returned in the DriverPropertyInfo object are database connection URL attributes, including a list of booted databases in a system (the databaseName attribute).

Databases in a system are not automatically booted until you connect with them. You can configure your system to retain the former behavior, in which case the steps described in this section will continue to work. See cloudscape.system.bootAll in Tuning Cloudscape.

getPropertyInfo requires a database connection URL and a Properties object as parameters. Typically, what you pass are values that you will use in a future call to java.sql.DriverManager.getConnection when you actually connect to the database. For information about setting attributes in calls to java.sql.DriverManager.getConnection, see Examples.

A call to getPropertyInfo with parameters that contain sufficient information to connect successfully returns an array of zero length. (Receiving this zero-length array does not guarantee that the getConnection call will succeed, because something else could go wrong.)

Repeat calls to getPropertyInfo until it returns a zero-length array or none of the properties remaining are desired.

The DriverPropertyInfo Array

When a non-zero-length array is returned by getPropertyInfo, each element is a DriverPropertyInfo object representing a database connection URL attribute that has not already been specified. Only those that make sense in the current context are returned.

This DriverPropertyInfo object contains:

  • name of the attribute
  • description
  • current value

    If an attribute has a default value, this is set in the value field of DriverPropertyInfo, even if the attribute has not been set in the database connection URL or the Properties object. If the attribute does not have a default value and it is not set in the URL or the Properties object, its value will be null.

  • list of choices
  • whether required for a connection request

Several fields in a DriverPropertyInfo object are allowed to be null.

databaseName

For example, if a Cloudscape system has the databases toursDB and flightsDB booted in its system directory, and some user has also connected to a database
A:/dbs/tours94 the array returned from getPropertyInfo will contain at least one object corresponding to the databaseName attribute. The choices field of the DriverPropertyInfo object will contain an array of three Strings with the values "toursDB", "flightsDB", and "A:/dbs/tours94". This object is returned only if the proposed connection objects do not already include a database name (in any form) or include the shutdown attribute with the value true.

Example

A typical use of getPropertyInfo in a GUI can be seen in the "Connect to DB detailed ..." menu option of the JDBCTest tool from Intersolv.

Here is some example code:

import java.sql.*;
import java.util.Properties;
// start with the least amount of information
// to see the full list of choices
//
// we could also enter with a URL and Properties
// provided by a user.
String url = "jdbc:cloudscape:";
Properties info = new Properties();
Driver cDriver = DriverManager.getDriver(url);
for (;;)
        {
        DriverPropertyInfo[] attributes = cDriver.getPropertyInfo(
            url, info);
         // zero length means a connection attempt can be made
        if (attributes.length == 0)
        break;
        // insert code here to process the array, e.g.,
        // display all options in a GUI and allow the user to
        // pick and then set the attributes in info or URL.
        }
// try the connection
Connection conn = DriverManager.getConnection(url, info);