5. UI Factories

The UI factory object should implement one or more UI factory interfaces appropriate to the type of UI generated (the factory method's return value) and the options clients have at creation time (the parameters the client can and must pass to the factory method). Factory interfaces can be implemented in many ways, but in general, factory objects should use lazy instantiation of the UI object. For example, rather than instantiating a UI object when the factory instantiates, and returning that already-instantiated UI when a factory method is invoked, a factory object should wait until a factory method is actually invoked before instantiating the UI object. Lazy instantiation lets you marshal the factory object without requiring the UI object's image to be included in the UI factory's marshalled image.

UI factories define methods that indicate by their return type the generated UI's Java type and indicate by their parameters the objects and primitive values that the client can and must supply to the factory. The first parameter to any UI factory method is a role object. The UI's role determines this object's category (but not the type). As used here, category means how the client program obtains the role object. For example, a role might specify that its role object is the service item, the service proxy, or an object obtained by invoking a method on the service proxy. The UI role describes how the client acquires the object that must be passed as the first parameter to the factory method. For example, the MainUI role's semantics indicate that the role object is the service item.

You should write UI factories such that their factory methods can be invoked multiple times. A client may wish to show a user the same UI several times, and therefore may invoke a factory method on the same factory object multiple times. Each time the factory method is invoked, it should produce and return a new UI object copy.

The Jini Service UI API's first version defines eight factory interfaces:

• DialogFactory: Returns an instance of class java.awt.Dialog, or one of its subclasses, that depends on the AWT, not the Swing, libraries
• FrameFactory: Returns an instance of class java.awt.Frame, or one of its subclasses, that depends on the AWT, not the Swing, libraries
• JComponentFactory: Returns an instance of class javax.swing.JComponent, or one of its subclasses, that depends on both the AWT and Swing libraries
• JDialogFactory: Returns an instance of class javax.swing.JDialog, or one of its subclasses, that depends on both the AWT and Swing libraries
• JFrameFactory: Returns an instance of class javax.swing.JFrame, or one of its subclasses, that depends on both the AWT and Swing libraries
• JWindowFactory: Returns an instance of class javax.swing.JWindow, or one of its subclasses, that depends on both the AWT and Swing libraries
• PanelFactory: Returns an instance of class java.awt.Panel, or one of its subclasses, that depends on the AWT, but not the Swing, libraries
• WindowFactory: Returns an instance of class java.awt.Window, or one of its subclasses other than Frame or Dialog, that depends on the AWT, not the Swing, libraries

Future incarnations of the Jini Service UI Specification or any other party may define additional UI factory interface types. The fully qualified names of UI factory interface types should, as with any other type, follow the recommended naming convention for unique packages outlined in the Java Language Specification:

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as sun.com. You then reverse this name, component by component, to obtain, in this example, com.sun, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names.

Here's an example UI factory interface:

package net.jini.lookup.ui.factory;

import javax.swing.JFrame;

public interface JFrameFactory extends java.io.Serializable {

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

    JFrame getJFrame(Object roleObject);
}

Given that only one toolkit field exists, all UIFactory interfaces implemented by a UI factory class must have the same toolkit.

5.1. Defining New Factory Types

Although anyone can define new factory types, to prevent a chaotic explosion of factory types, you should define new factory types with the utmost care. In general, new factory types will be justified only when new UI toolkits appear on the scene. If possible, new factory types should be agreed upon by the Jini Community and placed into the net.jini.lookup.ui.factory package so they are easy to find. For example, if a toolkit is defined for speech-only UIs, a set of factory methods for speech-only UIs could be added to those already in net.jini.lookup.ui.factory. If a graphical toolkit is defined for extremely small screens, a set of factory methods for small-screen UIs could be added to those already in net.jini.lookup.ui.factory.

A UI factory must be an interface, and each method in the interface must take an Object called the roleObject as its first parameter. Other than the role object, nothing should be passed to a factory method except information or context required by the toolkit.

It is recommended that all UI factory interfaces include two compile time String constants:

• TOOLKIT: Gives the package name of the produced UI's toolkit, which should appear in the UI descriptor's toolkit field
• TYPE_NAME: Gives the fully qualified string type name of the UI factory, as it should appear in UIFactoryTypes attributes

Such convenience constants not only help reduce typing and increase code readability, they also leverage compile-time type checking to help minimize the chance of typographical errors in toolkit strings and type names added to UIFactoryTypes attributes.