Using Activation: the Setup Program

Documentation Contents

This tutorial describes how to write a program that registers an activation descriptor for a remote object with the Java^TM Remote Method Invocation (Java RMI) activation system daemon (rmid) and then binds a stub for that remote object in an rmiregistry so that clients can look it up.

This tutorial has the following steps:

• Implement the Setup program
• Compile the source file
• Start rmid, rmiregistry, and the Setup program

• Setup.java - main Setup program
• setup.policy - security policy file for the Setup program
• rmid.policy - security policy file for rmid
• group.policy - security policy file for the activation group

Implement the Setup program

The Setup program, implemented by the class examples.activation.Setup, registers an activation descriptor with rmid to enable future activation of the object specified by that activation descriptor. This program does not create an instance of a remote object, but instead registers a remote object's stub with an rmiregistry so that clients can look it up. This Setup program must be run prior to running any of the clients described in the other activation tutorials.

The Setup program uses a number of system properties to customize the information that is registered with rmid and rmiregistry. The program also takes a single command-line argument that specifies the package-qualified name of the implementation class for the activatable remote object being registered. The Setup program is run as follows:

java -cp classpath \
     -Djava.security.policy=setup.policy        \
     -Djava.rmi.server.codebase=codebase         \
     -Dexamples.activation.setup.codebase=setupCodebase  \
     -Dexamples.activation.impl.codebase=implCodebase \
     -Dexamples.activation.name=name             \
     [-Dexamples.activation.file=filename]       \
     [-Dexamples.activation.policy=group.policy] \
     examples.activation.Setup implClass

where:

• classpath is a class path that includes the Setup program and the implementation classes
• setup.policy is the security policy file for the Setup program
• codebase is the location (URL) of the remote interface class(es)
• setupCodebase is the location (URL) the Setup program class (used in granting permissions to the Setup program in the setup.policy file)
• implCodebase is the location (URL) of the implementation class(es), used in the activation descriptor and also used in the group policy file as the codebase to grant permissions to
• name is the name for the object's stub to be bound in the registry
• file (optional) is the name of a file containing the object's persistent state which is registered as the data in the object's activation descriptor (no default)
• group.policy (optional) is the security policy file for the activation group (defaults to group.policy), and
• implClass is the fully-qualified name of the
implementation class.

The following is an example policy file for the Setup program:

  grant codeBase "${examples.activation.setup.codebase}" {

    // permissions to read system properties required by setup program
    permission java.util.PropertyPermission "examples.activation.impl.codebase","read";
    permission java.util.PropertyPermission "examples.activation.policy","read";
    permission java.util.PropertyPermission "examples.activation.file","read";
    permission java.util.PropertyPermission "examples.activation.name","read";

    // permission to connect to the activation system and the registry
    permission java.net.SocketPermission "*:1098-1099","connect";
};

The codebase to which permissions are granted is a URL specifying the location of the Setup program's implementation class(es). This URL is the value of the examples.activation.setup.codebase system property, which is defined when the Setup program is run. The Setup program needs the following permissions:

• java.util.PropertyPermission - to read various system properties required by the Setup program
• java.net.SocketPermission - to connect to the activation system (port 1098) to register an activation descriptor, and to connect to the registry (port 1099) to bind the activatable object's stub to a name

There are several steps to writing this Setup program:

• Construct an activation group descriptor
• Register the group descriptor
• Construct an activation descriptor
• Register the activation descriptor, and finally,
• Bind the remote object's stub in an rmiregistry

The Setup class has a static main method that performs all of the above steps. But before doing so, the main method sets a SecurityManager and obtains the single command line argument that specifies the package-qualified name of the implementation class for the activatable remote object. The rest of the steps are described below. See Setup.java for the full source code.

Construct an activation group descriptor

Before an application registers information about a particular activatable remote object, it first needs to register information about the activation group that the object will be contained in. An activation group is a container virtual machine (VM) for a set of activatable objects. Each activation group manages the execution of one or more activatable objects. An activation group descriptor contains information that the activation system needs to start an activation group's VM. An application can register an activation group descriptor with the activation system rmid to obtain an activation group ID to use for the activatable object, or the application can use an activation group ID obtained from a previous group registration.

The activation group descriptor, an instance of the class java.rmi.activation.ActivationGroupDesc, can be constructed in several ways. This tutorial uses the two parameter constructor ActivationGroupDesc(Properties,CommandEnvironment). The Properties map contains overrides for system properties in the activation group VM. For this tutorial, an activation group VM needs the following system properties defined:

