Accessing Cloudconnector from a Client
Page 3 of 4

Using Cloudconnector Clients

Cloudconnector supplies a tailored JDBC driver and database connection URL for use by clients. To access the Cloudconnector server, the client must specify the JDBC Driver and the database connection URL.

NOTE: The Cloudscape Developer's Guide documents the database connection URL for using Cloudscape as an embedded database.

Specifying the Client JDBC Driver

Depending on whether you are connecting programmatically or from a Cloudscape tool, use one of the following to specify the JDBC driver:

  • a call to Class.forName.newInstance()
  • the drivers system property

Programmatically

In client code, specify the client JDBC driver for connecting to a Cloudscape server:

Class.forName("COM.cloudscape.core.WebLogicDriver").newInstance();

From ij or Cloudview

If using ij or Cloudview, specify the drivers system property when starting up the tool. For example:

java -Djdbc.drivers=COM.cloudscape.core.WebLogicDriver COM.cloudscape.tools.cview

or

java -Djdbc.drivers=COM.cloudscape.core.WebLogicDriver COM.cloudscape.tools.ij

Specifying the Database Connection URL

After you have specified the JDBC driver, you connect to the database using a database connection URL.

A Cloudscape client to Cloudconnector uses the following database connection URL:

jdbc:cloudscape:weblogic[-  ssl]:[  //hostname:portnum/]
[ subsubprotocol:] [databaseName];[cloudscapeAttributes]
[& webLogicAttributes]

(All of this is one string; the new lines above just make the URL readable.)

  • ssl

    Use -ssl after the weblogic parameter if you are using Cloudconnector with the Secure Socket Layer (SSL) turned on. For more information, see SSL Security in Cloudconnector.

  • //hostname:portnum/

    If the host and client are running on different machines, replace hostname with the name of the host running Cloudconnector. If not specified, hostname defaults to localhost. For single-system configurations, you can explicitly specify localhost, or you can leave this blank.

    Replace portnum with the port number for the host hostname. The port number may be specified in the weblogic.properties file (as the weblogic.system.listenPort property) or on the Cloudconnector JVM command line. If not specified, portnum defaults to 7001 (or 7002 if SSL is turned on).

    If you do not specify values for either hostname or portnum, the default value is //localhost:7001/ (or //localhost:7002/ for weblogic-ssl).

  • subsubprotocol:

    subsubprotocol is typically not specified. It indicates whether Cloudscape should look for a database in a directory, class path, or jar file. It is used only in rare instances, typically for read-only databases. The value of subsubprotocol can be one of the following:

    • directory
    • classpath
      Databases are treated as read-only databases, and all databaseNames must begin with at least a slash, because you specify them "relative" to the class path directory or archive.
    • jar
      Databases are treated as read-only databases.

      If jar is specified, an additional element is required before the databaseName:

      (pathToArchive)

      where pathToArchive is the full path (including filename) of the jar or zip file that holds the database.

  • [databaseName];[cloudscapeAttributes]

    Specify the database name and any database connection URL attributes as specified in Cloudscape Developer's Guide. For example, to create and connect to a new database called newDB, include the following in the database connection URL:

    newDB;create=true

  • webLogicAttributes

    Optionally, use this argument to set WebLogic properties for Cloudconnector such as prefetching and caching. (Prefetching always works with caching.) Properties set on the database connection URL are good for the current session only (as opposed to properties set in the weblogic.properties file on the server). (See Setting Session-Level WebLogic Properties on the URL.)

    For example, to turn off prefetching and caching, specify:

    &weblogic.t3.cacheRows=0

    Separate each property with an ampersand (&).

Example URLs

Here are some example database connection URLs for Cloudscape clients:

  • jdbc:cloudscape:weblogic:newDB;create=true;autocommit=false
    &weblogic.t3.cacheRows=0

    Connects to Cloudconnector installed on the local machine at the default port, creates and connects to a database called newDB, and turns off auto-commit (a Cloudscape property) as well as prefetching and caching (WebLogic properties).

  • jdbc:cloudscape:weblogic://Jeeves:5001/accounting/accounts

    Connects to Cloudconnector running on host Jeeves and listening on port 5001, and connects to an existing accounts database in the accounting directory.

  • jdbc:cloudscape:weblogic:newDB;user=fred;password=secret

    Specifies user credentials for Fred.

NOTE: Typically, client applications should not use the ;shutdown=true form of the database connection URL in client/server environments. The system administrator should use the provided utility to shut down Cloudconnector. See Shutting Down Cloudconnector.

Setting Session-Level WebLogic Properties on the URL

WebLogic properties can be set durably for a system using the weblogic.properties file. The weblogic.properties file is discussed in the Setting Cloudconnector Properties section of chapter 7. This section discusses temporary, session-level WebLogic properties, which are specified by including them in the client database connection URL.

Setting WebLogic properties on a connection URL makes them valid only for the duration of the current connection.

The following sections describe two properties you might want to set for a client session:

Turning off Prefetching and Caching

To improve performance, Cloudconnector provides server-side prefetching and client-side caching of rows. However, prefetching and caching can cause the following behavior:

  • They cause slightly different behavior in some result set manipulation situations. For example, with prefetching and caching turned on, getting a result set fails if there are any errors (such as division by zero) when the system prefetches and caches the first set of rows.
  • They prevent you from using updatable cursors.

    Updatable cursors are described in the Cloudscape Reference Manual.

If you need more control over result set behavior or want to use the positioned update and delete statements (cursors), set the following property value, which disables both prefetching and caching:

weblogic.t3.cacheRows=0

Turning off the Parameter Cache

If you issue PreparedStatement clearParameters requests and need to ensure that statements are not executed until all parameters are reset, set the following property value:

weblogic.t3.enableSetParamCache=false