Prior to the release of the JDK1.2, an instance of a class that did not extend from UnicastRemoteObject could be accessed from a server program that (1) created an instance of the remote object, and (2) ran all the time. This functionality was provided by creating a constructor which exported the object by calling the static method UnicastRemoteObject.exportObject. The exportObject method accepts as an argument an object that implements an interface that extends from java.rmi.Remote.

Now with the introduction of the class java.rmi.activation.Activatable and the RMI daemon, rmid, programs can be written to register information about remote object implementations that should be created and execute "on demand", rather than running all the time. The RMI daemon, rmid, provides a JVM from which other JVM instances may be spawned. As in the UnicastRemoteObject.exportObject case, activatable objects may be exported using a static method, Activatable.exportObject, and these objects must implement a remote interface.

Note:  For the remainder of this tutorial, the terms "activatable object implementation", "activatable object," and "implementation" may be used interchangeably to refer to  the class, examples.activation.MyClass, which implements a remote interface and is activatable.

This tutorial is organized as follows:

• The steps to create a remote interface
• The steps to modify the implementation class
• The steps to create the setup class
• The steps to compile and run the example code

• Client3.java, the class which will invoke a method on an activatable object
• AnotherRemoteInterface.java, the interface that extends java.rmi.Remote, implemented by:
• MyClass.java, the class which is being modified to be activatable
• Setup3.java, the class which registers information about the activatable

class with the registry and the RMI daemon

For all of the source code used in the activation tutorials, you may choose from these formats:

• activation.zip
• activation.tar
• activation.tar.Z

Creating the remote interface

Create an interface that describes each of the methods that you would like to call remotely. For this example, the remote interface will be examples.activation.AnotherRemoteInterface.  There are three steps to create a remote interface.

1. Make the appropriate imports in the interface
2. Extend java.rmi.Remote
3. Declare each of the methods that may be called remotely

Step 1:
Make the appropriate imports in your interface
 
import java.rmi.*;

Step 2:
Extend java.rmi.Remote

public interface AnotherRemoteInterface extends Remote {
 

Step 3:
Declare each of the methods that may be called remotely

public String calltheServer(String s) throws RemoteException;

---

Creating the implementation class

For this example, the implementation class will be examples.activation.MyClass. There are three steps to migrate a class which does not extend Activatable or UnicastRemoteObject to become activatable:
 

1. Make the appropriate imports in the implementation class
2. Modify the class declaration so that the class now implements

an interface that extends from java.rmi.Remote
3. Declare a two-argument constructor in the implementation class

 
Step 1:
Make the appropriate imports in the implementation class

import java.rmi.*;
import java.rmi.activation.*;

Step 2:
Modify the class declaration so that the class implements
an interface that extends from java.rmi.Remote

