JDBC User Guide

DataCaster is a Java distributed database, and supports the Java database connectivity (JDBC) standard for Java applications to connect to the database. The JDBC driver and the underlying database supports the majority of the functionality specified in the JDBC 3.0 specification, but currently does not support all of the JDBC 3.0 features.

This guide provides a brief overview of how to use JDBC with DataCaster, and then lists the features supported and what is not supported. Please see the JDBC section of the Sun Java Tutorial for an good introduction to using JDBC. Please see the sections below for specific information you need on using JDBC with DataCaster.

Using JDBC Connections

Java applications use JDBC to connect to SQL databases in a number of ways. These include using a separate standalone database, often not written in Java, or embedding a Java database in the application. In the former case, the Java application may access the standalone database over the network.

The typical application architecture has a standalone database to which one of more separate Java applications connect via JDBC. A JDBC driver co-resident with the application performs the connectivity functions and provides the JDBC API to the Java application.

In the embedded case, a Java database can be co-resident with the application in the same JVM and provides the JDBC API more directly to the application.

DataCaster supports both modes of access. The best performance for a given application is obtained by embedding the database with the Java application. In this case, the database provides very low-overhead connections and a number of performance benefits.

A remote JDBC driver, i.e. the driver using RMI to connect to a standalone DataCaster instance, is also available. For some applications, e.g. J2EE and other applications that require separation of database and application, this driver needs to be used.

How to use JDBC for each of these cases is described below.

Embedded Database Case

In the embedded database case, the DataCaster jar needs to be in the classpath of your application. You can then use the JDBC URL for an embedded database to connect to the database. Multiple threads and users of your application can use the embedded database at the same time. Each database will be started when the first connection is made, and closed when the last connection is disconnected.

For users familar with JDBC, all the need to know is:

• Driver Classname: com.applibase.jdbc.DatabaseDriver
• Connection URL: jdbc:dcp:database_name

The database_name is the name of the database you want to connect to. A DataCaster instance can have multiple databases, and you will need to specify which database you are connecting to.

The following is a simple example of using JDBC for the embedded database case.

First you need to import some JDBC interfaces from the java.sql packge.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

This is a simple Java application program to be run from the command line without arguments. Hence the class main method is where we insertthe JDBC code.

public class SimpleJDBC {

    public void main(String args[]) {

The JDBC driver needs to be loaded first, using the complete driver classname.

        try {
            Class.forName("com.applibase.jdbc.DatabaseDriver");
        } catch (java.lang.ClassNotFoundException ex) {
            System.err.print("Can't load JDBC driver: "+ex.getMessage());
            System.exit(1);
        }

The url for the embedded case is used, and specifies the database name, which is productsdb. We then make a connection to the database using the DriverManager.getConnection() method.

        try {
            String url = "jdbc:dcp:productsdb";
            Connection con = DriverManager.getConnection(url, "myname", "mypasswd");

Next we execute a simple select on the products table uwing an SQL query string. The statement execution returns a ResultSet object.

            String queryString = "select * from products";
            Statement stmt = con.createStatement();
            ResultSet rs = stmt.executeQuery(queryString);

We iterate over the ResultSet object to get the desired data for each row of the table.

            while (rs.next()) {
                String product = rs.getString("product_name");
                float price = rs.getFloat("price");
                System.out.println(product + ": $" + price);
            }

Many of the JDBC methods can throw an SQLException, which we catch below.

            
        } catch (SQLException ex) {
            System.err.print("Did not quite work: "+ex.getMessage());

And we want to make sure we close the connection, which we do here in the finally block. Closing the database is always a good idea, to mimize delays on restart, and avoid issues with saving data and database recovery.

        } finally {
            if (con != null) con.close();
        }
    }
}

When using the DataCaster server for your web applications, you will use the embedded JDBC mode of operation.

RMI JDBC

DataCaster lets an application to connect to a Jdbc Driver running on a different VM or on a remote machine through RMI Driver. When using the JDBC RMI driver the usage is similar to that of local Jdbc driver except for the changes in the Driver class and the connection URL.

• Driver Class name : com.applibase.jdbc.client.DatabaseDriver
• Connection URL : "jdbc:rmi://[<server_address>[:<port_number>]]/<Database_Name>

Eample program:

In the following program tries to connect to a RMI server running on a remote machine with IP 192.168.0.53 on the default port ( 1099 ).

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;         

public class RMIJdbcDemo{

/* getConnection method returns a Connecion object to the Database specified by 'databaseName' on the machine 192.168.0.53 */

   public Connection getConnection(String databaseName,String userName, String password){

      try {
         Class.forName("com.appliase.jdbc.client.DatabaseDriver");
      } catch (java.lang.ClassNotFoundException e) {
         System.err.print("ClassNotFoundException: ");
         System.err.println(e.getMessage());
      }
      return DriverManager.getConnection("jdbc:rmi://192.168.0.53/"+databaseName,userName,password);
   }

   public createEmployeeTable(){
   {
      
      Connection con = getConnection("EmployeeDb","Librarian","fgheydh");
      con.createStatement().executeUpdate("Create table EmployeeTable( empId int , libraryId int primary key) ;
      /* Perform other necessary operations */
      ...

   }
}

Special Cases:

1. Server is Running on the default port: If the server is running on the default port ( 1099 ) then the port number need not be specified in the connection url, as demonstrated in the above example.

2. Server is bound to the loopback address ( 127.0.0.1 ) on the default port: In this case even the server_address can be droped as shown in the following url:

            "jdbc:rmi:EmployeeDb"

Note: For help on starting a RMI server on a machine please look at RMI Usage documentation.

For a list of what features are supported and what are not supported read Jdbc Limitations