JOIN MANAGER

Join Manager

• There are common steps in any server:
  • contact all known service locators by unicast
  • search for unknown locators by multicast
  • register the service with all of these
  • install a lease manager to keep the service alive
• These are encapsulated in JoinManager

  public class JoinManager {
       public JoinManager(Object obj,
                          Entry[] attrSets,
                          ServiceIDListener callback,
                          DiscoveryManagement discoverMgr,
                          LeaseRenewalManager leaseMgr)    
              throws IOException;
  
       public JoinManager(Object obj,
                          Entry[] attrSets,
                          ServiceID serviceID,
                          DiscoveryManagement discoverMgr,
                          LeaseRenewalManager leaseMgr)    
              throws IOException;
  }
        

• The first of these methods is used when the service is new and does not have a service id. A ServiceIDListener can be added which can note and save the id.
• The second method is used when the service already has an id.
• The other parameters are for the service and its entry attributes, a DiscoveryManagement object to set groups and unicast locators (typically this will be done using a LookupDiscoveryManager) and a lease renewal manager.

Service using Join Manager

REMOTE EVENTS

Event models

• Java has several event models
• Input events are generated by user actions such as key press, mouse click. These are placed into an event queue by one thread, removed by another
• Semantic events are generated by GUI components, such as mouse click in a Button generates an ActionEvent
• Property changes in objects generate PropertyChange events for Java beans
• Jini events are designed to work in a network environment
  • Events may be lost
  • Event delivery may have time delays, and state information may be out of date when it arrives
  • A listener may have disappeared or be unreachable, so listeners need to be on leases
  • Multiple event types (such as AWT events) require class availability while simple types don't

Remote events

• Event listeners must implement

        public interface RemoteEventListener {
            public void notify(RemoteEvent evt) throws ...:
        }
        

