Step 1. Define a Factory Object

The UIFactory Interface

// In file UIFactory.java
package org.jini.ui;

public interface UIFactory extends 
              java.io.Serializable {

   Object getUI(Object serviceObject)
        throws UICreationException;
}

Exceptions Thrown by getUI()

// In file InvalidServiceClassException.java
package org.jini.ui;

public class InvalidServiceClassException 
                  extends RuntimeException {

    public InvalidServiceClassException() {
    }

    public InvalidServiceClassException(
                              String msg) {
        super(msg);
    }
}

// In file UICreationException.java
package org.jini.ui;

public class UICreationException 
                extends Exception {

    private Exception thrownException;

    public UICreationException() {
    }

    public UICreationException(
                       String msg) {
        super(msg);
    }

    public UICreationException(
                      Exception e) {
        thrownException = e;
    }

    public Exception getThrownException() {
        return thrownException;
    }
}

2: Defining a Concrete Factory Class

/*
 * PrinterJPanelFactory - 
 * An implementation of the UIFactory 
 * interface that knows to cast the service
 * object to type PrinterService
 * and instantiates and returns a 
 * new PrinterJPanel GUI object.
*/
package com.artima.printer;

import org.jini.ui.UIFactory;
import org.jini.ui.InvalidServiceClassException;
import org.jini.ui.UICreationException;
import org.printerfolks.PrinterService;

public class PrinterJPanelFactory 
                 implements UIFactory {

    public Object getUI(
                  Object serviceObject)
        throws UICreationException {

        PrinterService ps;
        try {
            ps = (PrinterService) 
                         serviceObject;
        }
        catch (ClassCastException e) {
            throw new 
             InvalidServiceClassException();
        }

        try {
            return new PrinterJPanel(ps);
        }
        catch (Exception e) {
            throw new UICreationException(e);
        }
    }
}

Step 2. Pass the Service Object to the UI

/*
 * PrinterJPanel - A GUI panel that 
 * allows the user to interact with
 * a printer across the network via a 
 * Jini service object
*/
package com.artima.printer;

import javax.swing.*;
import javax.swing.event.*;
import javax.swing.border.*;
import javax.accessibility.*;
import java.awt.*;
import java.awt.event.*;
import org.jini.ui.*;
import org.printerfolks.*;

public class PrinterJPanel 
                     extends JPanel {

  private PrinterService serviceObject;

  //...

    public PrinterJPanel(
        PrinterService serviceObject) {

      this.serviceObject = serviceObject;

        //...
    }

    //...
}

Step 3. Place the UIFactory in an Entry

// In file UIFactoryEntry.java
package org.jini.ui.entry;
import net.jini.entry.AbstractEntry;
import java.util.Map;

public class UIFactoryEntry 
     extends AbstractEntry {

    public String name;
    public String function;
    public UIFactory factory;
    public Map properties;

    UIFactoryEntry() {
    }

    UIFactoryEntry(String name, 
       String function, UIFactory factory,
        Map properties) {

        this.name = name;
        this.function = function;
        this.factory = factory;
        this.properties = properties;
    }
}

// In file ComponentFactoryEntry.java
package org.jini.ui.entry.java.awt;
import org.jini.ui.UIFactoryEntry;
import java.util.Map;

public class ComponentFactoryEntry 
              extends UIFactoryEntry {

    // Could add other public fields 
    // here that allow instances to
    // characterize themselves in a way 
    // that can be selected by
    // matching criteria in the 
    // ServiceTemplate passed to an
    // invocation of lookup() on a 
    // ServiceRegistrar.

    ComponentFactoryEntry() {
    }

    ComponentFactoryEntry(String name, 
       String function, UIFactory factory,
        Map properties) {

        super(
         name, function, factory, properties);
    }
}

// In file PanelFactoryEntry.java
package org.jini.ui.entry.java.awt;
import java.util.Map;

public class PanelFactoryEntry 
       extends ComponentFactoryEntry {

    // Could add other public fields here 
    // that allow instances to
    // characterize themselves in a way 
    // that can be selected by
    // matching criteria in the ServiceTemplate 
    // passed to an invocation of lookup() on a
    // ServiceRegistrar.

    PanelFactoryEntry() {
    }

    PanelFactoryEntry(
      String name, String function, 
                     UIFactory factory,
        Map properties) {

        super(name, function, factory, 
                           properties);
    }
}

// In file MinimumScreenSize.java
package org.jini.ui;

public class MinimumScreenSize 
    implements java.io.Serializable {

    private java.awt.Dimension minScreenSize;

    public MinimumScreenSize(
             java.awt.Dimension dim) {

        this.minScreenSize = dim;
    }

    public java.awt.Dimension 
            getMinimumScreenSize() {
        return minScreenSize;
    }
 }

Step 4. Have the Service Object Implement Identifiable

To search for an appropriate UI object, a client with sufficient resources can just use the ServiceMatches lookup(ServiceTemplate, int) method of the ServiceRegistrar to retrieve the entire attribute set of a service along with the service object and its ServiceID object. It can then search through its local copies of all the attributes to find an appropriate UI.