 public class MyClass implements examples.activation.AnotherRemoteInterface {

 
Step 3:
Add a new two-argument constructor to the implementation class

public MyClass(ActivationID id, MarshalledObject data) throws RemoteException {
     // Register the object with the activation system
     // then export it on an anonymous port
     Activatable.exportObject(this, id, 0);
}
 

---

Creating the "setup" class

The job of the "setup" class is to create all the information necessary for the activatable class, without necessarily creating an instance of the remote object. For this example, the setup class will be examples.activation.Setup3.

The setup class passes information about the activatable class to rmid, registers a remote reference (an instance of the activatable class's stub class) and an identifier (name) with the rmiregistry, and then the setup class may exit.  There are six steps to create a setup class:
 

1. Make the appropriate imports
2. Install a SecurityManager
3. Create an ActivationDesc instance
4. Declare an instance of your remote interface and register with rmid
5. Bind the stub to a name in the rmiregistry
6. Quit the setup application

Step 1:
Make the appropriate imports in the setup class
 

import java.rmi.*;
import java.rmi.activation.*;
import java.util.Properties;

Step 2:
Install a SecurityManager
 

System.setSecurityManager(new RMISecurityManager());

Step 3:
Create an ActivationDesc  instance

In the setup application,the job of the activation descriptor is to provide all the information that rmid will require to create a new instance of the implementation class.

Note: In order to run this code on your system, you'll need to change the file URL location to be the location of the directory on your system, where you've installed the example source code.

// The "location" URL specifies where the class definition
// will come from when this object is requested (activated).
// Don't forget the trailing slash at the end of the URL
// or your classes won't be found
//
String location = "file:/home/rmi_tutorial/activation/";

// Create the rest of the parameters that will be passed to
// the ActivationDesc constructor
//
MarshalledObject data = null;

// The second argument to the ActivationDesc constructor will be used
// to uniquely identify this class; it's location is relative to the
// URL-formatted String, location.
//
ActivationDesc desc = new ActivationDesc
    ("examples.activation.MyClass", location, data);
 

Step 4:
Declare an instance of your remote interface and register the activation descriptor with  rmid

AnotherRemoteInterface ari =
       (AnotherRemoteInterface)Activatable.register(desc);
System.out.println("Got the stub for MyClass");

Step 5:
Bind the stub, that was returned by the Activatable.register method, to a name in the rmiregistry

Naming.rebind("MyClass", ari);
System.out.println("Exported MyClass");

Step 6:
Quit the setup application

System.exit(0);
 

---

Compile and run the code

There are six steps to compile and run the code:
 

1. Compile the remote interface, implementation, client and setup classes
2. Run rmic on the implementation class
3. Start the rmiregistry
4. Start the activation daemon, rmid
5. Run the setup program
6. Run the client

Step 1:
Compile the remote interface, implementation, client and setup classes

% javac -d . AnotherRemoteInterface.java
% javac -d . MyClass.java
% javac -d . Client3.java
% javac -d . Setup3.java

Step 2:
Run rmic on the implementation class

% rmic -d . examples.activation.MyClass

Step 3:
Start the rmiregistry
 
In order to run this code on your system, you'll need to change the location of the policy file to be the location of the directory on your system, where you've installed the example source code.

% rmiregistry -J-Djava.security.policy=/home/rmi_tutorial/activation/policy &

Note: In this example, for simplicity,  we will use a policy file that gives global permission to anyone from anywhere. Do not use this policy file in a production environment. For more information on how to properly open up permissions using a java.security.policy file, please refer to to the following documents:
 

http://java.sun.com/products/jdk/1.2/docs/guide/security/PolicyFiles.html
http://java.sun.com/products/jdk/1.2/docs/guide/security/permissions.html
 
Note:  Before you start the rmiregistry, you must make sure that the shell or window in which you will run the registry, either has no CLASSPATH set or has a CLASSPATH that does not include the path to any classes that you want downloaded to your client, including the stubs for your remote object implementation classes.

If you start the rmiregistry, and it can find your stub classes in its CLASSPATH, it will ignore the server's java.rmi.server.codebase property, and as a result, your client(s) will not be able to download the stub code for your remote object.

Step 4:
Start the activation daemon, rmid

% rmid &

Step 5:
Run the setup program
 

Run the setup, setting the codebase property to be the location of the implementation stubs. There are four things that need to go on the same command line:
 
1. The "java" command
2. A property name=value pair that specifies the location of the security policy file
3. A property to specify where the stub code lives (no spaces from the "-D" all the way though the last "/")
4. The fully-qualified package name of the setup program.

There should be one space just after the word "java", one between the two properties, and a third one just before the word "examples" (which is very hard to see when you view this as text, in a browser, or on paper).

% java -Djava.security.policy=/home/rmi_tutorial/activation/policy -Djava.rmi.server.codebase=file:/home/rmi-tutorial/activation/ examples.activation.Setup3

The codebase property will be resolved to a URL, so it must have the form of "http://aHost/somesource/" or "file:/myDirectory/location/" or, due to the requirements of some operating systems, "file:///myDirectory/location/" (three slashes after the "file:").
 
Please note that each of these sample URL strings has a trailing "/". The trailing slash is a requirement for the URL set by the java.rmi.server.codebase property, so the implementation can resolve (find) your class definition(s) properly.
 
If you forget the trailing slash on the property, or if the class files can't be located at the source (they aren't really being made available for download) or if you misspell the property name, you'll get thrown a java.lang.ClassNotFoundException. This exception will be thrown when you try to bind your remote object to the rmiregistry, or when the first client attempts to access that object's stub. If the latter case occurs, you have another problem as well because the rmiregistry was finding the stubs in its CLASSPATH.

The server output should look like this:
 

Got the stub for MyClass
Exported MyClass
 
