RmiJdbc FAQ and Release Notes
=============================

The following FAQ results from many user's e-mails:

some tips can seem obvious, some are not!  - Have a look.
If it does not answer your question, send me an e-mail.

JDBC versions 1 and 2
---------------------

JDBC 2 is now supported - not yet fully concerning the alpha version.

To use RmiJdbc: RmiJdbc for JDBC 2 requires JDK 1.2+, while the old RmiJdbc for JDBC 1.0 can be used with any JDK 1.1.x or 1.2+.

To compile RmiJdbc: RmiJdbc for JDBC 2 requires JDK 1.2+, while the old RmiJdbc for JDBC 1.0 requires JDK 1.1.x.

Download & Unzip problems:
--------------------------

- I give the exact file size in my page: if the size on your platform is
  different, you had download problems.

- Download problems may be due to browser misconfiguration (maybe your
  browser tries to unzip, or performs character conversions, then corrupts
  the file)

- If your browser displays wierd text instead of downloading, click the
  link with the right button then select "Save link as..." menu.

- The zip format is gzip, not winzip (see http://www.gzip.org for tools)

- I added a non-compressed version of RmiJdbc, download it if you can't
  manage with the gzipped one.

- Side effect: if you're very unlucky, I'm just changing the version while
  you download... may cause problems, but very unlikely! retry after 10 minutes


jar problems:
-------------

- If you can't un-jar the file, see the "Download & Unzip problems" section
  (your file is corrupted)

- If jar can't create the RmiJdbc directory, you probably have unsufficient
  access rights (see your system administrator).


Binding problems with RMI:
--------------------------

- When you get trouble with RJJdbcServer at registry time, it does not mean
  RJJdbcServer has not been launched: you may have more than one version
  running if you restart it - check before, kill the process, or restart
  rmiregistry if you used the -noreg option.

- If you use the -noreg option, rmiregistry needs the CLASSPATH to all
  components: RmiJdbc, and the JDBC Driver you plan to use;
  If rmiregistry does not find RmiJdbc, you may get a
  java.lang.ClassNotFoundException; If it does not find the JDBC Driver,
  you will get a java.lang.SQLException saying "No suitable driver" .

- You may get security exceptions when using RMI through firewalls:
  the RMI port is 1099. I think Sun delivers tools for HTTP tunneling of RMI.

- On Windows, you may experience some RMI hang-ups at bind() time:
  There's a bug in the JIT compiler provided as part of the Java Performance
  Pack (JPP) for JDK 1.1.4 (don't know if this is fixed in later releases).
  To disable the JIT, type the following command at the DOS prompt:
  SET JAVA_COMPILER=

- You may need to disable the IP name resolution (by passing directly IP
  addresses instead of names in RMI URLs): for example, if you use DHCP...
  In that case, position the java.rmi.server.hostname property when starting
  the RmiJdbc server:
    java -Djava.rmi.server.hostname=<IP> org.objectweb.rmijdbc.RJJdbcServer <driverList>
  Where <IP> is your server IP address and <driverList> is your
  JDBC Drivers list.

- Security exception with JDK 1.2 and later:

  java.security.AccessControlException: access denied
  ...
  This is due to a wrong RMI security policy configuration.

  The following tips can help:
  Edit your java.policy file (it can be located in JAVA_HOME\lib\security
  or JAVA_HOME\jre\lib\security or JAVA_HOME\javasoft\jre\1.2\lib, it depends),
  and do the following:

  In the "grant" section concerning Property permissions, add the following
  permission to the permissions list:

    permission java.util.PropertyPermission "java.rmi.server.hostname", "read"; 

  If it is not sufficient (or there's no property permission list), add the
  following lines:
  // Standard extensions get all permissions by default
  grant {
    // Allow everything for now
    permission java.security.AllPermission;
  };

  To learn more about permissions, see the javasoft
  doc at http://java.sun.com/products/jdk/1.2/docs/guide/security/index.html
  (and the JDK 1.2 doc at http://java.sun.com/products/jdk/1.2/docs/index.html
  if necessary).
  If on Solaris, it seems that you can just provide a .java.policy file with
  that content in your home directory (reported by a user).


Problems when connecting the database:
--------------------------------------

- "No suitable driver" exception means the underlying JDBC driver is not
  registered in JDBC Driver Manager, at the RJJdbcServer level:
  Make sure there's only one instance of RJJdbcServer running.
  If you used the -noreg option, check that rmiregistry was launched with the
  CLASSPATH set to see the JDBC Driver.

- The URL passed to RmiJdbc is of the form:
  "jdbc:rmi:" + "//" <hostname>[:<port>] + "/" + <full-JDBC-url>
  hostname is the target RmiJdbc server host name (where the target
  RJJdbcServer RMI server runs), port is the RMI port (optional).
  JDBC/ODBC bridge example:
    "jdbc:rmi://yourHost/jdbc:odbc:<odbc-datasource-name>"
  InstantDB example: "jdbc:rmi://yourHost/jdbc:idb:sample.prp"

- Before trying client/server access with RmiJdbc, try a local java application
  on top of JDBC to connect the database; Then, make it client/server!

- If the connection takes a very long time, it's generally due to TCP/IP
  misconfiguration: the name resolution (DNS) is probably misconfigured.
  If the DNS is not necessary while testing, try to disable it; if the
  performance problem disappears, call your system administrator so she
  configures the DNS properly.
  Otherwise:
  If you're using WinNT try to add all your involved Computers in the
  host-file (UNIX-like) located in the
  \<winnt-directory>\system32\drivers\etc directory.

- There are bugs in some JDBC Drivers and/or on some Java VMs:
  if you still have exceptions like "No suitable driver"
  and can't understand anything, add some code in RJJdbcServer.java
  that does the following:
   - Open a connection to your local data source
   - Close it
  Example:
   String url = "jdbc:idb=sample.prp"; //URL to the local JDBC source
   Connection con = DriverManager.getConnection(url);
   con.close();


RmiJdbc and the JDBC/ODBC bridge:
---------------------------------

- JDBC/ODBC URLs are of the form "jdbc:odbc:<odbc-datasource-name>", then
  the URL for RmiJdbc is
    "jdbc:rmi://<hostName>[:<port>]/jdbc:odbc:<odbc-datasource-name>".

- Make sure ODBC is well configured, and the datasource valid (the best is
  using JDBC/ODBC sample programs to make local tests in a java application,
  before trying RmiJdbc client/server).
  ODBC System DSNs seem easier to use for test purposes, because there is
  less security.


Garbage collection problems
---------------------------

- Sometimes, connections may not be properly closed when a client crashes.
  In that case, you may set the java.rmi.dgc.leaseValue property at server
  startup (a value in milliseconds, default is 600000 = 10 minutes).
  This value determines how long RMI will keep an unused server object, before
  garbage collection.
  Example (1 minute):
  java -Djava.rmi.dgc.leaseValue=60000 org.objectweb.rmijdbc.RJJdbcServer sun.jdbc.odbc.JdbcOdbcDriver
  Remember RMI clients send "renew" calls to the server when this timeout is
  halfway expired (so better don't go under 1 minute, or you will use a high
  amount of network bandwidth to just keep your objects alive). 


RmiJdbc in applets:
-------------------

- If you get "class not found" exceptions in the browser, copy RmiJdbc.jar
  in your applet code base directory; then, either:
  - un-jar RmiJdbc.jar (jar xvf RmiJdbc.jar)
  or
  - use an archive directive in the APPLET tag:
  <applet code="YourApplet.class" archive="RmiJdbc.jar">

- You may get security exceptions due to name resolution problems: sometimes
  the server host name returned by RMI does not match the applet's origin
  host name; then:
   - Make sure you use getCodeBase().getHost() in the applet to retrieve the
   server host name.
   - If so, print out what getCodeBase().getHost() returns, and use this value
   as a value for the java.rmi.server.hostname when starting the RmiJdbc
   server:
    java -Djava.rmi.server.hostname=<HostName> org.objectweb.rmijdbc.RJJdbcServer <driverList>
    Where <HostName> is what getCodeBase().getHost() returns
    and <driverList> is your JDBC Drivers list.
 
- RMI support in web browsers:

HotJava: You should have no problem.

Netscape:

- RMI is supported by Netscape 4 (on Windows, bugs on Unix will be fixed soon)
- See http://developer.netscape.com/software/jdk/download.html if you have
  problems

Internet Explorer:

- Internet Explorer version 4.71.1712.6 and later should support RMI (I don't
  know for earlier versions), but you must download rmi.zip (anonymous ftp) at
  ftp://ftp.microsoft.com/developr/msdn/unsup-ed, and un-pack it in
  \windows\java\classes.
  As you see, M$ support even what they don't support ;)
  If this URL changes, use the search at www.microsoft.com to lookup rmi.zip.

- Some users seem to have succeeded without rmi.zip, but with the JDK
  installed on the client platform and the CLASSPATH set.


RmiJdbc as a NT Service
-----------------------

WARNING:
The information provided here comes from RmiJdbc users, I didn't try myself
to run RmiJdbc as an NT service, and will provide no support on that subject.

- You can try do download a contributed package to run the
  RmiJdbc Server as a NT Service, thanks to Arnaud Treps who contributed it:
  http://www.objectweb.org/rmijdbc/contrib/RmiJdbcSrvc0-2.zip

- Running RmiJdbc as an NT service (using BMobile 'jservice')

Some users reported the possibility to use jservice, a tool from BMobile:
see http://www.bmobile.com/jservice/


- Running RmiJdbc as an NT service (using SRVANY.exe)

You need the SRVANY.EXE program, that comes with the NT resource kit.

First you install a new service.  Example-
 INSTSRV RmiJdbc c:\tools\srvany.exe
(You must of course modify the pathnames to match your PC).

Next you must modify a few registry settings with regedt32.exe:
  Create the key
   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RmiJdbc\Parameters
  
  Under that key create a value named 'Application' with the type
  REG_SZ and a value similar to c:\bin\run_rmijdbc.cmd

Then you must create the run_rmijdbc.cmd with the following contents-
(You must of course modify the pathnames to match your PC).

   @echo off
   set CLASSPATH=c:\jdk1.1.5\lib\classes.zip;c:\LocalJava;c:\LocalJava\RmiJdbc.jar 
   c:\jdk1.1.5\bin\java org.objectweb.rmijdbc.RJJdbcServer sun.jdbc.odbc.JdbcOdbcDriver > c:\temp\rmijdbc_server.log

Finally you need to open of the control panel, go into services and
select 'automatic' startup for the new service.

Problems when compiling RmiJdbc
-------------------------------
 
You may encounter error message related to "javax.net" classes (when compiling
RmiJdbc 2+ using a JDK version < 1.4).
This means you have to install JSSE on your system:
 RmiJdbc uses JSSE (Java Secure Socket Extensions) for SSL support.
 You will have to download and install Sun's JSSE in order to compile RmiJdbc.
 Download location: http://java.sun.com/products/jsse
 Then, to install JSSE:
 - Unzip the JSSE distribution.
 - Copy jsse.jar, jcert.jar and jnet.jar from JSSE's lib/ subdirectory into
  your JAVA_HOME/jre/lib/ext directory.

Miscellaneous
-------------

When using JDK 1.3 on Windows, RmiJdbc sometimes seems not to work at all:
try to grant all permissions in your java.policy file, it should solve
the problem (although it does not seem to be security-related at all !)
Here's what you should add - at least to test:
  grant {
    // Allow everything for now
    permission java.security.AllPermission;
  };

A newbie question I sometimes heard: "I start the RmiJdbc server in a DOS
windows, and it runs forever and never returns... what should I do ?"
The answer is: Do nothing, it's normal, a server runs forever.
(of course, it happens on Unix too, but Unix users never ask that question ;)

Symantec JVM users (VisualCafe):
There's a CLASSPATH variable in a sc.ini file somewhere (I think it's in
some VisualCafedbDE\bin directory), you may have to update it to find RmiJdbc
classes.