Many clients, however, will not want to download all the attributes. Those attributes take up memory, which can be a scarce resource in a small consumer device. In addition, downloading them may trigger unnecessary class files to be downloaded as well. (The JVM specification lets implementations load classes before they are used.) Such clients can use the Object lookup(ServiceTemplate) method of ServiceRegistrar, which, rather than returning an array of matching ServiceItems, returns only one matching service object. If more than one service matches the template passed to this lookup() version, one is selected arbitrarily and returned.

If such a resource-constrained client wants to display a UI for a service it got from calling Object lookup(ServiceTemplate), it must search through that service's attributes via methods declared in the ServiceRegistrar interface. Unfortunately, the client won't have enough information to uniquely identify the service whose object it has a local copy of. To be certain it can uniquely identify the service, the client needs the service's ServiceID. But when the client invokes lookup(), it just gets the service object, not the ServiceID. Thus, the only way this client can get the ServiceID is by asking the service and invoking a method on the service object.

For this reason, services that want to be friendly to resource-constrained clients should implement the Identifiable interface, which lets clients ask the service for its ServiceID:

package org.jini.ui;
import net.jini.core.lookup.ServiceID;

public interface Identifiable {

    ServiceID getServiceID();
}

Use Cases

A Resource-Constrained Client

1. Get a service object

   Client builds a ServiceTemplate that describes the service it desires, and invokes Object lookup(ServiceTemplate) on a ServiceRegistrar. The ServiceTemplate can include one or more UIFactoryEntry objects; these help the search to just the requested services that offer one or more UIs the client may potentially use.

2. Get the service ID

   The client makes sure the service object implements Identifiable with instanceof. If it does, the client casts the service object reference to Identifiable, and invokes getServiceID() on that reference. The client now has the service ID.

   Note that if the service object does not implement Identifiable, the client has to use the other form of lookup() to get an entire ServiceItem. This consumes more resources, but it yields a local copy of all attributes, which enables the client to search locally for an appropriate UI. Using this alternative approach may not be practical (or possible) for a resource-constrained client, which is why providers of services that these clients can be expected to request should implement Identifiable.

3. Retrieve property maps for candidate UIs

   The client builds a ServiceTemplate composed of the ServiceID object, which uniquely identifies the service, and an instance of a subclass of UIFactoryEntry, which indicates the desired UI type and potentially some desired UI characteristics. (For example, if the client is interested in a java.awt.Panel, it would create an instance of PanelFactoryEntry and put that in the ServiceTemplate.)

   Once the client has the ServiceTemplate, it invokes the getFieldValues(ServiceTemplate tmpl, int setIndex, String field) method on the ServiceRegistrar. In the tmpl argument, it passes a reference to the ServiceTemplate. In the setIndex argument, it passes zero (or whatever index the UIFactoryEntry exists in the ServiceTemplate's attr field). In the field argument, it passes the string properties.

   The client gets an array of Map objects as the return value of the getFieldValues() method invocation. Each Map object contains properties that characterize a UI whose entry matched the type specified in the ServiceTemplate. The client can then use the property maps to select an appropriate UI.

   For example, if the client has a small screen size, it may look for a minscreensize property in each Map, then compare the minimum screen size properties to find the UI object that is most suitable for the client's display capabilities. Other properties can include locales that the UI directly supports, so a client with a French-speaking user can find UIs that offer a French option. Any useful way to characterize a UI can be given a well-known property name and added to the Maps that sit in the UIFactoryEntry objects.

4. Retrieve one UIFactory

   When the client decides which Map represents the best UI for its needs, it looks up the name property on that Map. The name property should contain a String with an identical value to the String referenced by the name field of the corresponding UIFactoryEntry subclass. For example, if the name field of a JPanelFactoryEntry refers to a String with the value Bob's Groovy UI, then you should get a String with the value Bob's Groovy UI when you look up the name property on the Map contained in the properties field of that same JPanelFactoryEntry.

   Having retrieved the name property from the selected Map, the client builds a new ServiceTemplate composed of the ServiceID object and an instance of UIFactoryEntry with the name field set to the retrieved value of the name property. Then, the client once again invokes getFieldValues() on the ServiceRegistrar. It passes in its new ServiceTemplate in the tmpl argument, the appropriate index (probably zero) in the setIndex argument, and the String factory in the field argument.

   The name field of each UI factory-entry object in a particular service item's attributes array should be unique. Thus, the ServiceTemplate passed to the most recent invocation of getFieldValues() should match only the one UI factory entry that has the requested name. Therefore, getFieldValues() will return one UIFactory object. This object generates the UI object the client deemed to be most appropriate given its capabilities and user's preferences.

5. Create the UI

   Lastly, the client simply invokes getUI() on the UIFactory, passing in a reference to the service object. The getUI() method returns a new UI object. Although the type of reference is an object, the client can downcast that reference to a more specific type. If the client is looking for a UI among PanelFactoryEntrys, for example, it can downcast the reference returned by the UIFactory to java.awt.Panel.