OrionSupport, RMI Clients

RMI Clients

Written by Joseph Ottinger

Often, it is a lot more convenient to write an RMI client instead of a full-blown application client. Some of the advantages include:

Smaller support jar. For an RMI client, all you need is orionembedded.jar, nothing else.
No need to modify application on server side. An RMI client does not need to be explicitly registered with the j2ee application it connects to.
No need to write a special descriptor.

However, there are some disadvantages. For example, since there is no descriptor, you cannot specify ejb reference to other components. You will also have to look up EJB's in the global JNDI tree, rather than the java:comp/env namespace.

Below is a guide on Getting a sample RMI client working.

The first step is to ensure that we have a valid user to connect as. Edit your orion/config/principals.xml, and make sure you have a user specified that is not deactivated.

For the purposes of this example, we will assume that the username is admin, with the password 123.

Note that enabling the admin user is easiest, since the user already has RMI permissions. In order to grant rmi permissions to a particular group, add a permission element. Consult principals.xml for the syntax. The name of the permissions that RMI clients require are com.evermind.server.rmi.RMIPermission and rmi:login The first step is to create your jndi.properties file.

This will specify the initial context properties that should be used:

java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
# note that we specify 'default' below to connect to the default application
# in your client, you would replace that with the name of your application
# as it appears in server.xml
java.naming.provider.url=ormi://localhost/default
# the username and password to connect with
java.naming.security.principal=admin

java.naming.security.credentials=123

The next step is to write the client. In this example, we'll write a very simple client that connects to the server and looks up an object in the global JNDI tree:

import javax.naming.InitialContext;
import javax.naming.NamingException; 
public class RMITest
{
  public static void main(String[] args) throws NamingException
  {
    InitialContext context = new InitialContext();
    //look up the application administrator object and print it. 
    System.out.println(context.lookup("java:comp/Administrator"));
  }
}

Finally, it's time to put it all together. Compile RMITest, and ensure that jndi.properties and orionembedded.jar are both in your classpath.

Run it, and you should see something like this show up:

__com.evermind.server.administration.DefaultApplicationAdministrator@d1e765__

If you get some exception, then double check that you have orionembedded.jar and jndi.properties in your classpath. Also verify that the server is up and running, and has the user you specified listed in principals.xml.

Note also that in many cases, it's more convenient to not specify the properties in jndi.properties, but instead to create a Hashtable with those key/value pairs, and pass it in to the InitialContext constructor. This will enable you use a customised login prompt before creating the initial context.

You can read more about Orion's support for application clients at http://www.orionserver.com/docs/client-deployment.html