Chapter 23: Activation

Many of the examples in earlier chapters use RMI/Jeri proxies for services. These services live within a server whose principal task is to keep the service alive and registered with lookup services. If the server fails to renew leases then lookup services will eventually discard the proxy; if the server fails to keep itself and its service alive then the service will not be available when a client wants to use it.

This results in a server and a service which most of the time will be idle, probably swapped out to disk but still using virtual memory. Java memory requirements on the server side can be enormous From JDK 1.2, there is an extension to RMI called activation which allows an idle object to be "dormant", and be brought to life when needed. In this way, it does not occupy virtual memory while idle. Of course, another process needs to be alive to restore such objects, and RMI supplies a daemon rmid (in Jini 1.2) and phoenix (in Jini 2.0) to manage this. In effect, rmid/phoenix acts as another virtual memory manager as it stores information about dormant Java objects in its own files and restores them from there as needed.

There are serious limitations to rmid and phoenix: they are Java program themselves and when running also uses enormous amounts of memory! So it only makes sense to use this technique when you expect to be running a number of largely idle services on the same machine. When a service is brought to life, or activated, a new JVM may be started to run the object. This again increases memory use.

If memory use was the only concern, then there are a variety of other systems such as echidna which run multiple applications within a single JVM. These may be adequate to solve memory issues. However, RMI Activation is also designed to work with distributed objects, and allows JVM's to hold remote references to objects which are no longer active. Instead of throwing a remote exception on trying to access these objects, the Activation system tries to resurrect the object using rmid or phoenix to give a valid (and new) reference. Of course, if it fails to do this, it will throw an exception anyway.

The standard RMI activation system is supported by Jini 2.0, in the same way as it supports JRMP. But with the advent of Jeri, Jini 2.0 has a new version of activation with a new activation server, phoenix.

Making an object into an activable object requires registering the object with the activation system by exporting it, and by using a special two-argument constructor which will be called when the object needs to be reconstructed. The constructor looks like:

public ActivatableImpl(ActivationID id, MarshalledObject data)
    throws RemoteException {
    ...
}
	  

There is an important conceptual change from non-activatable services. In a non-activatable service, the server is able to create the service. In an activation system, the original server could have terminated, and will not be available to start the service. Instead, the activation server is responsible for that. But the service still has to be exported, and it can't rely on the activation server to do that (for example, it would have no knowledge of the protocol such as Jeri/JRMP/IIOP). So the service has to export itself. That is, within the constructor the service must find an exporter and export itself. This is a change from "standard" activation as used in Jini 1.2: there, many things were hidden from the programmer and it was not neccessary to pay attention to this.

That in turn raises another problem: in a non-activatable service, the server creates the service, gets a proxy by exporting the service and then does things like register the proxy with lookup services. But if the export operation is buried within the service constructor, then a server cannot readily get access to it. This is the role of the ProxyAccessor interface: it supplies a method that a server can call on the service to give the proxy. Unless the service can do everything itself, it will usually need to implement this interface. (An exception to this occurs when the service is its own proxy: it just needs to be Serialisable in that case.)

With these in place, the file classifier becomes

	    
package activation;

import net.jini.export.*; 
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.BasicILFactory;
import net.jini.jeri.tcp.TcpServerEndpoint;
import net.jini.activation.ActivationExporter;

import net.jini.jrmp.JrmpExporter;

import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;
import net.jini.export.ProxyAccessor;

import common.MIMEType;
import common.FileClassifier;
import rmi.RemoteFileClassifier;
import java.rmi.Remote;

/**
 * FileClassifierImpl.java
 */

public class FileClassifierImpl implements RemoteFileClassifier,
					   ProxyAccessor {

    private Remote proxy;

    public MIMEType getMIMEType(String fileName) 
	throws java.rmi.RemoteException {
        if (fileName.endsWith(".gif")) {
            return new MIMEType("image", "gif");
        } else if (fileName.endsWith(".jpeg")) {
            return new MIMEType("image", "jpeg");
        } else if (fileName.endsWith(".mpg")) {
            return new MIMEType("video", "mpeg");
        } else if (fileName.endsWith(".txt")) {
            return new MIMEType("text", "plain");
        } else if (fileName.endsWith(".html")) {
            return new MIMEType("text", "html");
        } else
            // fill in lots of other types,
            // but eventually give up and
            return new MIMEType(null, null);
    }


    public FileClassifierImpl(ActivationID activationID, MarshalledObject data)  
	throws java.rmi.RemoteException {

	Exporter exporter = 
	    new ActivationExporter(activationID,
			 new BasicJeriExporter(TcpServerEndpoint.getInstance(0),
					       new BasicILFactory(),
					       false, true));
	    
	proxy = (Remote) exporter.export(this);
    }

    // Implementation for ProxyAccessor
    public Object getProxy() {
	return proxy;
    }
} // FileClassifierImpl

	  

The server doesn't actually start the service - that is the task of a process like phoenix. What the server has to do is setup the parameters for the service so that phoenix will know how to handle it. These may include

1. Which activation group the service will belong to

2. The security policy to run services in a particular activation group

3. The classpath for phoenix to run the service in a new Java virtual machine. Note that this classpath cannot be one that is relative to the server, since it will be used by phoenix.