• Where

        public class RemoteEvent {
            public long getID();             // distinguish event types
            public long getSequenceNumber(); // like a timestamp
            public MarshalledObject getRegistrationObject(); // handback
        

• There is no equivalent within Jini to addActionListener(), addPropertyChangeListener(), etc. Each object must look after its own listener list and decide when and how to call it. But...
• Registration of a remote event listener must return

        public class EventRegistration {
            public EventRegistration(long eventID, Object source,
                                     Lease lease, long seqNum);
            public long getID();
            public Object getSource();
            public Lease getLease();
            public long getSequenceNumber();
        }
        

A single listener list

A list with only one listener on it can be done by

protected RemoteEventListener listener = null;

public EventRegistration addRemoteListener(RemoteEventListener listener)
       throws java.util.TooManyListenersException {
    if (this.listener == null {
        this.listener = listener;
    } else {
        throw new java.util.TooManyListenersException();
    }
    return new EventRegistration(0L, this, null, 0L);
}

Single listener event notification

The source object can send an event to its listener by

protected void fireNotify(long eventID,
                          long seqNum) {
    if (listener == null) {
        return;
    }

    RemoteEvent remoteEvent = new RemoteEvent(this, eventID, 
                                              seqNum, null);
    listener.notify(remoteEvent);
}

A multiple listener list

A list with multiple listeners on it can be done by

protected Vector listeners = new Vector();

public EventRegistration addRemoteListener(RemoteEventListener listener) {
    listeners.add(listener);
    return new EventRegistration(0L, this, null, 0L);
}

Multiple listener event notification

The source object can send an event to its listener list by

protected void fireNotify(long eventID,
                          long seqNum) {
    RemoteEvent remoteEvent = new RemoteEvent(this, eventID, 
                                              seqNum, null);
    for (int n = 0; n < listeners.size(); n++) {
        RemoteListener listener = (RemoteListener) listeners.elementAt(n);
        listener.notify(remoteEvent);
    }
}

Remote events using echo

• Echo is a stateless service
• Events are usually issued on change of state, otherwise they don't mean anything
• So the echo service has to be hacked a bit to make it stateful by e.g making the last stgring echoed into a state value
• Each time echo() is called, a change event is isued and sent to listeners
• The source files are here

Echo interface

Echo interface implementation

Echo server

Echo client

Echo listener

Flashing clocks

• Like the UPnP example, the Jini clock can act as an event generator
• Jini events do not have to be associated with state variables, but something has to change to generate events!
• This example generates events when the valid state is set or changes
• The Timer interface needs methods to add/remove event listeners
• The implementations need to handle the listener lists and generate and post events
• No other changes are needed on the service side - the clients get a timer can make calls directly on it
• All files are here

Timer

Ticker Timer

Listener

• The listener must register with the service
• It must first find the services using ServiceDiscoveryManager
• The listener gets a proxy for the service
• When the listener registers, the service gets an object that represents the listener
• The service gets a proxy for the listener
• So the listener must create a proxy for itself, and hand this to the service proxy to be added to the listener list

Validity Listener

Deployment

• Compile all source files
• On the server machine generate RMI stubs for all the timers using rmic
• Run an HTTP server for the server and copy all the stub files to it
• On the client machine, generate an RMI stub for the ValidityListener
• Run an HTTP server for the client and copy all the stub files to it
• (All the HTTP servers can be the same one)
• Run reggie
• Run the listener
• Run some clocks
• Running first the lsitener, then a ticker clock and then a computer clock gives in the client window

  
  runvalidity:
       [exec] Service appeared: class service.TickerTimer_Stub
       [exec] Service appeared: class service.ComputerTimer_Stub
       [exec] Got event from service.TickerTimer_Stub[RemoteStub [ref: [endpoint:[192.168.1.11:32986](remote),objID:[d42d08:fc9d2377fd:-8000, 0]]]]
       [exec]    value is valid
  

Mutable file classifier

Allow the file classifier to change its list of MIME type mappings, and notify listeners when it does so

import java.rmi.server.UnicastRemoteObject;
import java.rmi.MarshalledObject;
import net.jini.core.event.RemoteEventListener;
import net.jini.core.event.RemoteEvent;
import net.jini.core.event.EventRegistration;
import java.rmi.RemoteException;
import net.jini.core.event.UnknownEventException ;

import javax.swing.event.EventListenerList;

import common.MIMEType;
import common.MutableFileClassifier;
import java.util.Map;
import java.util.HashMap;

public class FileClassifierImpl extends  UnicastRemoteObject 
                                implements RemoteFileClassifier {

    /**
     * Map of String extensions to MIME types
     */
    protected Map map = new HashMap();

    /**
     * Listeners for change events
     */
    protected EventListenerList listenerList = new EventListenerList();

    public MIMEType getMIMEType(String fileName) 
	throws java.rmi.RemoteException {

	MIMEType type;
	String fileExtension;
	int dotIndex = fileName.lastIndexOf('.');

	if (dotIndex == -1 || dotIndex + 1 == fileName.length()) {
	    // can't find suitable suffix
	    return null;
	}

	fileExtension= fileName.substring(dotIndex + 1);
	type = (MIMEType) map.get(fileExtension);
	return type; 
    }

    public void addType(String suffix, MIMEType type)
	throws java.rmi.RemoteException {
	map.put(suffix, type);
	fireNotify(ADD_TYPE);
    }

    public void removeMIMEType(String suffix, MIMEType type)
	throws java.rmi.RemoteException {
	if (map.remove(suffix) != null) {
	    fireNotify(REMOVE_TYPE);
	}
    }

    public EventRegistration addRemoteListener(RemoteEventListener listener)
	throws java.rmi.RemoteException {
	listenerList.add(RemoteEventListener.class, listener);

	return new EventRegistration(0, this, null, 0);
    }

    // Notify all listeners that have registered interest for
    // notification on this event type.  The event instance 
    // is lazily created using the parameters passed into 
    // the fire method.

    protected void fireNotify(long eventID) {
	RemoteEvent remoteEvent = null;
	
	// Guaranteed to return a non-null array
	Object[] listeners = listenerList.getListenerList();
	
	// Process the listeners last to first, notifying
	// those that are interested in this event
	for (int i = listeners.length - 2; i >= 0; i -= 2) {
	    if (listeners[i] == RemoteEventListener.class) {
		RemoteEventListener listener = (RemoteEventListener) listeners[i+1];
		if (remoteEvent == null) {
		    remoteEvent = new RemoteEvent(this, eventID, 
						  0L, null);
		}
		try {
		    listener.notify(remoteEvent);
		} catch(UnknownEventException e) {
		    e.printStackTrace();
		} catch(RemoteException e) {
		    e.printStackTrace();
		}
	    }
	}
    }    

    public FileClassifierImpl()  throws java.rmi.RemoteException {
	// load a predefined set of MIME type mappings
	map.put("gif", new MIMEType("image", "gif"));
	map.put("jpeg", new MIMEType("image", "jpeg"));
	map.put("mpg", new MIMEType("video", "mpeg"));
	map.put("txt", new MIMEType("text", "plain"));
	map.put("html", new MIMEType("text", "html"));
    }
} // FileClassifierImpl

USER INTERFACE

User interface

• Using the public interface, a client can write a generic UI to handle all services of that type
• A custmised user interface for a service must come from the service, the client cannot be expected to know it
• Jini has a standard way of doing this which is very complicated. This is dealt with later
• A comparatively simple way is given first
• All source files are here

UI or factory?

• To send a service, the server creates the service object and a proxy for it, and sends the proxy to the lookup service
• If the server also attempts to create a UI object such as a JFrame then
  • It will get its fonts from the server
  • It will get UI style (metal, windows, etc) from the server
  • It will get its locale from the server
• If it is then transferred to the client, then the client may have different fonts, different style, different locale
• So the server should not instantiate the UI. Instead it should create a factory and send that to the client
• When the client gets the factory, it calls a method that creates a client-side UI such as a JFrame, with all client-side properties

UI must know the proxy

• The UI object will make calls back to the service
• It must know the proxy object in order to do so
• The factory will need to take the proxy as parameter

Factory as Entry

• The service will not change just because it has a UI, so the service spec will not change
• The easiest way to get a factory across is to send it as an Entry field along with the service
• The client can only deal with interfaces - if it had the object, it wouldn't need to get it from the service

UIFactory interface

This is all new

UIFactory implementation

This is all new. It puts a label with the current time and a Refresh button inside a frame

Service with UI

UI client

Deployment

• Compile all source files
• On the server machine generate RMI stubs for all the timers using rmic
• Run an HTTP server for the server and copy all the stub files to it
• Run reggie
• Run the client UI
• Run some clocks
Each clock should show its own frame, as before
• The client should also show a frame for the UI that it got from the service

Problems with this approach

• The client may not have the class files for the UI - a phone running MIDP cannot handle Swing classes
• When the factory is instantiated, the JFrame class must be loaded since it is a return type. Otherwise an exception will be thrown
• So the factory should be wrapped in a MarshalledObject
• But then the client doesn't know its type, so extra fields must be added to tell the client what is inside the marshalled object

Run

Two clocks running with their "local" UIs on the right and their "remote UIs" on the left look like

User interface - old stuff

• A user interface for a service must come from the service, the client cannot be expected to know it
• Jini sets possible user interfaces as Entry attributes
• The Entry object for a UI is

  
  public class UIDescriptor extends AbstractEntry {
        
      public String role;
      public String toolkit;
      public Set attributes;
      public MarshalledObject factory;
  
      public UIDescriptor();
      public UIDescriptor(String role, String toolkit, 
                          Set attributes, MarshalledObject factory);
  
      public final Object getUIFactory(ClassLoader parentLoader)
             throws IOException, ClassNotFoundException;
  }
  
        

Reasons for UIDescriptor

• The UI should be created on the client side only - there is no point creating one on the server side, because it will not be used there
• The server side creates a factory. This factory is sent to the client, and the client uses the factory to create the UI
• The server could send many factories: one to create a Swing UI, one to create a MIDP UI, etc
• If the client attempts to instantiate a factory object that generates a Swing UI, then it must know the Swing classes (not possible in a J2ME phone). If the client attempts to instantiate a factory object that generates a MIDP UI, then it must know the MIDP classes (not possible in a standard JDK).
• So the factory is sent as a MarshalledObject and all Java's should know this class
• But then the client doesn't know what is inside the marshalled object till it unmarshals it - which needs the appropriate UI classes to be present
• The toolkit field is a string that says what UI classes will be needed
• This still doesn't give enough info about the factory e.g. if it uses Swing classes, does the factory generate a JFrame, a JDialog or a JPanel? This info is stored in the attributes
• Finally, is the UI for everyday users, for novices, for administrators, etc? This info is given in the role

Attributes of UIDescriptor

role

Each UI may have a speecific role, such as system administrator UI, novice UI, general UI. The only UI role currently defined is

public interface net.jini.lookup.ui.MainUI {
    String ROLE = "net.jini.lookup.ui.MainUI";
}   
      

toolkit

A UI built using AWT components will require the java.awt toolkit to be present; using Swing will require the javax.swing toolkit; using MIDP would require the javax.microedition.lcdui. The toolkit is set to one of these strings, so that the client can do a quick check on what the UI requires

factory

The UI will generate objects of a certain type that can be used by the client. These could be e.g.

• AWT Dialog
• Swing JFrame

The factory is a generator of one of these objects. It will be sent as a MarshalledObject (see later)

There is a factory interface for each type e.g

package net.jini.lookup.ui.factory;

import javax.swing.JFrame;

public interface JFrameFactory {
    String TOOLKIT = "javax.swing";
    String TYPE_NAME = "net.jini.lookup.ui.factory.JFrameFactory";

    JFrame getJFrame(Object roleObject);
}
      

attributes

These can carry any additional information about a UI. In particular, info about the factory type should be included

        Set attribs = new HashSet();
        Set typeNames = new HashSet();
        typeNames.add(JFrameFactory.TYPE_NAME);
        attribs.add(new UIFactoryTypes(typeNames));
      

Marshalled factory object

• If an object is instantiated, all of the classes needed for the object have to be present
• For a limited device machine such as a MIDP wireless device, classes such as AWT and Swing are not there
• An attempt to instantiate an object which uses e.g. Swing could result in a download of the entire Swing package
• To avoid this, a factory is not sent as e.g. JFrameFactory, to avoid this possible download.
• A factory is sent as a MarshalledObject, which should be present in all Java machines

  
          MarshalledObject factory = null;
          try {
              factory = new MarshalledObject(new FileClassifierFrameFactory());
          } catch(Exception e) {
          }
        

• This is why the toolkit and the factory type are sent in the UIDescriptor, so the client can figure out if it can handle the type before unmarshalling it

Factory implementation

• Each factory must have an implementation to return a UI object for the service
• e.g. a FrameFactory factory for a which can generate a Frame for a FileClassifierUI could be

FileClassifierFrame

• A FileClassifierFrame could look like
and when invoked pop up a dialog
• Implementation is

Server

A server to deliver both a FileClassifier and a UI for it is

import complete.FileClassifierImpl;

import net.jini.lookup.JoinManager;
import net.jini.core.lookup.ServiceID;
import net.jini.discovery.LookupDiscovery;
import net.jini.core.lookup.ServiceRegistrar;
import java.rmi.RemoteException;
import net.jini.lookup.ServiceIDListener;
import net.jini.lease.LeaseRenewalManager;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.discovery.DiscoveryEvent;
import net.jini.discovery.DiscoveryListener;
import net.jini.core.entry.Entry;

import net.jini.lookup.ui.MainUI;
import net.jini.lookup.ui.factory.FrameFactory;
import net.jini.lookup.entry.UIDescriptor;
import net.jini.lookup.ui.attribute.UIFactoryTypes;

import java.rmi.MarshalledObject;
import java.io.IOException;
import java.util.Set;
import java.util.HashSet;

public class FileClassifierServer 
    implements ServiceIDListener {
    
    public static void main(String argv[]) {
        new FileClassifierServer();

        // stay around forever
        Object keepAlive = new Object();
        synchronized(keepAlive) {
            try {
                keepAlive.wait();
            } catch(InterruptedException e) {
                // do nothing
            }
        }
    }

    public FileClassifierServer() {

        JoinManager joinMgr = null;

        // The typenames for the factory
        Set typeNames = new HashSet();
        typeNames.add(FrameFactory.TYPE_NAME);

        // The attributes set
        Set attribs = new HashSet();
        attribs.add(new UIFactoryTypes(typeNames));

        // The factory
        MarshalledObject factory = null;
        try {
            factory = new MarshalledObject(new FileClassifierFrameFactory());
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(2);
        }
        UIDescriptor desc = new UIDescriptor(MainUI.ROLE,
                                             FileClassifierFrameFactory.TOOLKIT,
                                             attribs,
                                             factory);

        Entry[] entries = {desc};

        try {
            LookupDiscoveryManager mgr = 
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
            joinMgr = new JoinManager(new FileClassifierImpl(), /* service */
                                      entries /* attr sets */,
                                      this /* ServiceIDListener*/,
                                      mgr /* DiscoveryManagement */,
                                      new LeaseRenewalManager());
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
    }

    public void serviceIDNotify(ServiceID serviceID) {
        // called as a ServiceIDListener
        // Should save the id to permanent storage
        System.out.println("got service ID " + serviceID.toString());
    }
    
} // FileClassifierServer

A client

A client to get a FileClassifier and use its UI is

import common.FileClassifier;
import common.MIMEType;

import java.rmi.RMISecurityManager;
import net.jini.discovery.LookupDiscovery;
import net.jini.core.lookup.ServiceTemplate;
import net.jini.discovery.LookupDiscoveryManager;
import net.jini.lookup.ServiceDiscoveryManager;
import net.jini.core.lookup.ServiceItem;
import net.jini.lease.LeaseRenewalManager;
import net.jini.core.entry.Entry;

import net.jini.lookup.ui.MainUI;
import net.jini.lookup.ui.factory.FrameFactory;
import net.jini.lookup.entry.UIDescriptor;
import net.jini.lookup.ui.attribute.UIFactoryTypes;

import java.awt.*;
import javax.swing.*;

import java.util.Set;
import java.util.Iterator;
import java.net.URL;

/**
 * TestFrameUI.java
 */

public class TestFrameUI {

    private static final long WAITFOR = 100000L;

    public static void main(String argv[]) {
        new TestFrameUI();

        // stay around long enough to receive replies
        try {
            Thread.currentThread().sleep(2*WAITFOR);
        } catch(java.lang.InterruptedException e) {
            // do nothing
        }
    }

    public TestFrameUI() {
        ServiceDiscoveryManager clientMgr = null;

        System.setSecurityManager(new RMISecurityManager());

        try {
            LookupDiscoveryManager mgr =
                new LookupDiscoveryManager(LookupDiscovery.ALL_GROUPS,
                                           null /* unicast locators */,
                                           null /* DiscoveryListener */);
            clientMgr = new ServiceDiscoveryManager(mgr, 
                                                new LeaseRenewalManager());
        } catch(Exception e) {
            e.printStackTrace();
            System.exit(1);
        }
  
        Class [] classes = new Class[] {FileClassifier.class};
        UIDescriptor desc = new UIDescriptor(MainUI.ROLE, 
                                             FrameFactory.TOOLKIT, 
                                             null, null);
        Entry [] entries = {desc};

        ServiceTemplate template = new ServiceTemplate(null, classes, 
                                                       entries);

        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");
            System.exit(1);
        }

        // We now have a service that plays the MainUI role and
        // uses the FrameFactory toolkit of "java.awt".
        // We now have to find if there is a UIDescriptor
        // with a Factory generating an AWT Frame
        checkUI(item);
    }

    private void checkUI(ServiceItem item) {
        // Find and check the UIDescriptor's
        Entry[] attributes = item.attributeSets;
        for (int m = 0; m < attributes.length; m++) {
            Entry attr = attributes[m];
            if (attr instanceof UIDescriptor) {
                // does it deliver an AWT Frame?
                checkForAWTFrame(item, (UIDescriptor) attr);
            }
        }
    }
   
    private void checkForAWTFrame(ServiceItem item, UIDescriptor desc) {
        Set attributes = desc.attributes;
        Iterator iter = attributes.iterator();
        while (iter.hasNext()) {
            // search through the attributes, to find a UIFactoryTypes
            Object obj = iter.next();
            if (obj instanceof UIFactoryTypes) {
                UIFactoryTypes types = (UIFactoryTypes) obj;
                // see if it produces an AWT Frame Factory
                if (types.isAssignableTo(FrameFactory.class)) {
                    FrameFactory factory = null;
                    try {
                        factory = (FrameFactory) desc.getUIFactory(this.getClass().
                                                                  getClassLoader());
                    } catch(Exception e) {
                        e.printStackTrace();
                        continue;
                    }

                    Frame frame = factory.getFrame(item); 
                    frame.setVisible(true);
                } 
            }
        }
    }
        

} // TestFrameUI

Summary

• Jini is a fairly complete middleware solution for distributed services
• Its advantages are
  • Lightweight
  • Supports dynamic and static discovery
  • Supports RPC and distributed objects, transparently to the client
  • Supports synchronous method call and asynchronous event handling
  • Has robust network and security mechanisms built in
• Its disadvantages are
  • Java only
  • Unusual in programming style
  • Complex to get simple examples going