2. UI Descriptors

A net.jini.lookup.entry.UIDescriptor (UIDescriptor) is a net.jini.core.lookup.Entry (Entry) that enables a UI to be associated with a service in the service item's attribute sets. A UIDescriptor holds a marshalled UI factory object in the factory field, a role type name in the role field, a toolkit package name in the toolkit field, and an attribute set that describes the factory-generated UI in the attributes field.

The UIDescriptor not only houses a marshalled UI factory that produces a UI, but also describes the produced UI to help clients decide whether or not to unmarshal the UI factory. The UI is described in the role, toolkit, and attributes fields.

Class UIDescriptor's public interface looks like this:

package net.jini.lookup.entry;

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

public class UIDescriptor extends net.jini.entry.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 {...}
}

Because the marshalled UI factory is referenced from a public field, programs can simply invoke get() directly on the marshalled object to unmarshal the factory client. Clients must ensure, however, that the class loader that loads the class files for the UI can also (likely via a parent class loader) load the class files of the service proxy with which the UI will interact. The UIDescriptor includes a convenience method named getUIFactory() to help clients unmarshal the UI factory with the proper class loader context.

The getUIFactory() method saves a reference to the current context class loader, sets the context class loader to the class loader passed as parentLoader, invokes get() on the marshalled object, then resets the context class loader to the saved reference before returning the object that get() produces.

The class loader passed to the getUIFactory() method in the parentLoader parameter should be able to load types (classes and interfaces) needed when the UI interacts with the role object, which is passed as the first parameter to any factory method. A UI role's semantic description indicates, among other things, what object should be passed to the factory as the role object. For the net.jini.lookup.ui.MainUI role, for example, the role object is the service item. Thus, to unmarshal a UI factory for a main UI, the class loader passed to getUIFactory() should be able to load types needed when the UI interacts with the service proxy contained in the service item. For example, the client could pass to getUIFactory() the class loader the client previously used to load the service proxy.

The String referenced from the toolkit field (which names the main package of the primary UI toolkit) is determined by the UI factory type. Each UI factory type's semantics should include a toolkit string, so UI providers will know what string to put in the toolkit field for their selected UI factory type. Two toolkit strings currently defined are java.awt, for graphical UIs that depend on AWT but not Swing, and javax.swing, for graphical UIs that depend on Swing (and AWT, since Swing is built on top AWT).