4. The codebase for the client to find the service (needed if the service registers itself with lookup services)

String[] options = {"-classpath", 
	            "activation.FileClassifierServer.jar"};
CommandEnvironment commEnv =
	            new CommandEnvironment(null, options);
	  

String[] options = {"-classpath", 
	            "activation.FileClassifierServer.jar"};
ActivationGroupDesc.CommandEnvironment commEnv =
	    new CommandEnvironment(null, options);
Properties props = new Properties();
props.put("java.security.policy",
	  SECURITY_POLICY_FILE);
props.put("java.rmi.server.codebase", 
	  "http://192.168.1.13/classes/activation.FileClassifierServer-dl.jar");
ActivationGroupDesc group = new ActivationGroupDesc(props, commEnv);

The next steps are to register the group and get a group ID from that. Then an activation description for the service is constructed. This includes the group ID and the name of the service's class file. (Two other parameters are discussed later.) This service can then be registered with phoenix. At this point, the service is with phoenix, but has not been initialised. So its constructor has not been called, and there is no proxy for it. This means it cannot yet be registered with a lookup service and cannot yet be found by any client. How then can we force it to be constructed? At this point the server has an activation ID for the service from the registration. It uses this to ask phoenix to activate the service by the activate() method. The code for this looks like

ActivationGroupDesc group = new ActivationGroupDesc(props, commEnv);
ActivationGroupID groupID  = actSys.registerGroup(group);

ActivationGroup.createGroup(groupID, group, 0);
String codebase = "...";
MarshalledObject data = null;
ActivationDesc desc = null;
desc = new ActivationDesc(groupID,
                          "activation.FileClassifierImpl",
                           codebase, data, true);
ActivationID aid =  actSys.registerObject(desc);
Remote stub = (Remote) aid.activate(true);
	

The service and the server must be compiled as usual. Nonactivatable services just require classes for the client and for the server. For activatable services it is more complex: classes are required for the client, for the startup server and for phoenix

1. The classes that are required by the client must be copied to an http server. In this case, it is only the class file rmi/RemoteFileClassifier.class. That is, if a protocol such as Jeri is used with stub generation at runtime. If JRMP was used, the rmic compiler would need to be run on activation/FileClassifierImpl.class and the resultant stub would also need to be copied to the http server