• java.security.policy - the group's security policy file
• java.class.path - a dummy class path to prevent an activation group from loading implementation classes from the local class path
• examples.activation.impl.codebase - the location of the implementation classes, which the group's policy file uses to grant permissions to
• examples.activation.file - a file containg the object's persistent state

The java.security.policy property is specified by the examples.activation.policy system property, and defaults to the file named group.policy which will, in practice, be in the working directory where rmid is run. The java.class.path property is defined as no_classpath. The examples.activation.impl.codebase and examples.activation.file properties are specified by their current values (respectively), defined when the Setup program runs.

The group descriptor is constructed as follows:

String policy =
    System.getProperty("examples.activation.policy", "group.policy");
String implCodebase =
    System.getProperty("examples.activation.impl.codebase");
String filename =
    System.getProperty("examples.activation.file", "");

Properties props = new Properties();
props.put("java.security.policy", policy);
props.put("java.class.path", "no_classpath");
props.put("examples.activation.impl.codebase", implCodebase);
if (filename != null && !filename.equals("")) {
    props.put("examples.activation.file", filename);
}

ActivationGroupDesc groupDesc = new ActivationGroupDesc(props, null);

The following is an example group.policy file that grants the appropriate permissions for the activation examples:

grant codeBase "${examples.activation.impl.codebase}" {
    
    // permission to read and write object's file
    permission java.io.FilePermission "${examples.activation.file}","read,write";
    
    // permission to listen on an anonymous port
    permission java.net.SocketPermission "*:1024-","accept";
};

The codebase to which permissions are granted is a URL specifying the location of the activatable object's implementation classes. This URL is the value of the examples.activation.impl.codebase system property, which will be defined in the activation group's VM. An activatable object in the group needs two permissions:

• java.io.FilePermission - to read and write the file containing the activatable object's persistent state
• java.net.SocketPermission - to export the activatable object to accept connections an anonymous port

Register the group descriptor

Next, the Setup program must register the activation group descriptor with the activation system to obtain the group's ID, an instance of the class java.rmi.activation.ActivationGroupID. The class java.rmi.activation.ActivationGroup has a static method getSystem for obtaining the stub for the activation system. The Setup program calls the activation system's remote method registerGroup, passing the group descriptor created above, to register the activation group:

ActivationGroupID groupID = 
    ActivationGroup.getSystem().registerGroup(groupDesc);

Construct an activation descriptor

Once the activation group ID is obtained, the Setup program can register the activation descriptor. The activation descriptor has four basic pieces of information:

• the activation group ID for the group that the object will be contained in
• the implementation's class name
• the location (URL) specifying where the implementation's classes can be loaded from
• a marshalled object containing initialization information for the object

In this example, the activation group ID is the one obtained above; the implementation's class name is the class name, implClass, supplied as the command-line argument to the Setup program; the location (URL) is specified by the system property examples.activation.impl.codebase; and, the initialization data (which is optional) is a filename specified by the system property examples.activation.file.

The activation descriptor is constructed as follows:

MarshalledObject data = null;
if (filename != null && !filename.equals("")) {
    data = new MarshalledObject(filename);
}

ActivationDesc desc =
    new ActivationDesc(groupID, implClass, implCodebase, data);

Register the activation descriptor

Next, the Setup program must register the activation descriptor with the activation system. The class Activatable has a static convenience method, register, that registers an activation descriptor with the activation system and returns a stub for the activatable object specified by the descriptor.

Remote stub = Activatable.register(desc);

Note: The register method attempts to load a stub class for the implementation class in order to create a stub instance. If your activatable object needs to support pre-5.0 clients, you will need use rmic to pregenerate a stub class for the implementation class. If your activatable object does not need to support pre-5.0 clients, then there is no need to pregenerate a stub class for the implementation class. If the register method is unable to load a pregenerated stub class, it will use an instance of a dynamically-generated proxy class that implements all the interfaces of the implementation class. In the latter case the register method needs load the implementation class in order to determine the remote interfaces that the implementation class implements. So, the register method has a slight behavioral difference, depending on whether a pregenerated or dynamically-generated stub class is used.

Bind the remote object's stub in a rmiregistry

Finally, the remote object's stub is bound to a name in the registry running on the default port of 1099. The name is specified by the system property examples.activation.name.

String name = System.getProperty("examples.activation.name");
LocateRegistry.getRegistry().rebind(name, stub);

Compile the source file

The source file for this example can be compiled as follows:

javac -d setupDir Setup.java