 Step 6:
Run the client

The argument to the client program is the hostname of the implementation server, in this case, "vector".

% java examples.activation.Client3 vector
 
The client output should look like this:
 

Got a remote reference to the class MyClass
Called the remote method
Result: Watson are you there?  I'm here!
 

---

An Alternate Approach

An alternative approach to what we just went through is to create an "adapter" class that  implements the remote interface, gets registered with rmid and the registry by the setup program, and which then creates the object instance and forwards the remote method to that instance. The benefit to this approach is that you don't have to make a change to the original non-remote class.

So, let's assume that the original, non-remote class, looks like this:

package examples.activation;

public class MyNonRemoteClass {
 
    private String result = null;
 
    // Here's the original class, which concatenates two strings
    //
    public String calltheServer(String takeThis) {

        result = takeThis + "I'm here!";
        return result;
    }

}
 

We write the same interface, examples.activation.AnotherRemoteInterface, to describe the methods we'd like to call remotely:
 
package examples.activation;

import java.rmi.*;

public interface AnotherRemoteInterface extends Remote {
 
    public String calltheServer(String s) throws RemoteException;

}
 
 

But rather than editing MyNonRemoteClass.java, which we may not always have the source code to do anyway, we'll create a new class examples.activation.MyNonRemoteClassAdapter, which (like an event adapter) implements the specified interface, and then takes appropriate action. What's new in MyNonRemoteClassAdapter from what we did earlier, is that it creates an instance of MyNonRemoteClass in it's constructor and it calls the MyNonRemoteClass.calltheServer method.
 
package examples.activation;

import java.rmi.*;
import java.rmi.activation.*;

public class MyNonRemoteClassAdapter implements
    examples.activation.AnotherRemoteInterface
{
    private String result = null;
    private MyNonRemoteClass mnrc;

    // The constructor for activation and export; this constructor is
    // called by the method ActivationInstantiator.newInstance during
    // activation, to construct the object.
    //
    public MyNonRemoteClassAdapter(ActivationID id,
        MarshalledObject data) throws RemoteException
    {
        // Register the object with the activation system
        // then export it on an anonymous port
        //
        Activatable.exportObject(this, id, 0);

        // Create an instance of the class MyNonRemoteClass
        //
        mnrc = new MyNonRemoteClass();
    }

    // Define the method declared in AnotherRemoteInterface
    // to accept a String, modify it, and return it to the client
    //
    public String calltheServer(String takeThis)
        throws RemoteException
    {
        // Rather than modify the String here, forward
        // it on to the non-remote object impleemntation
        //
        result = mnrc.calltheServer(takeThis);
        return result;
    }

}
 
 

Now the class we'll run rmic on and the class referenced by the setup program will be the adapter class. The  setup program examples.activation.Setup3alt looks like this now:
 
package examples.activation;

import java.rmi.*;
import java.rmi.activation.*;
import java.util.Properties;

public class Setup3alt {

    // This class registers information about the MyClass
    // class with rmid and the rmiregistry
    //
    public static void main(String[] args) throws Exception {
 
        System.setSecurityManager(new RMISecurityManager());
 
        AnotherRemoteInterface ari;

        // Don't forget the trailing slash at the end of the URL
        // or your classes won't be found
        //

  String location = "file:/home/rmi_tutorial/activation/";

  // Create the rest of the parameters that will be passed to
  // the ActivationDesc constructor
  //
  MarshalledObject data = null;

  // The second argument to the ActivationDesc constructor 
  // will be used to uniquely identify this class; it's 
  // location is relative to theURL-formatted String, location.
  //
  ActivationDesc desc = new ActivationDesc
      ("examples.activation.MyNonRemoteClassAdapter",
      location, data);
 

        ari = (AnotherRemoteInterface)Activatable.register(desc);
        System.out.println("Got the stub for MyNonRemoteClassAdapter");

        // Bind the stub to a name in the registry running on 1099
        //
        Naming.rebind("MyNonRemoteClassAdapter", ari);
        System.out.println("Exported MyNonRemoteClassAdapter");

        System.exit(0);
    }

}

 

---

Copyright © 1998 Sun Microsystems, Inc. All Rights Reserved.