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

Using Cloudscape with IDEs

When you use an integrated development environment (IDE) to develop an embedded Cloudscape application, you may need to run Cloudscape within a server framework. This is because an IDE may try connect to the database from two different JVMs, whereas only a single JVM instance should connect to a Cloudscape database at one time, as described in One Cloudscape per System (multiple connections from the same JVM are allowed).

An "embedded Cloudscape application" is one which runs in the same JVM as the application. Such an application uses the embedded Cloudscape driver (COM.cloudscape.core.JDBCDriver; see Embedded Cloudscape JDBC Driver) and database connection URL (jdbc:cloudscape:databaseName; see Embedded Cloudscape JDBC Database Connection URL). If you use this driver name or database connection URL from the IDE, when the IDE tries to open a second connection to the same database with the embedded Cloudscape, the attempt fails. Two JVMs cannot connect to the same database in embedded mode. This situation is described in more detail in IDEs and Multiple JVMs.

RmiJdbc, free software that provides remote access to JDBC drivers, is included with all Cloudscape products and is a good choice when developing an embedded application with an IDE. RmiJdbc is described in more detail in About the RmiJdbc Driver.

The basic steps you take to work around this limitation are:

  1. Start RmiJdbc server before using the IDE.
  2. Make sure the IDE uses the RmiJdbc client driver and RmiJdbc client database connection URL to connect to a database.

    Requests from multiple JVMs can succeed, because the RmiJdbc server handles the connection requests. (For more information about RmiJdbc, see the Cloudscape Server and Administration Guide.)

  3. Before deploying the application, change the driver name back to the embedded driver name and the database connection URL back to the embedded database connection URL.

These steps are described in more detail in Using the RmiJdbc Driver in an IDE.

IDEs and Multiple JVMs

When you use an integrated development environment (IDE) to build a Java application, you can launch the application from within the IDE at any point in the development process. For example, In JBuilder, you can launch an application from the Run menu. In Visual Cafe, you can launch applications from the Project menu. In either case, the IDE launches a JVM dedicated to the application. When the application completes, the JVM exits. Any database connections established by the application are closed.

During the development of a database application, most IDEs allow you to test individual database connections and queries without running the entire application. For example, the following figure shows the JBuilder window for testing a database query in JBuilder's "design mode":

Figure 9-1 Testing a database connection from within JBuilder.

When you test an individual database connection or query (which, of course, also requires a database connection), the IDE launches a JVM that runs in a specialized testing environment. In this case, when a test completes, the JVM remains active and available for further testing, and the database connection established during the test remains open.

If you use the embedded Cloudscape JDBC driver, you will encounter errors in the following situations:

  • You test an individual query or database connection and then try to run an application that uses the same database as the tested feature.

    The database connection established by testing the connection or query stays open, and prevents the application from establishing a connection to the same database.

  • You run an application, and before it completes (for example, while it waits for user input), you attempt to run a second application or to test a connection or query that uses the same database as the first application.

Running Cloudscape inside RmiJdbc server allows you to run applications and test individual connections and queries without conflicts between connections.

About the RmiJdbc Driver

The RmiJdbc driver is server framework that uses the Java remote method interface (RMI) to give client applications access to a target JDBC driver on a remote server. RmiJdbc server handles connections from remote or local client applications in separate JVMs.

In the context of developing a Cloudscape application with an IDE, this means that connection requests from the JVM in the IDE's test environment and connection requests from the JVM dedicated to an application are treated as requests from separate clients. The client-side component of the RmiJdbc driver sends these requests to the RmiJdbc's server agent, which threads the requests to use a single instance of the Cloudscape JDBC driver.

Using the RmiJdbc Driver in an IDE

To develop an embedded Cloudscape application using the RmiJdbc driver:

  1. Make sure your class path contains the path to the RmiJdbc classes and the path to the primary Cloudscape library, as in the following example:

    set classpath=
    %cloudscape_install%\frameworks\RmiJdbc\classes\
    RmiJdbc.jar;%cloudscape_install%\lib\cloudscape.jar;
    %classpath%

  2. Start the RmiJdbc server:

    java -Dcloudscape.system.home=d:\cloudscape\demo\databases
        -ms16m -mx32m RmiJdbc.RJJdbcServer
        COM.cloudscape.core.JDBCDriver

    This starts the RmiJdbc server and binds it to the Cloudscape JDBC driver (COM.cloudscape.core.JDBCDriver).

  3. Start your IDE.
  4. In your IDE, specify the client driver name like this:
COM.cloudscape.core.RmiJdbcDriver
  1. In your IDE, use the RmiJdbc client database connection URL:

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

  2. Develop your application, testing the application and database connections and queries as needed.
  3. Before deploying your application, replace the driver and database connection URL wherever they occur application code with the Cloudscape embedded driver name (COM.cloudscape.core.JDBCDriver) and embedded database connection URL (jdbc:cloudscape:databaseName; see Embedded Cloudscape JDBC Database Connection URL).