RmiJdbc Quick Start


Please email any bug reports, comments or suggestions to rmijdbc@objectweb.org


Architecture

RmiJdbc Server component:
On the server side, a daemon (RJJdbcServer) runs: it offers an RMI server object that implements the whole interface of a JDBC Driver object, and can give access to any JDBC Driver registered in the JDBC DriverManager on the server side.

RmiJdbc JDBC Driver:
The RmiJdbc JDBC Driver runs on the client side: the JDBC classes it implements contact the RmiJdbc Server to access databases.

Quick Start

Obtain the RmiJdbc.jar package: in the source distribution, it is in the dist/lib directory.

Then, you may directly start RmiJdbc as follows:

java -jar RmiJdbc.jar [-noreg] [-port regportnum] [-lp portnum] [-sm] [-ssl] [-passwd passwd] [driverList]

You may also start RmiJdbc like this:

Make your CLASSPATH variable point on the RmiJdbc.jar package
Start the RmiJdbc Server component:
java org.objectweb.rmijdbc.RJJdbcServer [-noreg] [-port regportnum] [-lp portnum] [-sm] [-ssl] [-passwd passwd] [driverList]

Options:

  • -noreg: means you launch the RmiJdbc server with an external rmiregistry
  • -port regportnum: specify the rmiregistry port (optional, useful if you launch rmiregistry on a port of your own)
  • -lp portnum: specify the listener port for remote objects (optional, useful if need to use a single port for remote objects - otherwise, dynamically allocated ports are used)
  • -sm: use the standard RMI SecurityManager (otherwise, a relaxed SecurityManager is used, equivalent to the RMI SecurityManager with AllPermissions set)
  • -ssl: use RmiJdbc on top of SSL. Read the related documentation if you need that option. The default implementation uses JSSE (standard since JDK 1.4, or separate download from javasoft since JDK 1.2.2).
  • -passwd: define an administrative password, used by org.objectweb.rmijdbc.RJAdmin for administrative operations (eg. server shutdown).
  • driverList: list of JDBC Driver classes available on your server (ex. org.enhydra.instantdb.jdbc.idbDriver). You can also declare your driver list in the jdbc.drivers System property (java -Djdbc.drivers=driverList org.objectweb.rmijdbc.RJJdbcServer)
    Note: the JDBC/ODBC bridge is registered by default, no need to add "sun.jdbc.odbc.JdbcOdbcDriver" to the driver list.

Then, a remote JDBC client can access your local database!
See the code example for more details.

The JDBC URL format used for RmiJdbc is:

 jdbc:rmi://<rmihostname[:port]>/<jdbc-url>

where:

  • rmihostname is the name or IP address of the host where the RmiJdbc server runs.
  • port is the port number for the RMI registry (default 1099, otherwise use the port number specified in the "-port" option on the server side).
  • jdbc-url is the local JDBC URL used on the server to reach the database (for example, a "jdbc:odbc:DSN" URL if the JDBC/ODBC bridge is used).

Administration

java org.objectweb.rmijdbc.RJAdmin operation url [user] [password]

operation is one of:

  • PING: check for database connection availability.
    java org.objectweb.rmijdbc.RJAdmin PING jdbc-url dbuser dbpassword
  • INFO: obtain JDBC driver info.
    java org.objectweb.rmijdbc.RJAdmin INFO jdbc-url
  • SHUTDOWN: shutdown RmiJdbc server.
    java org.objectweb.rmijdbc.RJAdmin SHUTDOWN jdbc-url admpassword
    admpassword is the administrative password defined when starting the RmiJdbc server (-passwd option). If no password was defined, shutdown is not allowed.
url is the full RmiJdbc URL (eg. jdbc:rmi://your-host/jdbc:odbc:YOUR-DSN).

Limitations

Some JDBC 2 classes are still missing: SQLData, SQLInput and SQLOutput are not yet implemented.
RmiJdbc in APPLETs may not work on some platforms, specially if you have old web browsers.
ResultSet's getObject() methods can only return serializable objects (due to RMI distribution).