2. The classes needed by the startup server are the file classifier server and the classes it needs. This gets a bit tricky. The server doesn't actually create the service at any time, so it doesn't need the class file for FileClassifierImpl. But when it activates the service, phoenix will create the service and return a proxy for it. This proxy will implement RemoteFileClassifier. So the server will need the class files to support a RemoteFileClassifier even though it doesn't explicitly create one. The files could be either in the server's classpath, or in its codebase. This server uses the codebase as information in the proxy when it registers the service with a lookup service, and so we wouldn't want to put extra stuff in there for downloading to a client. Instead, the class files may be better off in the server's classpath (Hmmm, I'm not completely happy with that - I wonder if there is a better way...)

   1. common/MIMEType.class

   2. common/FileClassifier.class

   3. rmi/RemoteFileClassifier.class

   4. activation/FileClassifierServer.class

3. Finally, the classes needed by phoenix are FileClassifierImpl and its dependencies, but not the startup server

   1. common/MIMEType.class

   2. common/FileClassifier.class

   3. rmi/RemoteFileClassifier.class

   4. activation/FileClassifierImpl.class

Before starting the service provider, a phoenix process must be set running on the same machine as the service provider. An HTTP server must be running on a machine as specified by the codebase property on the service. The service provider can then be started. This will register the service with phoenix, and will copy a proxy object up to any lookup services that are found. The server can then terminate (as mentioned earlier, this will cause the service's lease to expire, but techniques to handle this are described later).

In summary, there are typically three processes involved in getting an activatable service running

1. The service provider, which specifies information about the service to phoenix

2. phoenix, which must be running on the same machine as the service provider, and must be started before the service provider. Igt creates the service on demand

3. An HTTP server, which can be on a different machine, and is pointed to by the codebase

While the service remains registered with lookup services, clients can download its proxy. The service will be created on demand by phoenix. You only need to run the server once, since phoenix keeps information about the service in it own log files.

An Ant file to build, deploy and run the service (but not phoenix) is activation.FileClassifierServer.xml

The type of service discussed above are ``lazy'' services, activated on demand when their methods are called. This reduces memory use, at the expense of starting up a new JVM when required. Some services need to be continuously alive, but can still benefit from the log mechanism of phoenix. If phoenix crashes and is restarted, or the machine is rebooted and phoenix restarts, then it is able to use its log files to restart any ``active'' services registered with it, as well as restore ``lazy'' services on demand. This can avoid messing around with boot configuration files, by making services non-lazy and just ensuring that phoenix is started on reboot.

The service implementations shown in this chapter so far have hard-coded the protocol - Jeri. In general this is not a good idea, as it should be left to a runtime configuration to specify this. So the code to find an exporter should be handled by looking in a configuration, as we did in the Configuration chapter.

The startup server is the one that will see the configuration file, typically a filename as a command line parameter. Previously, for non-activable services the server is able to extract the exporter directly from the configuration and use it to export the service. But as we have seen, it is now the responsibility of the service itself to define and use an exporter. The problem is how to get the command line parameters from the startup server into the service's constructor.

This can be solved by using the marshalled data discussed in the last section: but instead of using it for state, we can place the command line arguments from the server into this and so pass the configuration into the client.

The changes to the service are to add in configuration code to the constructor

 
package activation;

import net.jini.export.*; 
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.BasicILFactory;
import net.jini.jeri.tcp.TcpServerEndpoint;
import net.jini.activation.ActivationExporter;

import net.jini.jrmp.JrmpExporter;

import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;
import net.jini.export.ProxyAccessor;

import net.jini.config.Configuration;
import net.jini.config.ConfigurationException;
import net.jini.config.ConfigurationProvider;

import common.MIMEType;
import common.FileClassifier;
import rmi.RemoteFileClassifier;
import java.rmi.Remote;

/**
 * FileClassifierConfig.java
 */

public class FileClassifierConfig implements RemoteFileClassifier,
					   ProxyAccessor {

    private Remote proxy;

    public MIMEType getMIMEType(String fileName) 
	throws java.rmi.RemoteException {
        if (fileName.endsWith(".gif")) {
            return new MIMEType("image", "gif");
        } else if (fileName.endsWith(".jpeg")) {
            return new MIMEType("image", "jpeg");
        } else if (fileName.endsWith(".mpg")) {
            return new MIMEType("video", "mpeg");
        } else if (fileName.endsWith(".txt")) {
            return new MIMEType("text", "plain");
        } else if (fileName.endsWith(".html")) {
            return new MIMEType("text", "html");
        } else
            // fill in lots of other types,
            // but eventually give up and
            return new MIMEType(null, null);
    }


    public FileClassifierConfig(ActivationID activationID, MarshalledObject data)  
	throws java.rmi.RemoteException {

	// The marshalled object should be an array of strings
	// holding a configuration
	String[] args = null;
	try {
	    args = (String[]) data.get();
	} catch(Exception e) {
	    // empty
	}

	Exporter defaultExporter = 
	    new ActivationExporter(activationID,
			 new BasicJeriExporter(TcpServerEndpoint.getInstance(0),
					       new BasicILFactory(),
					       false, true));
	Exporter exporter = defaultExporter;

	try {
	    Configuration config = ConfigurationProvider.getInstance(args); 

	    exporter = (Exporter) config.getEntry( "JeriExportDemo", 
						   "exporter", 
						   Exporter.class); 
	} catch(ConfigurationException e) {
	    // empty
	}

	proxy = (Remote) exporter.export(this);
    }

    // Implementation for ProxyAccessor
    public Object getProxy() {
	return proxy;
    }
} // FileClassifierImpl

	

The startup server marshalls the command line arguments and passes them into the activation description

 
	    
package activation;

//import rmi.RemoteFileClassifier;

import java.rmi.Remote;
import net.jini.discovery.LookupDiscovery;
import net.jini.discovery.DiscoveryListener;
import net.jini.discovery.DiscoveryEvent;
import net.jini.core.lookup.ServiceRegistrar;
import net.jini.core.lookup.ServiceItem;
import net.jini.core.lookup.ServiceRegistration;
import net.jini.core.lease.Lease;
import java.rmi.RMISecurityManager;
import java.rmi.MarshalledObject;
import java.rmi.activation.ActivationDesc;
import java.rmi.activation.ActivationGroupDesc;
import java.rmi.activation.ActivationGroupDesc.CommandEnvironment;
import java.rmi.activation.Activatable;
import java.rmi.activation.ActivationGroup;
import java.rmi.activation.ActivationGroupID;
import java.rmi.activation.ActivationSystem;
import java.rmi.activation.ActivationID;

import java.util.Properties;
import java.io.IOException;

import java.rmi.activation.UnknownGroupException;
import java.rmi.activation.ActivationException;
import java.rmi.RemoteException;

/**
 * FileClassifierServerConfig.java
 */

public class FileClassifierServerConfig implements DiscoveryListener {

    static final protected String SECURITY_POLICY_FILE = 
	"/home/httpd/html/java/jini/tutorial/policy.all";
    // Don't forget the trailing '/'!
    static final protected String CODEBASE = 
	"http://192.168.1.13/classes/activation.FileClassifierServer-dl.jar";
    
    // protected FileClassifierImpl impl;
    protected Remote stub;
    
    public static void main(String argv[]) {
	new FileClassifierServerConfig(argv);
	// stick around while lookup services are found
	try {
	    Thread.sleep(100000L);
	} catch(InterruptedException e) {
	    // do nothing
	}
	// the server doesn't need to exist anymore
	System.exit(0);
    }

    public FileClassifierServerConfig(String[] argv) {
	// install suitable security manager
	System.setSecurityManager(new RMISecurityManager());

	// new
	ActivationSystem actSys = null;
	try {
	    actSys = ActivationGroup.getSystem();
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	// Install an activation group
	Properties props = new Properties();
	props.put("java.security.policy",
	  SECURITY_POLICY_FILE);
	// props.put("java.rmi.server.codebase", 
	//  "http://192.168.1.13/classes/activation.FileClassifierServer-dl.jar");
	String[] options = {"-classpath", 
			    "/home/httpd/html/java/jini/tutorial/dist/activation.FileClassifierServer-act.jar:/usr/local/jini2_0/lib/phoenix-init.jar:/usr/local/jini2_0/lib/jini-ext.jar"};
	CommandEnvironment commEnv =
	    new CommandEnvironment(null, options);
	System.out.println("1");
	ActivationGroupDesc group = new ActivationGroupDesc(props, commEnv);
	System.out.println("2");
	ActivationGroupID groupID = null;
	try {
	    groupID = actSys.registerGroup(group);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	String codebase = CODEBASE;	
	MarshalledObject data = null;
	// marshall the command line args for the service
	try {
	    data = new MarshalledObject(argv);
	} catch(IOException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	ActivationDesc desc = null;
	desc = new ActivationDesc(groupID,
				  "activation.FileClassifierImpl",
				  codebase, data, true);

	// new
	ActivationID aid = null;
	try {
	    aid = actSys.registerObject(desc);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	try {
	System.out.println("3");
	    stub = (Remote) aid.activate(true);
	System.out.println("4 " + stub);
	    // stub = (RemoteFileClassifier) Activatable.register(desc);
	} catch(UnknownGroupException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	
	LookupDiscovery discover = null;
        try {
            discover = new LookupDiscovery(LookupDiscovery.ALL_GROUPS);
        } catch(Exception e) {
            System.err.println(e.toString());
            System.exit(1);
        }

        discover.addDiscoveryListener(this);
    }
    
    public void discovered(DiscoveryEvent evt) {

        ServiceRegistrar[] registrars = evt.getRegistrars();

        for (int n = 0; n < registrars.length; n++) {
            ServiceRegistrar registrar = registrars[n];

	    // export the proxy service
	    ServiceItem item = new ServiceItem(null,
					       stub,
					       null);
	    ServiceRegistration reg = null;
	    try {
		reg = registrar.register(item, Lease.FOREVER);
	    } catch(java.rmi.RemoteException e) {
		System.err.print("Register exception: ");
		e.printStackTrace();
		// System.exit(2);
		continue;
	    }
	    try {
		System.out.println("service registered at " +
				   registrar.getLocator().getHost());
	    } catch(Exception e) {
	    }
	}
    }

    public void discarded(DiscoveryEvent evt) {

    }
} // FileClassifierServer

	

An Ant file for this is activation.FileClassifierServerConfig.xml

Jini 1.1 supplied an implementation of LeaseRenewalService called norm. This was a non-lazy Activatable service, which required rmid to be running. In Jini 2.0 it has been extended to be much more flexible and is controlled by various configurations

1. JRMP

   1. transient

   2. persistent

   3. activatable (requires an activation server such as phoenix)

2. Jeri

   1. transient

   2. persistent

   3. activatable (requires an activation server such as phoenix)

For example, to run the transient Jeri version

java -Djava.security.policy=config_dir/jsk-all.policy \
     -jar install_dir/lib/start.jar \
     config_dir/start-transient-norm.config
	  

The policy file could contain

grant codebase "file:install_dir/lib/*" {
    permission java.security.AllPermission;
};
	  

The file start-transient-norm.config should contain

import com.sun.jini.start.NonActivatableServiceDescriptor;
import com.sun.jini.start.ServiceDescriptor;

com.sun.jini.start {
    private static codebase = "http://your_host:http_port/norm-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/norm.jar";
    private static config = "config_dir/transient-norm.config";

    static serviceDescriptors = new ServiceDescriptor[] {
	new NonActivatableServiceDescriptor(
	    codebase, policy, classpath,
	    "com.sun.jini.norm.TransientNormServerImpl",
	    new String[] { config })
    };
}
	  

This points to the transient-norm.config which in turn contains

com.sun.jini.norm {
    initialLookupGroups = new String[] { "your.group" };
}
	  

	  
/**
 * @version 1.1
 */

package activation;

import java.rmi.Remote;
import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;
import net.jini.core.event.RemoteEvent;
import net.jini.core.event.RemoteEventListener;
import net.jini.core.lease.Lease;
import net.jini.lease.ExpirationWarningEvent;

import net.jini.export.*; 
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.BasicILFactory;
import net.jini.jeri.tcp.TcpServerEndpoint;
import net.jini.activation.ActivationExporter;

public class RenewLease implements RemoteEventListener,
				   ProxyAccessor  {
    
    private Remote proxy;

    public RenewLease(ActivationID activationID, MarshalledObject data)  
	throws java.rmi.RemoteException {

	Exporter exporter = 
	    new ActivationExporter(activationID,
			 new BasicJeriExporter(TcpServerEndpoint.getInstance(0),
					       new BasicILFactory(),
					       false, true));
	    
	proxy = (Remote) exporter.export(this);
    }
    
    public void notify(RemoteEvent evt) {
	System.out.println("expiring... " + evt.toString());
	ExpirationWarningEvent eevt = (ExpirationWarningEvent) evt;
	Lease lease = eevt.getRenewalSetLease();
	try {
	    // This is short, for testing. Try 2+ hours
	    lease.renew(20000L);
	} catch(Exception e) {
	    e.printStackTrace();
	}
	System.out.println("Lease renewed for " +
			   (lease.getExpiration() -
			    System.currentTimeMillis()));
    }

    public Object getProxy() {
	return proxy;
    }
}

	

 
	  
package activation;

import rmi.RemoteFileClassifier;

import net.jini.discovery.LookupDiscovery;
import net.jini.discovery.DiscoveryListener;
import net.jini.discovery.DiscoveryEvent;
import net.jini.core.lookup.ServiceRegistrar;
import net.jini.core.lookup.ServiceItem;
import net.jini.core.lookup.ServiceRegistration;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.core.event.RemoteEvent;
import net.jini.core.event.RemoteEventListener;
import net.jini.core.lease.Lease;
import net.jini.lease.LeaseRenewalService;
import net.jini.lease.LeaseRenewalSet;
import java.rmi.RMISecurityManager;
import java.rmi.MarshalledObject;
import java.rmi.activation.ActivationDesc;
import java.rmi.activation.ActivationGroupDesc;
import java.rmi.activation.ActivationGroupDesc.CommandEnvironment;
import java.rmi.activation.Activatable;
import java.rmi.activation.ActivationGroup;
import java.rmi.activation.ActivationGroupID;
import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;

import java.util.Properties;
import java.util.Vector;

import java.rmi.activation.UnknownGroupException;
import java.rmi.activation.ActivationException;
import java.rmi.RemoteException;

/**
 * FileClassifierServer.java
 */

public class FileClassifierServerLease
    implements DiscoveryListener {

    static final protected String SECURITY_POLICY_FILE = 
	"/home/jan/projects/jini/doc/policy.all";
    // Don't forget the trailing '/'!
    static final protected String CODEBASE = "http://localhost/classes/";
    
    protected RemoteFileClassifier stub;

    protected RemoteEventListener leaseStub;

    // Lease renewal management
    protected LeaseRenewalSet leaseRenewalSet = null;

    // List of leases not yet managed by a LeaseRenewalService
    protected Vector leases = new Vector();

    public static void main(String argv[]) {
	new FileClassifierServerLease(argv);
	// stick around while lookup services are found
	try {
	    Thread.sleep(10000L);
	} catch(InterruptedException e) {
	    // do nothing
	}
	// the server doesn't need to exist anymore
	System.exit(0);
    }

    public FileClassifierServerLease(String[] argv) {
	// install suitable security manager
	System.setSecurityManager(new RMISecurityManager());

	// Install an activation group
	Properties props = new Properties();
	props.put("java.security.policy",
		SECURITY_POLICY_FILE);
	ActivationGroupDesc.CommandEnvironment ace = null;
	ActivationGroupDesc group = new ActivationGroupDesc(props, ace);
	ActivationGroupID groupID = null;
	try {
	    groupID = ActivationGroup.getSystem().registerGroup(group);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	
	try {
	    ActivationGroup.createGroup(groupID, group, 0);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	
	String codebase = CODEBASE;	
	MarshalledObject data = null;
	ActivationDesc desc = null;
	ActivationDesc descLease = null;
	try {
	    desc = new ActivationDesc("activation.FileClassifierImpl",
						 codebase, data);
	    descLease = new ActivationDesc("activation.RenewLease",
						 codebase, data);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	try {
            stub = (RemoteFileClassifier) Activatable.register(desc);
            leaseStub = (RemoteEventListener) Activatable.register(descLease);
	} catch(UnknownGroupException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	
	LookupDiscovery discover = null;
        try {
            discover = new LookupDiscovery(LookupDiscovery.ALL_GROUPS);
        } catch(Exception e) {
            System.err.println(e.toString());
            System.exit(1);
        }

        discover.addDiscoveryListener(this);
    }

    public void discovered(DiscoveryEvent evt) {

        ServiceRegistrar[] registrars = evt.getRegistrars();
	RemoteFileClassifier service;

        for (int n = 0; n < registrars.length; n++) {
            ServiceRegistrar registrar = registrars[n];

	    // export the proxy service
	    ServiceItem item = new ServiceItem(null,
					       stub,
					       null);
	    ServiceRegistration reg = null;
	    try {
		reg = registrar.register(item, Lease.FOREVER);
	    } catch(java.rmi.RemoteException e) {
		System.err.print("Register exception: ");
		e.printStackTrace();
		// System.exit(2);
		continue;
	    }
	    try {
		System.out.println("service registered at " +
				   registrar.getLocator().getHost());
	    } catch(Exception e) {
	    }

	    Lease lease = reg.getLease();
	    // if we have a lease renewal manager, use it
	    if (leaseRenewalSet != null) {
		try {
		    leaseRenewalSet.renewFor(lease, Lease.FOREVER);
		} catch(RemoteException e) {
		    e.printStackTrace();
		}
	    } else {
		// add to the list of unmanaged leases
		leases.add(lease);
		// see if this lookup service has a lease renewal manager
		findLeaseService(registrar);
	    }
	}
    }

    public void findLeaseService(ServiceRegistrar registrar) {
	System.out.println("Trying to find a lease service");
	Class[] classes = {LeaseRenewalService.class};
	ServiceTemplate template = new ServiceTemplate(null, classes, 
                                                   null);
	LeaseRenewalService leaseService = null;
	try {
	    leaseService = (LeaseRenewalService) registrar.lookup(template);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    return;
	}
	if (leaseService == null) {
	    System.out.println("No lease service found");
	    return;
	}
	try {
	    // This time is unrealistically small - try 10000000L
	    leaseRenewalSet = leaseService.createLeaseRenewalSet(20000);
	    System.out.println("Found a lease service");
	    // register a timeout listener
	    leaseRenewalSet.setExpirationWarningListener(leaseStub, 5000,
	    					 null);
	    // manage all the leases found so far
	    for (int n = 0; n < leases.size(); n++) {
		Lease ll = (Lease) leases.elementAt(n);
		leaseRenewalSet.renewFor(ll, Lease.FOREVER);
	    }
	    leases = null;
	} catch(RemoteException e) {
	    e.printStackTrace();
	}
	Lease renewalLease = leaseRenewalSet.getRenewalSetLease();
	System.out.println("Lease expires in " +
			   (renewalLease.getExpiration() -
			    System.currentTimeMillis()));
    }

    public void discarded(DiscoveryEvent evt) {

    }
} // FileClassifierServerLease



    

	

An Ant file to build, deploy and run the service is activation.FileClassifierServerLease.xml

In order to run the server, the following need to be running

1. reggie to run as a lookup service

2. phoenix to act as an activation server for the FileClassifier service, and also for the RenewLease service

3. norm as a lease renewal service. Each lease will be registered with this, and it will have the RenewLease as listener for expiration events

!!! I HAVEN'T MADE ANY CHANGES BEYOND THIS POINT YET !!!

The Jini 1.1 release includes an implementation of the lookup discovery service, called fiddler. This has been modified in Jini 2.0 to be more flexible. It can be run in three modes, using either Jeri (the default) or JRMP

1. transient

2. persistent

3. activatable (requires phoenix to be running)

To run fiddler in transient mode using Jeri over TCP, a command line such as this needs to be executed

java \
  -Djava.security.manager= \
  -Djava.security.policy=fiddler-start-transient.policy \
    -jar jini_install_dir/lib/start.jar \
           config/fiddler-start-transient.config
	

The contents of fiddler-start-transient.config could be

import com.sun.jini.start.NonActivatableServiceDescriptor;
import com.sun.jini.start.ServiceDescriptor;

com.sun.jini.start {

    private static serviceCodebase   = 
            new String("http://myHost:8080/fiddler-dl.jar");
    private static servicePolicyFile = 
            new String("example_install_dir${/}policy${/}jeri-transient-fiddler.policy");
    private static serviceClasspath  = 
            new String("jini_install_dir${/}lib${/}fiddler.jar");
    private static serviceImplName   = 
            new String("com.sun.jini.fiddler.TransientFiddlerImpl");
    private static serviceConfig     = 
            new String("example_install_dir${/}config${/}jeri-transient-fiddler.config");
    private static serviceArgsArray  = new String[] { serviceConfig };

    private static nonActivatableServiceDescriptor =
                   new NonActivatableServiceDescriptor(serviceCodebase,
                                                       servicePolicyFile,
                                                       serviceClasspath,
                                                       serviceImplName,
                                                       serviceArgsArray);
    static serviceDescriptors = 
                 new ServiceDescriptor[] { nonActivatableServiceDescriptor };

}//end com.sun.jini.start
	

import net.jini.jeri.BasicILFactory;
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.tcp.TcpServerEndpoint;

com.sun.jini.fiddler {

    private invocationLayerFactory = new BasicILFactory();
    serverExporter = new BasicJeriExporter(TcpServerEndpoint.getInstance(0),
                                           invocationLayerFactory,
                                           false,
                                           true);

    initialLookupGroups = new String[] {"myGroup.myCompany.com"};

}//end com.sun.jini.fiddler

An activatable service can make use of a lease renewal service to look after the leases for lookup services discovered. How it finds these lookup services can be by means of a lookup discovery service. The logic to manage these two services could be a little tricky as we attempt to find two different services. We can simplify for this example by just doing a sequential search using a ServiceDiscoveryManager

While lease management can be done by the lease renewal service, the lease renewal set will also be leased and will need to be renewed on occasions. The lease renewal service can call an activatable RenewLease object to do this, as in the last section.

The lookup discovery service is also a leased service - it will only report changes to lookup services while its own lease is current. So the lease from this service will have to be managed by the lease renewal service, in addition to the leases for any lookup services discovered.

The primary purpose of the lookup discovery service is to call the notify() method of some object when information about lookup services changes. This object should also be an activatable object. We define a DiscoveryChange object with method notify() to handle changes in lookup services. If a lookup service has disappeared, we don't worry about it. If a lookup service has been discovered, we want to register the service with it, and then manage the resultant lease. This means that the DiscoveryChange object must know both the service to be registered, and the lease renewal service. This is static data, so these two objects can be passed in an array of two objects as the MarshalledObject to the activation constructor. The class itself can be implemented as

 
	  
package activation;

import java.rmi.activation.Activatable;
import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;
import net.jini.core.event.RemoteEvent;
import net.jini.core.event.RemoteEventListener;
import net.jini.core.lease.Lease;
import net.jini.lease.ExpirationWarningEvent;
import net.jini.core.lookup.ServiceItem;
import net.jini.core.lookup.ServiceRegistrar;
import net.jini.core.lookup.ServiceRegistration;
import net.jini.lease.LeaseRenewalSet;
import net.jini.discovery.RemoteDiscoveryEvent;
import java.rmi.RemoteException;
import  net.jini.discovery.LookupUnmarshalException;

import rmi.RemoteFileClassifier;

public class DiscoveryChange extends Activatable
    implements RemoteEventListener {

    protected LeaseRenewalSet leaseRenewalSet;
    protected RemoteFileClassifier service;
    
    public DiscoveryChange(ActivationID id, MarshalledObject data)  
	throws java.rmi.RemoteException {
	super(id, 0);
	Object[] objs = null;
	try {
	    objs = (Object []) data.get();
	} catch(ClassNotFoundException e) {
	    e.printStackTrace();
	} catch(java.io.IOException e) {
	    e.printStackTrace();
	}
	service = (RemoteFileClassifier) objs[0];
	leaseRenewalSet= (LeaseRenewalSet) objs[1];
    }
    
    public void notify(RemoteEvent evt) {
	System.out.println("lookups changing... " + evt.toString());
	RemoteDiscoveryEvent revt = (RemoteDiscoveryEvent) evt;

	if (! revt.isDiscarded()) {
	    // The event is a discovery event
	    ServiceItem item = new ServiceItem(null, service, null);
	    ServiceRegistrar[] registrars = null;
	    try {
		registrars = revt.getRegistrars();
	    } catch(LookupUnmarshalException e) {
		e.printStackTrace();
		return;
	    }
	    for (int n = 0; n < registrars.length; n++) {
		ServiceRegistrar registrar = registrars[n];
		
		ServiceRegistration reg = null;
		try {
		    reg = registrar.register(item, Lease.FOREVER);
		    leaseRenewalSet.renewFor(reg.getLease(), Lease.FOREVER);
		} catch(java.rmi.RemoteException e) {
		    System.err.println("Register exception: " + e.toString());
		}
	    }
	}
    }
}

	

The server must install an activation group, and then find activation proxies for the service itself and also for our lease renewal object. After this, it can use a ClientLookupManager to find the lease service, and register our lease renewal object with it. Now that it has a proxy for the service object, and also a lease renewal service, it can create the marshalled data for the lookup discovery service and register this with rmid. Now we can find the lookup discovery service, and register our discovery change listener DiscoveryChange with it. At the same time, we have to register the service with all the lookup services the lookup discovery service finds on initialisation. This all leads to

 
	  
package activation;

import rmi.RemoteFileClassifier;

import net.jini.discovery.LookupDiscovery;
import net.jini.discovery.LookupDiscoveryService;
import net.jini.discovery.DiscoveryListener;
import net.jini.discovery.DiscoveryEvent;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.discovery.LookupDiscoveryRegistration;
import net.jini.discovery.LookupUnmarshalException;

import net.jini.core.lookup.ServiceRegistrar;
import net.jini.core.lookup.ServiceItem;
import net.jini.core.lookup.ServiceRegistration;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.core.event.RemoteEvent;
import net.jini.core.event.RemoteEventListener;
import net.jini.core.lease.Lease;

import net.jini.lease.LeaseRenewalService;
import net.jini.lease.LeaseRenewalSet;
import net.jini.lease.LeaseRenewalManager;

import net.jini.lookup.ServiceDiscoveryManager;

import java.rmi.RMISecurityManager;
import java.rmi.activation.ActivationDesc;
import java.rmi.activation.ActivationGroupDesc;
import java.rmi.activation.ActivationGroupDesc.CommandEnvironment;
import java.rmi.activation.Activatable;
import java.rmi.activation.ActivationGroup;
import java.rmi.activation.ActivationGroupID;
import java.rmi.activation.ActivationID;
import java.rmi.MarshalledObject;
import java.rmi.activation.UnknownGroupException;
import java.rmi.activation.ActivationException;
import java.rmi.RemoteException;

import java.util.Properties;
import java.util.Vector;



/**
 * FileClassifierServerDiscovery.java
 */

public class FileClassifierServerDiscovery
    /* implements DiscoveryListener */ {
    private static final long WAITFOR = 10000L;

    static final protected String SECURITY_POLICY_FILE = 
	"/home/jan/projects/jini/doc/policy.all";
    // Don't forget the trailing '/'!
    static final protected String CODEBASE = "http://localhost/classes/";
    
    protected RemoteFileClassifier serviceStub;

    protected RemoteEventListener leaseStub,
	                          discoveryStub;

    // Services
    protected LookupDiscoveryService discoveryService = null;
    protected LeaseRenewalService leaseService = null;

    // Lease renewal management
    protected LeaseRenewalSet leaseRenewalSet = null;

    // List of leases not yet managed by a LeaseRenewalService
    protected Vector leases = new Vector();

    protected ServiceDiscoveryManager clientMgr = null;

    public static void main(String argv[]) {
	new FileClassifierServerDiscovery();
	// stick around while lookup services are found
	try {
	    Thread.sleep(20000L);
	} catch(InterruptedException e) {
	    // do nothing
	}
	// the server doesn't need to exist anymore
	System.exit(0);
    }

    public FileClassifierServerDiscovery() {
	// install suitable security manager
	System.setSecurityManager(new RMISecurityManager());

	installActivationGroup();

	serviceStub = (RemoteFileClassifier) 
	              registerWithActivation("activation.FileClassifierImpl", null);
	
	leaseStub = (RemoteEventListener) 
	              registerWithActivation("activation.RenewLease", null);

	initClientLookupManager();

	findLeaseService();

	// the discovery change listener needs to know the service and the lease service
	Object[] discoveryInfo = {serviceStub, leaseRenewalSet};
	MarshalledObject discoveryData = null;
	try {
	    discoveryData = new MarshalledObject(discoveryInfo);
	} catch(java.io.IOException e) {
	    e.printStackTrace();
	}
	discoveryStub = (RemoteEventListener) 
	                 registerWithActivation("activation.DiscoveryChange",
						discoveryData);

	findDiscoveryService();

    }

    public void installActivationGroup() {

	Properties props = new Properties();
	props.put("java.security.policy",
		  SECURITY_POLICY_FILE);
	ActivationGroupDesc.CommandEnvironment ace = null;
	ActivationGroupDesc group = new ActivationGroupDesc(props, ace);
	ActivationGroupID groupID = null;
	try {
	    groupID = ActivationGroup.getSystem().registerGroup(group);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	
	try {
	    ActivationGroup.createGroup(groupID, group, 0);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
    }

    public Object registerWithActivation(String className, MarshalledObject data) {
	String codebase = CODEBASE;	
	ActivationDesc desc = null;
	Object stub = null;

	try {
	    desc = new ActivationDesc(className,
					   codebase, data);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	}

	try {
            stub = Activatable.register(desc);
	} catch(UnknownGroupException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(ActivationException e) {
	    e.printStackTrace();
	    System.exit(1);
	} catch(RemoteException e) {
	    e.printStackTrace();
	    System.exit(1);
	}
	return stub;
    }

    public void initClientLookupManager() {
	LookupDiscoveryManager lookupDiscoveryMgr = null;
        try {
            lookupDiscoveryMgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
            clientMgr = new ServiceDiscoveryManager(lookupDiscoveryMgr, 
						new LeaseRenewalManager());
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    public void findLeaseService() {
	leaseService = (LeaseRenewalService) findService(LeaseRenewalService.class);
	if (leaseService == null) {
	    System.out.println("Lease service null");
	}
	try {
	    leaseRenewalSet = leaseService.createLeaseRenewalSet(20000);
	    leaseRenewalSet.setExpirationWarningListener(leaseStub, 5000,
                                                 null);
	} catch(RemoteException e) {
	    e.printStackTrace();
	}
    }

    public void findDiscoveryService() {
	discoveryService = (LookupDiscoveryService) findService(LookupDiscoveryService.class);
	if (discoveryService == null) {
	    System.out.println("Discovery service null");
	}
	LookupDiscoveryRegistration registration = null;
	try {
	    registration =
		discoveryService.register(LookupDiscovery.ALL_GROUPS,
					  null,
					  discoveryStub,
					  null,
					  Lease.FOREVER);
	} catch(RemoteException e) {
	    e.printStackTrace();
	}
	// manage the lease for the lookup discovery service
	try {
	    leaseRenewalSet.renewFor(registration.getLease(), Lease.FOREVER);
	} catch(RemoteException e) {
	    e.printStackTrace();
	}

	// register with the lookup services already found
	ServiceItem item = new ServiceItem(null, serviceStub, null);
	ServiceRegistrar[] registrars = null;
	try {
	    registrars = registration.getRegistrars();
	} catch(RemoteException e) {
	    e.printStackTrace();
	    return;
	} catch(LookupUnmarshalException e) {
	    e.printStackTrace();
	    return;
	}

	for (int n = 0; n < registrars.length; n++) {
	    ServiceRegistrar registrar = registrars[n];
	    ServiceRegistration reg = null;
	    try {
		reg = registrar.register(item, Lease.FOREVER);
		leaseRenewalSet.renewFor(reg.getLease(), Lease.FOREVER);
	    } catch(java.rmi.RemoteException e) {
		System.err.println("Register exception: " + e.toString());
	    }
	}
    }

    public Object findService(Class cls) {
        Class [] classes = new Class[] {cls};
        ServiceTemplate template = new ServiceTemplate(null, classes, 
                                                       null);

        ServiceItem item = null;
        try {
            item = clientMgr.lookup(template, 
                                    null, /* no filter */ 
                                    WAITFOR /* timeout */);
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
        if (item == null) {
            // couldn't find a service in time
	    System.out.println("No service found for " + cls.toString());
	    return null;
        }
        return item.service;
    }
} // FileClassifierServerDiscovery



    

	

In order to run this example, you need to

1. Run a lookup service reggie

2. Run an activation server phoenix

3. Run a lease renewal service norm

4. Run a lookup discovery service fiddler

5. Run the server. This will terminate, hopefully after finding the services and registering the DiscoveryChange with the lookup discovery service, and register the leases for the service and the discovery service