Connecting to remote Databases through RMI

DataCaster supports an embedded mode and a standalone mode of operation. When connecting to a standalone database via JDBC or the User API, RMI is used to connect to the standalone DataCaster client or server instance.

DataCaster lets users to connect to remote database through the RMI client API or through Jdbc connection. To let users connect to your database you need to start the RMI server on your machine, see the section on Starting RMI Server. Once the user gets a Database object( while using Client API ) or the Connection object( in case of using JDBC ) to the remote database, he can use it the same way he uses the embedded database. Since RMI objects communicate with the server through remote method invocation, there are a few limitations to its usage. Please read RMI Limitations section for more information.

Starting RMI Server:

RMI server once started listens to all the incoming requests on the designated port ( 1099 by default ), and allows only clients who have provided proper Usename and password for the requested database. There are two ways of starting the RMI server on any machine.

As a Stand alone application:

To start the RMI server as a standalone application you need to run the DbServerImpl class as below ( assuming that you have the datacaster or datacore jar in the classpath ).

java com.applibase.rmi.server.DbServerImpl

This starts a server bound to the first network interface which has an non-loopback ip ( if none present will use the loopback adress itself ) and starts listening to the incoming connection requests on the default port ( 1099 ).

Special Cases:

1. In case you want to start the server bound to any particular network interface ( say 192.168.xxx.yyy ) then you need to start the server as follow

java com.applibase.rmi.server.DbServerImpl -h 192.168.xxx.yyy

This starts a RMI server and binds it to the default port on the interface with the ip 192.168.xxx.yyy. ( this workseven for hostnames. Example: java com.applibase.rmi.server.DbServerImpl -h www.example.com )

Note: To start the server on a loopback address you need to specifically give the address. Ex: java com.applibase.rmi.server.DbServerImpl -h 127.0.0.1 unless that is the only ip address available.

b. In case you want to start the server bound to any particular port on an network interface.

java com.applibase.rmi.server.DbServerImpl -h www.example.com -p 2000

This will start a server bound to port 2000 on the network interface with the address www.example.com .

Note

Since the server has been started as a stand alone application only way to stop the server is to kill the application itself.

Start the RMI server within an application:

You can use the startServer static method in DbServerImpl class to start a RMI server on any required port and address. This method returns a DbServer object that can be used to stop the server whenever required within the application. Example:

                //Start a RMI Server on the defautl port and address.
               com.applibase.db.rmi.DbServer rmiServerInstance = com.applibase.rmi.server.DbServerImpl.startServer(null,-1);               ....
               ....
               // Stop the server so that no other connection is accepted.
               rmiServerInstance.stopServer();

Special cases:

1. To start the server that is bound to a particular port on a particular interface you need to pass the network interface address ( or host name ) and the port number as arguments to the startServer method: Example: //Start a RMI Server on interface 192.168.0.5 that listens to connections on port 3001 com.applibase.db.rmi.DbServer rmiServerInstance = com.applibase.rmi.server.DbServerImpl.startServer("192.168.0.5",3001); ... Note: Passing NULL or empty string for HostAdress parameter makes the server start on the default address which is the same as the address of the first network interface that has a non-loopback address ( if none present then 100pback adress - 127.0.0.1 is used. ) .Similarly passing -1 as an argument for startServer method makes the server to be bound to the default port which is 1099.

Connecting to the server

Connecting to RMI Server through the API:

When using the datacaster API we connect to any database by getting a com.applibase.db.user.DatabaseImpl object instance, similarly to connect to a remote database instance that we can use a com.applibase.db.rmi.client.DatabaseImpl object instance. Once we get the database Instance the rest of the usage is the same for both RMI and local database. Example:

          Database db = new com.applibase.db.rmi.client.DatabaseImpl( "coretest","username","password");
          DbStatement stmt.executeUpdate();
          ...
           db.disconnect();

Connecting to RMI Server through JDBC :

When using JDBC for connecting to the database we use the connection object got from the com.applibase.jdbc.DriverManager, similarly to use the RMI client JDBC driver we need to use the connection object got from com.applibase.jdbc.client.DriverManager. The connection url should be of the form: jdbc:rmi://[[:]]/. For more detailed information read Jdbc Guide.Example:

        try{
               Class.forName("com.appliase.jdbc.client.DatabaseDriver");
       } catch (java.lang.ClassNotFoundException e) {
               System.err.print("ClassNotFoundException: ");
              System.err.println(e.getMessage());
       }
       Connection con = DriverManager.getConnection("jdbc:rmi://192.168.0.53/"+databaseName,userName,password); 
       stmt = db.createStatement("create table EmployeeTab (empId int, empName varchar(256), deptId int)");