Description: 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 might become necessary. It might be necessary to iterate though several calls to getPropertyInfo.
Keywords: java.sql.Driver.getPropertyInfo, Available databases, list of provided by databaseName attribute

# 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 might become necessary. It might 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 Derby system, do not use the method against an instance of org.apache.derby.jdbc.EmbeddedDriver. Instead, request the JDBC driver from the driver manager:

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

In a Derby system, the properties returned in the DriverPropertyInfo object are 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 "derby.system.bootAll" in Tuning Java DB.

getPropertyInfo requires a 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.

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 connection URL attribute that has not already been specified. Only those that make sense in the current context are returned.

Parent topic: Developing tools and using Derby with an IDE
Related concepts
Creating, dropping, and backing up databases
Using Derby with IDEs
Related reference
Database connection examples