where setupDir is the root destination directory to put the class files in.

Start rmid, rmiregistry, and the Setup program

To run this the Setup program, you will need to do the following:

• Start rmid
• Start rmiregistry
• Run the Setup program

Start rmid

To start rmid, run the rmid command on the server's host. This command should produce no output if it is run with a security policy file as specified below. For more information, see the tools documentation for rmid [Solaris, Windows].

For example, in the Solaris Operating System:

rmid -J-Djava.security.policy=rmid.policy \
     -J-Dexamples.activation.policy=group.policy &
	 

Or, on Windows platforms:

start rmid -J-Djava.security.policy=rmid.policy \
           -J-Dexamples.activation.policy=group.policy

where:

• rmid.policy is the security policy file for rmid
• group.policy is the group policy file, used in rmid's policy file

The security policy file for rmid grants permissions for rmid to execute specific commands and to use specific command-line options in starting activation group VMs. For example, a user might grant specific permissions to start an activation group VM with one or more system properties or other java command-line options. This example allows rmid to start activation group VMs that define the system properties java.security.policy, java.class.path, examples.activation.impl.codebase, and examples.activation.file. The following example security policy file grants permission to start an activation group VM with these specific properties defined:

grant { 
    // allow activation groups to use certain system properties
    permission com.sun.rmi.rmid.ExecOptionPermission "-Djava.security.policy=${examples.activation.policy}";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Djava.class.path=no_classpath";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Dexamples.activation.impl.codebase=*";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Dexamples.activation.file=*";
};

The first ExecOptionPermission permission grant restricts the java.security.policy system property to be the file specified by the system property examples.activation.policy, defined when rmid is run. The next permission grant allows a group to define the system property java.class.path as no_classpath, a dummy class path that prevents the group from having a valid class path. The next permission grant allows the group to define the system property examples.activation.impl.codebase to be any value. The final permission grant allows the examples.activation.file system property to be any value.

Start rmiregistry

To start the registry, run the rmiregistry command on the server's host. This command produces no output (when successful) and is typically run in the background. For more information, see the tools documentation for rmiregistry [Solaris, Windows].

For example, in the Solaris Operating System:

rmiregistry &

Or, on Windows platforms:

start rmiregistry 

By default, the registry runs on TCP port 1099. To start a registry on a different port, specify the port number from the command line. For example, to start the registry on port 2001 on a Windows platform:

start rmiregistry 2001

Note: Make sure that rmiregistry does not have any implementation classes in its class path to prevent it from loading any classes from its local class path.

If the registry will be running on a port other than 1099, you'll need to specify the port number in the calls to LocateRegistry.getRegistry in the Setup program, as well as any clients that access this registry. For example, if the registry is running on port 2001 in this example, the call to getRegistry would be:

Registry registry = LocateRegistry.getRegistry(2001);

Also note that if you use a registry port other than 1099, you will also need to modify the Setup and client program's policy files to grant permission to connect to the registry's port.

Run the Setup program

To start the Setup program, run the Setup class using the java command as follows:

java -cp setupDir:implDir \
     -Djava.security.policy=setup.policy        \
     -Djava.rmi.server.codebase=codebase         \
     -Dexamples.activation.setup.codebase=setupCodebase       \
     -Dexamples.activation.impl.codebase=implCodebase \
     -Dexamples.activation.name=name             \
     [-Dexamples.activation.file=file]       \
     [-Dexamples.activation.policy=group.policy] \
     examples.activation.Setup implClass

where:

• setupDir is the root directory for the Setup program's class
• implDir is the root directory for the implementation's classes
• setup.policy is the security policy file for the Setup program
• codebase is the location (URL) of the remote interface class(es)
• setupCodebase is the location (URL) the Setup program class (used in granting permissions to the Setup program in the setup.policy file)
• implCodebase is the location (URL) of the implementation class(es), used in the activation descriptor and also used in the group policy file as the codebase to grant permissions to
• name is the name for the object's stub to be bound in the registry
• file (optional) is the name of a file containing the object's persistent state which is registered as the data in the object's activation descriptor (no default)
• group.policy (optional) is the security policy file for the activation group (defaults to group.policy), and
• implClass is the fully-qualified name of the implementation class.

Note: If you use file URLs for any of the codebases listed above, make sure that each file URL has a trailing slash, or the codebase will be invalid.

The output from the Setup program should look like this:

Activation group descriptor registered.
Activation descriptor registered.
Stub bound in registry.

Copyright 2004 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: rmi-comments@java.sun.com