JDBC Reference
Page 4 of 31

java.sql.DriverManager.getConnection

A Java application using the JDBC API establishes a connection to a database by obtaining a Connection object. The standard way to obtain a Connection object is to call the method DriverManager.getConnection, which takes a String containing a database connection URL. A JDBC database connection URL (uniform resource locator) provides a way of identifying a database.

DriverManager.getConnection can take one argument besides a database connection URL, a Properties object. You can use the Properties object to set database connection URL attributes.

You can also supply strings representing user names and passwords. When they are supplied, Cloudscape checks whether they are valid for the current system if user authentication is enabled. User names are passed to Cloudscape as authorization identifiers, which are used to determine whether the user is authorized for access to the database and for determining the default schema. When the connection is established, if no user is supplied, Cloudscape sets the default user to APP, which Cloudscape uses to name the default schema. If a user is supplied, the default schema is the same as the user name if one exists (otherwise, it's APP).

Cloudscape Database Connection URL Syntax

A Cloudscape database connection URL consists of the basic database connection URL followed by an optional subsubprotocol and optional attributes.

This section provides reference information only. For a more complete description, including examples, see Connecting to Databases in the Cloudscape Developer's Guide.

Embedded Databases

For applications with embedded databases, the syntax of the database connection URL is

  jdbc:cloudscape:[  subsubprotocol:][  databaseName][;  attributes]*
  • jdbc:cloudscape:

    In JDBC lingo, cloudscape is the subprotocol for connecting to a Cloudscape database. The subprotocol is always cloudscape and does not vary.

  • subsubprotocol:

    subsubprotocol, which is not typically specified, specifies where Cloudscape looks for a database: in a directory, in a class path, or in a jar file. It is used only in rare instances, usually for read-only databases. subsubprotocol is 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. (You do not have to specify classpath as the subsubprotocol; it is implied.)
    • jar
      Databases are treated as read-only databases.

      jar requires an additional element immediately before the databaseName:

      (pathToArchive)

      pathToArchive is the path to the jar or zip file that holds the database and includes the name of the jar or zip file.

      See the Cloudscape Developer's Guide for examples of database connection URLs for read-only databases.

  • databaseName

    Specify the databaseName to connect to an existing database or a new one. You can shut down the current database if you specify current=true for the databaseName combined with the shutdown=true attribute.

    You can specify the database name alone, or with a relative or absolute path. See Standard Connections--Connecting to Databases in the File System in the Cloudscape Developer's Guide.

  • attributes

    Specify 0 or more database connection URL attributes as detailed in The Cloudscape Database Connection URL Attributes.

Syntax--Clients to Cloudconnector

For clients to Cloudconnector, the syntax of the database connection URL is

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

Use -ssl after the word weblogic if you are using Cloudconnector with SSL turned on.

  • //hostname:portnum/

    Replace hostname with the name of the host running Cloudconnector if it is not running on the same machine as the client. Replace portnum with the port number specified for the weblogic.system.listenPort property in the weblogic.properties file or on the Cloudconnector JVM command line. 7001 is the default value. 7002 is the default value if SSL is turned on.

    If you do not specify //hostname:portnum/, the default value is
    //localhost:7001/. For weblogic-ssl, the default value is //localhost:7002/.

  • subsubprotocol:

    subsubprotocol, which is not typically specified, specifies where Cloudscape looks for a database: in a directory, in a class path, or in a jar file. It is used only in rare instances, usually for read-only databases. subsubprotocol is 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.

      jar requires an additional element immediately before the databaseName:

      (pathToArchive)

      pathToArchive is the path to the jar or zip file that holds the database and includes the name of the jar or zip file.

  • [databaseName][;cloudscapeAttributes]

    Specify the database name and any database connection URL attributes as specified in The Cloudscape Database Connection URL Attributes.

  • webLogicAttributes

    You can set Cloudconnector (WebLogic) properties such as prefetching and caching. Properties set on a database connection URL are valid for the current session only. For examples, see the Cloudscape Server and Administration Guide.

    Separate each WebLogic property with a new ampersand (&).

Syntax--Clients to RmiJdbc Server

For clients to RmiJdbc Server, the syntax of the database connection URL is

jdbc:cloudscape:rmi: //hostname:portnum/[ subsubprotocol:]
[databaseName][;cloudscapeAttributes]

  • //hostname:portnum/

    Replace hostname with the name of the host running RmiJdbc if it is not running on the same machine as the client. Replace portnum with the port number for the server.1099 is the default value.

    If you do not specify //hostname:portnum/, the default value is
    //localhost:1099/.

  • subsubprotocol:

    subsubprotocol, which is not typically specified, specifies where Cloudscape looks for a database: in a directory, in a class path, or in a jar file. It is used only in rare instances, usually for read-only databases. subsubprotocol is 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.

      jar requires an additional element immediately before the databaseName:

      (pathToArchive)

      pathToArchive is the path to the jar or zip file that holds the database and includes the name of the jar or zip file.

  • [databaseName][;cloudscapeAttributes]

    Specify the database name and any database connection URL attributes as specified in The Cloudscape Database Connection URL Attributes.

Additional Syntax

Cloudscape also supports the following syntax:

jdbc:default:connection

This database connection URL is equivalent to the standard Cloudscape using the current=true attribute. For more information, see current=true.

The Cloudscape Database Connection URL Attributes

You can supply an optional list of attributes to a database connection URL. Cloudscape translates these attributes into properties, so you can also set attributes in a Properties object passed to DriverManager.getConnection. (You cannot set those attributes as system properties, only in an object passed to the DriverManager.getConnection method.)

These attributes are specific to Cloudscape and are listed in Chapter 7, "Database Connection URL Attributes".

Attribute name/value pairs are converted into properties and added to the properties provided in the connection call. If no properties are provided in the connection call, a properties set is created that contains only the properties obtained from the database connection URL.

Connection conn = DriverManager.getConnection(
    "jdbc:cloudscape:toursDB;create=true");

-- setting an attribute in a Properties object
Properties p = new Properties();
p.put("create", "true"); Connection conn = DriverManager.getConnection(     "jdbc:cloudscape:toursDB", myProps); -- passing user name and password Connection conn = DriverManager.getConnection( "jdbc:cloudscape:toursDB", "dba", "password");

NOTE: Attributes are not parsed for correctness. If you pass in an incorrect attribute or corresponding value, it is simply ignored. (Cloudscape does provide a tool for doing so. For more information, see the Cloudscape Tools and Utilities Guide.)