content/release-doc/current/specs/html/serviceui-spec.html - river-site - Git at Google

 <!--
  ! Licensed to the Apache Software Foundation (ASF) under one
  ! or more contributor license agreements.  See the NOTICE file
  ! distributed with this work for additional information
  ! regarding copyright ownership. The ASF licenses this file
  ! to you under the Apache License, Version 2.0 (the
  ! "License"); you may not use this file except in compliance
  ! with the License. You may obtain a copy of the License at
  !
  !      http://www.apache.org/licenses/LICENSE-2.0
  !
  ! Unless required by applicable law or agreed to in writing, software
  ! distributed under the License is distributed on an "AS IS" BASIS,
  ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ! See the License for the specific language governing permissions and
  ! limitations under the License.
  !-->
 <HTML><BODY>
 <h1>The ServiceUI API Specification - Version 1.1</h1>

 <h1>Revision History</h1>

 <ul>
  <li>1.1a - Sat., June 4, 2005: Released 1.1a with no changes to the code or this specification other
 than changing the license from the Sun Community Source License (SCSL) to Apache License, Version 2.0.
  <li>1.1 - Thu., October 14, 2002: Released 1.1beta4 as 1.1 with no changes to the code or this specification.
  <li>1.1beta4 - Thu., July 11, 2002: Made a
     1.1beta4 release in which the doPrivileged statements are removed from
     the <code>UIDescriptor.getUIFactory</code> method.
     Removed the sentence, "Because setting
     and getting the context class loader is a privileged operation, the <code>getUIFactory()</code>
     method wraps those operations in <code>AccessController.doPrivileged()</code> calls," from the
     description of <code>getUIFactory</code> in section 2 of this specification.

  <li>1.1beta3 - Thu., Mar. 7, 2002: Many changes to accompany the 1.1beta3 release
      <ul>
      <li>Added Section 9, Consistent Serialized Forms, which
      describes a slight narrowing of the contracts of the constructors of <code>UIDescriptor</code>,
      <code>Locales</code>, <code>UIFactoryTypes</code>, and <code>RequiredPackages</code>. These
      constructors are now required to copy the contents of the passed <code>Set</code> or
      <code>Map</code> to an unmodifiable version that has a consistent serialized form
      across all VMs.
      <li>Changed the implementation and contract of <code>AccessibleUI.hashcode</code>
      so that it returns the hashcode of its fully qualified <code>String</code> name, rather than
      the hashcode of its <code>Class</code> instance.
      <li>Added <code>UIDescriptorBean</code> to <code>net.jini.lookup.entry</code>, as suggested
      by the Jini Lookup Attributes Schema specification.
      <li>Theresa Gonzales edited the entire spec for English, and I went over it again after that. Lots
      of minor changes to clarify sentences, but no change in semantics.
     <li>Changed "service object" to "service proxy," to tow the line with
         commonly used Jini jargon.
     <li>Modified the Javadoc of <code>MainUI</code>,  <code>AdminUI</code>,
          and <code>AboutUI</code> to match the semantics given in the
          specification. Originally (prior to the 1.0 release), these role
          interfaces defined their role object to be exactly the service item.
          Ken Arnold requested we say that the service item must be accepted
          as the role object, which yields more flexibility. Although a
          service item is required to always work when passed as the role
          object to factory methods for main, admin, and about UIs, other
          objects may also work. I made this change back then to the
          specification, but forgot to change the Javadoc comments. The
          specification and the Javadoc comments are now in sync.
      </ul>
  <li>1.1 - Wed., Aug. 22, 2001:
      Fixed two method names in <code>JDialogFactory</code> that were both incorrectly
      named <code>getDialog()</code>
      in ServiceUI 1.0. The methods are now correctly named <code>getJDialog()</code>.
      Added <code>serialVersionID</code>s
      to all classes in the API in order to accelerate deserialization. Improved
      javadoc comments: added missing serial, author, param, throws, and return
      tags, as well as added clarifying javadoc text where it seemed helpful.
      Added flat javadoc documentation to the end of Service UI API Specification
      to make sure the API's semantics are specified in detail in the
      specification itself.
  <li>1.0 - Mon., Apr. 24, 2000:
      Only changed the specification's version number from 0.9.2 to 1.0 in order
      to match the version number of the code now released under the Sun
      Community Source License (SCSL).
  <li>0.9.2 - Sun., Mar. 12, 2000:
      Fixed typo: Changed <code>Administratable</code>
      to <code>Administrable</code>.
      Fixed grammar: In last paragraph of section 3.1, changed &quot;had&quot;
      to &quot;had had.&quot;
  <li>0.9.1 - Mon., Mar. 6, 2000:
      Only changed the specification's version number from 0.9.0 to 0.9.1 to
      match the code's revised version number. Fixed some bugs in version 0.9.1
      code, which are described on the Code Access
      page: http://www.artima.com/jini/serviceui/CodeAccess.html.
  <li>0.9.0 - Tue., Feb. 22, 2000:
      Fixed four grammar typos, without changing specification meaning. In
      section 3.2, paragraph 2, the main UI's associated service item <i>must be
      accepted</i> as the role object, rather than <i>required</i> as the role
      object. In section 3.3, paragraph 2, the admin UI's associated service
      item <i>must be accepted</i> as the role object, rather than <i>required</i>
      as the role object. In section 3.4, paragraph 2, the about UI's associated
      service item <i>must be accepted</i> as the role object, rather than <i>required</i>
      as the role object. In section 3.7, paragraph 2, changed &quot;simply
      shouldn't extend&quot; to &quot;simply shouldn't <i>in general</i>
      extend.&quot; In section 3.7, added paragraph 3, which starts,
      &quot;Nevertheless, if some party....&quot;
  <li>0.8.1 - Wed., Feb. 9, 2000:
      In <code>MainUI</code>,
      <code>AdminUI</code>,
      and <code>AboutUI</code>,
      changed constant <code>role</code>
      to <code>ROLE</code>.
      In all factories, changed <code>toolkit</code> to <code>TOOLKIT</code> and <code>typeName</code>
      to <code>TYPE_NAME</code>.

  <li>0.8.0 - Tue., Feb. 8, 2000:
      One last pass. Mostly minor tweaks except for the last few sections, which
      had some major surgery.
  <li>0.7 - Mon., Feb. 7, 2000:
      Reviewed and cleaned up a lot of text. A few sections near the end are
      still a bit rough. Will post version 0.8 tonight, which will serve as the
      starting point for the two-week ServiceUI review phase.
  <li>0.6 - Sat., Feb. 5, 2000:
      Fleshed out remaining sections, though some of it is rough.
  <li>0.5 - Thu., Feb. 3, 2000:
      Fleshed out material in most sections. Added a new section on third-party
      UIs.
  <li>0.4 - Wed., Feb. 2, 2000:
      Incorporated changes decided upon with Jini architects at the 2nd meeting.
      Document now offers a good general overview.
  <li>0.3 - Mon., Jan. 31, 2000:
      Fixed a few typos in Main UI semantics.
  <li>0.2 - Sun., Jan. 30, 2000:
      Added introduction, revised semantics of Main/Admin/About UI roles,
      dropped <code>Flavor</code>
      and <code>FlavorSelectorUI</code>.

  <li>0.1 - Fri., Jan. 28, 2000:
      First version.
 </ul>

 <P><B>splitwebpage</B>
 <H1>Table of Contents</H1>

 <OL>
 <LI>Introduction

 <UL>
 <LI>1.1. Direct-Use Clients
 <LI>1.2. User Adapters
 <LI>1.3. Jini Service UIs
 </UL>

 <LI>UI Descriptors
 <LI>UI Roles

 <UL>
 <LI>3.1. Displaying Roles to Users
 <LI>3.2. The <CODE>net.jini.lookup.ui.MainUI</CODE> Role
 <LI>3.3. The <CODE>net.jini.lookup.ui.AdminUI</CODE> Role
 <LI>3.4. The <CODE>net.jini.lookup.ui.AboutUI</CODE> Role
 <LI>3.5. Defining New Role Types
 <LI>3.6. Working with Existing Role Types
 <LI>3.7. Choosing Superinterfaces for New Role Types
 </UL>

 <LI>UI Attributes

 <UL>
 <LI>4.1. The <CODE>AccessibleUI</CODE> Attribute
 <LI>4.2. The <CODE>Locales</CODE> Attribute
 <LI>4.3. The <CODE>RequiredPackages</CODE> Attribute
 <LI>4.4. The <CODE>UIFactoryTypes</CODE> Attribute
 </UL>

 <LI>UI Factories

 <UL>
 <LI>5.1. Defining New Factory Types
 </UL>

 <LI>UI Objects

 <UL>
 <LI>6.1. What to Provide
 <LI>6.2. Avoiding Service-Level Data and Client Context

 </UL>

 <LI>Adding Third-Party UIs
 <LI>Evolution and Prior Knowledge
 <LI>Consistent Serialized Forms

 <LI>Package <CODE>net.jini.lookup.entry</CODE>
 <UL>
 <LI>10.1. Class <CODE>net.jini.lookup.entry.UIDescriptor</CODE>
 <LI>10.2. Class <CODE>net.jini.lookup.entry.UIDescriptorBean</CODE>
 </UL>

 <LI>Package <CODE>net.jini.lookup.ui</CODE>
 <UL>
 <LI>11.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui</CODE>
 <LI>11.2. Summary of Classes In Package <CODE>net.jini.lookup.ui</CODE>
 <LI>11.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui</CODE>
 <LI>11.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui</CODE>
 <LI>11.5. Interface <CODE>net.jini.lookup.ui.AboutUI</CODE>
 <LI>11.6. Interface <CODE>net.jini.lookup.ui.AdminUI</CODE>
 <LI>11.7. Interface <CODE>net.jini.lookup.ui.MainUI</CODE>
 </UL>

 <LI>Package <CODE>net.jini.lookup.ui.factory</CODE>
 <UL>
 <LI>12.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui.factory</CODE>
 <LI>12.2. Summary of Classes In Package <CODE>net.jini.lookup.ui.factory</CODE>
 <LI>12.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui.factory</CODE>
 <LI>12.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui.factory</CODE>
 <LI>12.5. Interface <CODE>net.jini.lookup.ui.factory.DialogFactory</CODE>
 <LI>12.6. Interface <CODE>net.jini.lookup.ui.factory.FrameFactory</CODE>
 <LI>12.7. Interface <CODE>net.jini.lookup.ui.factory.JComponentFactory</CODE>
 <LI>12.8. Interface <CODE>net.jini.lookup.ui.factory.JDialogFactory</CODE>
 <LI>12.9. Interface <CODE>net.jini.lookup.ui.factory.JFrameFactory</CODE>
 <LI>12.10. Interface <CODE>net.jini.lookup.ui.factory.JWindowFactory</CODE>
 <LI>12.11. Interface <CODE>net.jini.lookup.ui.factory.PanelFactory</CODE>
 <LI>12.12. Interface <CODE>net.jini.lookup.ui.factory.WindowFactory</CODE>
 </UL>

 <LI>Package <CODE>net.jini.lookup.ui.attribute</CODE>
 <UL>
 <LI>13.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui.attribute</CODE>
 <LI>13.2. Summary of Classes In Package <CODE>net.jini.lookup.ui.attribute</CODE>
 <LI>13.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui.attribute</CODE>
 <LI>13.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui.attribute</CODE>
 <LI>13.5. Class <CODE>net.jini.lookup.ui.attribute.AccessibleUI</CODE>
 <LI>13.6. Class <CODE>net.jini.lookup.ui.attribute.Locales</CODE>
 <LI>13.7. Class <CODE>net.jini.lookup.ui.attribute.RequiredPackages</CODE>
 <LI>13.8. Class <CODE>net.jini.lookup.ui.attribute.UIFactoryTypes</CODE>
 </UL>
 </OL>

 <P><B>splitwebpage</B>
 <h1>1. Introduction</h1>

 <p>Traditionally, desktop applications are designed with a built-in user
 interface (UI). The code for the application's UI is often highly coupled to
 the code that implements the application's functionality. Over time, tentacles
 of UI code may burrow deep into functionality code, and tentacles of
 functionality code may burrow back into UI code. In the traditional desktop
 application, therefore, the UI code and functionality code are usually
 inseparable, married for all eternity. </p>

 <p>Jini's service proxy architecture encourages you to think differently about
 UI and functionality: </p>

 <ul>
  <li>UI and functionality should
      be separate
  <li>Both UI and functionality are
      encapsulated in objects
  <li>The coupling point between UI
      code and functionality code should be the service proxy interface
 </ul>

 <p>A Jini service proxy should represent the service's pure functionality, expressed
 via the methods of its object interface. For example, the service proxy
 interface for a toaster service should express or model the conceptual toaster
 service's functionality -- the interface should say &quot;what it means to be a
 toaster.&quot; The service proxy should not supply human access to the toaster
 service; a separate UI object should provide such access. </p>

 <h2>1.1. Direct-Use Clients</h2>

 <p>One reason for excluding the UI from the service proxy is to enable client
 programs (clients) to access the service without human intervention or
 supervision. Clients written by programmers who knew about a particular service
 proxy's (potentially well-known or standard) interface can interact with a
 service directly. As Figure 1 shows, client code can interact directly with a
 service by invoking the methods in the service proxy interface. Such a client
 is called a <i>direct-use</i> client, because its programmers, based on their
 knowledge of the service proxy interface, can write code that uses the service
 directly via that interface. </p>

 <P>
 <CENTER>
 <IMG src="images/servonly.gif">
 <BR clear="all">
 <STRONG>Figure 1. A "direct-use" client talks to a service through its object
 interface.</STRONG>
 </CENTER>

 <p>Direct-use clients need not be completely devoid of a user. For example, a
 user could operate a device that acts as a direct-use client in certain cases.
 If the user requested that the device save some data in a file, the device
 could acquire a storage service proxy and directly invoke methods on that
 object to save data in a file, without further user intervention. In this case,
 the user-operated device acts as a direct-use client of storage services,
 because the device's programmers had prior knowledge of the storage service proxy
 interface and used that knowledge to program the device to use those services
 directly. </p>

 <p>On the other hand, direct-use clients can also function independently of
 human supervision or intervention. Such clients act as <i>autonomous agents</i>,
 which decide for themselves when to enlist a service's help. When an autonomous
 agent uses a service, it invokes the methods offered by the service proxy
 interface directly. Thus, an autonomous agent's programmers must have prior
 knowledge of the service proxy interfaces their agent uses. (Although the
 human programmer actually has the prior knowledge when he or she writes the
 client code, in this document the code itself will often be said to have prior
 knowledge.) </p>

 <h2>1.2. User Adapters</h2>

 <p>When you design a Jini service, you should attempt to capture the service's
 entire functionality in the service proxy interface. To access any aspect of
 your service, a direct-use client should only need a reference to the service
 proxy. The service proxy should not include any code that defines a user
 interface to the service, just code that provides the service functionality at
 the method invocation level. </p>

 <p>To provide a user interface for the service, you should encapsulate the user
 interface code in a separate UI object. As Figure 2 shows, a UI object grants a
 user access to some aspect of a Jini service. Think of a service UI object as a
 <i>user adapter</i> -- an object that <em>adapts</em> a service proxy
 interface that a human user cannot interact with directly into one a human user
 can interact with directly. Sitting between the service proxy interface and a
 human user, a UI object can grant the user access to a service. </p>

 <P>
 <CENTER>
 <IMG src="images/servnUI.gif">
 <BR clear="all">
 <STRONG>Figure 2. A user interacts with a service via a UI object.</STRONG>
 </CENTER>

 <p>A UI object can represent a graphical UI component, such as an AWT <code>Frame</code> or Swing
 <code>JPanel</code>,
 but doesn't necessarily need to be graphical. A UI object could also represent
 a speech interface, a text interface, a speech and graphic combination, or a
 3D-immersive world. (The UI object is called <i>UI object</i>, rather than <i>GUI
 object </i>or <i>view object</i>, because the object represents UI components
 in general, not just graphical UI components.) Any kind of Jini Service UI,
 including a 3D-immersible world with speech and virtual text display, should be
 represented by a UI object, which is distinct from the service proxy. </p>

 <p>One advantage of this architecture, in which UI and functionality are
 separated, is that you can associate multiple UIs with the same service.
 Associating multiple UIs with one service lets you tailor different UIs for
 clients that have particular UI capabilities, such as Swing or speech. Clients
 can then choose the UI that best fits their user interface capabilities. In
 addition, you may want to associate different UIs that serve different
 purposes, such as a main UI or an administration UI, with a service. Often, you
 may need to associate multiple UIs with one Jini service, where each UI has a
 particular purpose and targets a particular set of client capabilities. </p>

 <h2>1.3. Jini Service UIs</h2>

 <p>This specification standardizes how UI providers associate a UI (user
 adapter) object with a Jini service, and shows how client programs can find the
 best-fit UI among multiple UIs associated with the same service. To associate a
 UI with a Jini service, UI providers (primarily service providers, but also
 possibly third parties) must supply three items: </p>

 <ul>
  <li>The UI itself
  <li>A UI factory that produces
      the UI
  <li>A UI descriptor that
      describes the UI
 </ul>

 <p class=MsoNormal>A <i>UI factory</i> is an object that has one or more
 factory methods that produce and return a UI object. A <i>UI descriptor</i>, an
 instance of <code>net.jini.lookup.entry.UIDescriptor</code>
 (<code>UIDescriptor</code>),
 serves as a container for the UI factory and other objects that describe the UI produced by the factory.
 Because <code>UIDescriptor</code>
 implements <code>net.jini.core.entry.Entry</code>
 (<code>Entry</code>),
 you can include a <code>UIDescriptor</code>
 in a Jini service item's attribute sets array, thereby associating the UI with
 the service. A UI descriptor contains four public fields: </p>

 <ul>
  <li><code>factory</code>: A reference to a <code>java.rmi.MarshalledObject</code>
      that contains the UI factory object in marshalled form
  <li><code>attributes</code>: A <code>java.util.Set</code>
      of attribute objects that describe the factory-produced UI
  <li><code>toolkit</code>: A <code>String</code>
      that names the main package of the UI toolkit the UI requires
  <li><code>role</code>: A <code>String</code>
      that gives the fully qualified name of a Java interface type that
      represents the UI's role
 </ul>

 <p>The <code>attributes</code>,
 <code>toolkit</code>,
 and <code>role</code>
 fields' purpose is to describe the UI produced by the marshalled UI factory.
 Using these fields, clients can choose from multiple UIs associated with a
 service. Once they select a UI object, clients can use the other field, <code>factory</code>, to
 create the object. </p>

 <p>To associate a UI with a Jini service, the UI provider must first fill a UI
 descriptor with a role <code>String</code>,
 a toolkit <code>String</code>,
 an attribute set, and a marshalled UI factory. The UI provider must then place
 the UI descriptor in the attribute sets of the Jini service's service item. </p>

 <p>A UI's role indicates both its purpose and its role-related semantics. Each
 UI role is defined as a Java interface type, which UI objects playing that role
 implement. The <code>role</code>
 field references a <code>String</code>
 whose value is the role interface type's fully qualified name. For example, a <code>net.jini.lookup.ui.MainUI</code>
 role UI provides general access to a service. A <code>net.jini.lookup.ui.AdminUI</code> role
 UI enables a user to administer a service. Although most UI object semantics of
 interest to the client program are defined by the UI factory's return type,
 some semantics may be tied to the role. For example, for a role that represents
 a user dialog, the role interface might include methods that let the client
 determine the dialog's result. </p>

 <p>The UI descriptor's <code>attributes</code>
 field holds a reference to a <code>java.util.Set</code> of serializable objects that contain
 information about the UI the descriptor represents. These objects can be of any
 class, so long as they are serializable. Clients can search through the
 attributes set for attribute types about which they have prior knowledge. The
 objects can then help the client decide whether or not to use the
 descriptor-represented UI. Several attribute classes, defined in the <code>net.jini.lookup.ui.attribute</code>
 package, are described later in this document. </p>

 <p>The <code>toolkit</code>
 field facilitates matching when querying the Jini lookup service. For example,
 if a client seeks all services that have main UIs working with the Swing
 toolkit, it could form a <code>net.jini.core.lookup.ServiceItem</code>
 (<code>ServiceItem</code>)
 whose <code>attributeSetTemplates</code>
 array includes a UI descriptor template. If the UI descriptor template's <code>factory</code> and <code>attributes</code>
 fields are set to <code>null</code>,
 the <code>role</code>
 field is set to <code>net.jini.lookup.ui.MainUI</code>,
 and <code>toolkit</code>
 field is set to <code>javax.swing</code>,
 the lookup would only return services that have at least one main UI for Swing.
 </p>

 <p>The <code>factory</code>
 field contains the UI factory object inside a <code>MarshalledObject</code> so that you
 can place the class files for the factory and the UI it produces in a different
 codebase than the service item containing the UI descriptor. By placing the
 class files for UI factories and UI objects in separate codebases than that of
 the service item, clients can download a service item without downloading all
 the JAR files containing those class files, most or all of which the client may
 never use. Only if the client attempts to use a UI will it need to unmarshal
 the UI factory; this would trigger the downloading of the JAR file containing
 the factory class files, and possibly the class files for the factory-generated
 UI. </p>

 <p>To use a UI, a client program must have prior knowledge of both the UI
 factory type (including, of course, the UI object type returned by its factory
 methods) and the UI role type. These types define the UI object semantics,
 which client programmers must understand before they can write code to interact
 properly with the UI. A client doesn't need prior knowledge of all the
 attributes types that appear in the attributes set. To the extent the client
 has prior knowledge of the attribute types, it can use that knowledge to select
 an appropriate UI from multiple UIs associated with a service. </p>

 <P><B>splitwebpage</B>
 <h1>2. UI Descriptors</h1>

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

 <p>The <code>UIDescriptor</code>
 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 <code>role</code>, <code>toolkit</code>, and <code>attributes</code>
 fields. </p>

 <p>Class <code>UIDescriptor</code>'s
 public interface looks like this: </p>

 <PRE>
 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 {...}
 }
 </PRE>

 <p>Because the marshalled UI factory is referenced from a public field, programs
 can simply invoke <code>get()</code>
 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 <code>UIDescriptor</code> includes a convenience
 method named <code>getUIFactory()</code>
 to help clients unmarshal the UI factory with the proper class loader context. </p>

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

 <p>The class loader passed to the <code>getUIFactory()</code> method in the <code>parentLoader</code>
 parameter should be able to load types (classes and interfaces) needed when the
 UI interacts with the <i>role object</i>, 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 <code>net.jini.lookup.ui.MainUI</code>
 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 <code>getUIFactory()</code> 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 <code>getUIFactory()</code>
 the class loader the client previously used to load the service proxy. </p>

 <p>The <code>String</code>
 referenced from the <code>toolkit</code>
 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 <code>toolkit</code> field
 for their selected UI factory type. Two toolkit strings currently defined are <code>java.awt</code>, for
 graphical UIs that depend on AWT but not Swing, and <code>javax.swing</code>,
 for graphical UIs that depend on Swing (and AWT, since Swing is built on top
 AWT). </p>

 <P><B>splitwebpage</B>
 <h1>3. UI Roles</h1>

 <p>The <code>UIDescriptor's
 role</code> field gives the fully qualified name of the interface that
 represents the role of the UI the marshalled UI factory generates. If the
 client program unmarshals the UI factory and invokes a factory method, the UI
 the factory method returns must implement the role interface that <code>role </code>
 specifies.
 </p>

 <p>For a client program to use a UI, the client must have prior knowledge of
 the UI semantics, a portion of which the UI's role type defines. Thus, for a
 client to use a UI, the client must understand the semantics of the type whose
 fully qualified name appears in the <code>role</code> field of that UI's <code>UIDescriptor</code>. </p>

 <p>For example, three role types defined in the <code>net.jini.lookup.ui</code> package by
 the Jini Service UI Specification are <code>MainUI</code>, for a main UI to a Jini
 service; <code>AdminUI</code>,
 for an administration UI; and <code>AboutUI</code> for an about UI. Future incarnations of
 the Jini Service UI Specification, individual Jini service API specifications,
 or any other party may define other role types. The UI role types' fully
 qualified names should, as with any other type, follow the recommended naming
 convention for unique packages outlined in the Java Language Specification: </p>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:.5in'>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. </p>

 <p>For example, printers in general don't have a main UI, but they may have a
 UI for printer setup, a UI for print job setup, and a UI for administering the
 printer. The Printer working group, therefore, could define two role types as
 part of its Printer API definition, one for printer setup and one for print job
 setup. (The printer's administration UI could likely use the existing <code>net.jini.lookup.ui.AdminUI</code>
 role.) The Printer working group would start its role type names with a package
 prefix it has either received or obtained control over. For example, if the
 Jini Community grants the Printer working group the right to place its APIs in
 the <code>net.jini.print</code>
 package, the group could name its <code>role</code> types: <code>net.jini.print.ui.PrinterSetup</code>
 and <code>net.jini.print.ui.PrintJobSetup</code>.
 Each working group or other entity that defines Jini Service APIs can include,
 as part of its specification, any new UI role types useful in the context of
 its service. </p>

 <h2>3.1. Display Roles to Users</h2>

 <p>As the strings referenced from the <code>role</code> field are Java type names, they
 should only be manipulated by client programs. Users should not view them. A
 client may, nevertheless, display localized strings representing roles about
 which the client has prior knowledge. </p>

 <p>For example, imagine a Jini browser client shows a service list using icons
 and names provided by <code>net.jini.lookup.entry.ServiceType</code>
 (<code>ServiceType</code>)
 entries. Such a Jini browser could, when the user double-clicks on a service
 icon or name, attempt to display a <code>MainUI</code> for the service. In addition,
 such a Jini browser could, when the user right-clicks on a service icon or
 name, pop up a list of verb strings, one for each UI role the service offers in
 a form the client believes it can use. For example, imagine that the user
 right-clicked, among the UIs offered by the service, three <code>java.swing.JFrame</code>
 (<code>JFrame</code>)
 UIs (produced by <code>net.jini.lookup.ui.factory.JFrameFactory</code>s);
 one for each of <code>net.jini.lookup.ui</code>
 package's three defined roles: <code>MainUI</code>, <code>AdminUI</code>, and <code>AboutUI</code>. If
 the client can use <code>JFrame</code>s,
 the client could display three verbs on the pop-up list when the user
 right-clicks. In the US-English locale, the verb strings could be: <code>&quot;Open...&quot;</code>,
 <code>&quot;Administer...&quot;</code>,
 and <code>&quot;About...&quot;</code>.
 If the user selects <code>About...</code>,
 the client could display the <code>AboutUI</code> <code>JFrame</code>. </p>

 <p>Note that the service did not provide the strings shown to the user -- <code>&quot;Open...&quot;</code>,
 <code>&quot;Administer...&quot;</code>,
 and <code>&quot;About...&quot;</code>.
 The developers of the Jini browser client decided upon these strings. Given
 that these developers had prior knowledge of the <code>MainUI</code> role, they were able to
 decide that, in their client, <code>&quot;Open&quot;</code> would be a sensible verb string
 for <code>MainUI</code>s
 in the US-English locale. Of course, those developers may have selected other
 verb strings for other locales. German users of the same browser, for example,
 could potentially encounter the verb string <code>&quot;Jetzt Geht's Los...&quot;</code> for <code>MainUI</code>s, <code>&quot;Was Ist Das
 Ding...&quot;</code> for <code>AboutUI</code>s, and <code>&quot;Spielen Sie Mit Die Viele Kleine Nummern...&quot;</code>
 for <code>AdminUI</code>s.
 </p>

 <p>Because the client program, not the Jini service, provides the verb strings,
 the client will be unable to show a verb in its list for any role about which
 it did not have prior knowledge. Thus, if the user right-clicks a service that
 also offers a <code>JFrame</code>
 UI with the role <code>net.jini.blender.ui.FrappeUI</code>,
 the client will be able to display a localized string for that UI in its verb
 list only if the client's developers had had prior knowledge of that role. If
 the client's programmers did not endow the program with prior knowledge of <code>FrappeUI</code>s, the
 client will not be able to list a verb for that UI in its pop-up, and therefore
 the user will not be able to select it. This prior-knowledge requirement is
 intentional, because as mentioned previously, the role defines a portion of the
 UI's semantics. Before the client program can properly use a UI, it must have
 prior knowledge of the role interface. If a client doesn't know how to use a
 UI, then letting the user select that UI makes no sense.</p>

 <h2>3.2. The <code>net.jini.lookup.ui.MainUI</code>
 Role</h2>

 <p><code>net.jini.lookup.ui.MainUI</code>
 (<code>MainUI</code>)
 is a UI role interface implemented by main UIs, which enable client programs to
 grant users general access to a service. If a UI descriptor's UI factory
 produces a UI that implements this interface (i.e., produces a main UI), the UI
 descriptor's <code>role</code>
 field must reference a <code>String</code>
 with the value <code>net.jini.lookup.ui.MainUI</code>.
 </p>

 <p>The first parameter of any factory method declared in a UI factory type is a
 role object. Any factory method that produces a main UI must accept as the role
 object the service item (the <code>net.jini.core.lookup.ServiceItem</code>) of the service
 associated with the main UI. </p>

 <p>Main UIs should let clients configure them before they begin. For example,
 main UIs produced by <code>FrameFactory</code>,
 <code>JFrameFactory</code>,
 <code>WindowFactory</code>
 and <code>JWindowFactory</code>
 (all members of the <code>net.jini.lookup.ui.factory</code>
 package) should not be visible when they return from the factory method. This
 allows clients to set the UI's position and size, for example, before making
 the UI visible by invoking <code>setVisible(true)</code> on the UI. </p>

 <p>A client should be able to invoke a main UI factory method multiple times
 sequentially. In other words, if a user uses a service via a main UI, then
 exits, and then double-clicks once again on the service icon, the client can
 simply invoke a UI factory method again, and acquire another main UI for the
 same service. Therefore, you should write main UIs so that they work regardless
 of the service proxy's state when the main UI is created. </p>

 <p>It is recommended that clients use multiple main UIs for the same service
 only sequentially, and avoid creating for the same service proxy multiple main
 UIs that operate concurrently with one another. But because some clients may
 create and use multiple main UIs simultaneously for the same service proxy,
 service and main UI providers should program defensively to ensure that
 multiple main UIs for the same service proxy will all work together
 concurrently. </p>

 <p>Here's the <code>net.jini.lookup.ui.MainUI</code>
 tag interface: </p>

 <PRE>
 package net.jini.lookup.ui;

 public interface MainUI {

     String ROLE = "net.jini.lookup.ui.MainUI";
 }
 </PRE>

 <h2>3.3. The <code>net.jini.lookup.ui.AdminUI</code>
 Role</h2>

 <p><code>net.jini.lookup.ui.AdminUI</code>
 (<code>AdminUI</code>)
 is a UI role interface implemented by admin UIs, which enable users to
 administer a service. If a UI descriptor's UI factory produces a UI that implements
 this interface (i.e., produces an admin UI), the UI descriptor's <code>role</code> field must reference a <code>String</code>
 with the value <code>&quot;net.jini.lookup.ui.AdminUI&quot;</code>.
 </p>

 <p>The first parameter of any factory method declared in a UI factory type is a
 role object. Any factory method that produces an admin UI must accept as the
 role object the service item (the <code>net.jini.core.lookup.ServiceItem</code>) of
 the service associated with the main UI. </p>

 <p>Admin UIs have precisely the same semantics as main UIs. The only difference
 is their purpose. Here's the <code>net.jini.lookup.ui.AdminUI</code> interface: </p>

 <PRE>
 package net.jini.lookup.ui;

 public interface AdminUI {

     String ROLE = "net.jini.lookup.ui.AdminUI";
 }
 </PRE>

 <h2>3.4. The <code>net.jini.lookup.ui.AboutUI</code>
 Role</h2>

 <p class=MsoNormal><code>net.jini.lookup.ui.AboutUI</code>
 (<code>AboutUI</code>)
 is a UI role interface implemented by about UIs, which enable users to view (or
 in some way experience) information about a service. If a UI descriptor's UI
 factory produces a UI that implements this interface (i.e., produces an about
 UI), the UI descriptor's <code>role</code>
 field must reference a <code>String</code>
 with the value <code>&quot;net.jini.lookup.ui.AboutUI&quot;</code>.
 </p>

 <p>The first parameter of any factory method declared in a UI factory type is a
 role object. Any factory method that produces an about UI must accept as the
 role object the service item (the <code>net.jini.core.lookup.ServiceItem</code>) of
 the service associated with the main UI. </p>

 <p>About UIs have precisely the same semantics as main UIs. The only difference
 is their purpose. Here's the <code>net.jini.lookup.ui.AboutUI</code> interface: </p>

 <PRE>
 package net.jini.lookup.ui;

 public interface AboutUI {

     String ROLE = "net.jini.lookup.ui.AboutUI";
 }
 </PRE>

 <h2>3.5. Defining New Role Types</h2>

 <p>As mentioned previously, any party may define new role interfaces. New UI
 role interfaces will likely be defined in conjunction with new Jini Service API
 definitions, and many of those roles will likely represent service-specific
 dialogs with users. As used here, a <i>dialog</i> is a short conversation with
 the user, usually to obtain some information from the user. Although for
 graphical toolkits, a dialog is often implemented with a dialog box, such as
 AWT's <code>Dialog</code>
 or Swing's <code>JDialog</code>,
 the term <i>dialog</i> is used here in the generic sense, not strictly in the
 graphical sense. Service-specific dialog UIs will enable clients to enlist a
 user's help at various points throughout an otherwise direct use of a service. </p>

 <p>As an example, consider a user asking a word processor that has prior
 knowledge of a well-known Jini Printer API to print a document. (Note that the
 types appearing in this example were invented for illustration purposes. At the
 time of this writing, the Jini Printer Service API had not been finalized.) To
 print via the Jini Print Service API, the word processor first obtains a <code>net.jini.print.service.PrintService</code>
 (<code>PrintService</code>)
 object and invokes <code>createPrintJob()</code>
 on that object to obtain a <code>net.jini.print.job.PrintJob</code> (<code>PrintJob</code>)
 object. A purely direct-use client must do two things with the <code>PrintJob</code>
 object -- configure the print job and supply the print data -- before invoking <code>close()</code> on the
 print job, thereby queuing the printing job. Although the word processor could
 potentially do both jobs directly, it may not have prior knowledge of the portion of the <code>PrintJob</code>
 object's interface that lets the client configure the print job, and besides,
 users are accustomed to configuring print jobs. Given an available user, the
 word processor would likely want to provide a dialog UI that lets the user
 configure the print job. Once the user completes his or her configuration and
 dismisses the dialog UI (with &quot;OK,&quot; not &quot;Cancel&quot;), the word
 processor could supply the print data and invoke <code>close()</code> on the <code>PrintJob</code>. </p>

 <p>Given that Jini Print Service API clients would prefer a dialog UI that
 allows for user configuration, the Printer working group could define a new UI
 role type for that purpose. The Printer working group would likely place the
 role interface in some subpackage of its API's main package. For example, it
 could define an interface named: <code>net.jini.print.ui.PrintJobSetup</code> (<code>PrintJobSetup</code>).
 </p>

 <p>A <code>PrintJobSetup</code>
 UI would represent a dialog that enables user configuration of a print job,
 such as page orientation, and so on. Once the user selects configuration
 parameters, he or she dismisses the dialog UI, which in some way communicates
 back to the client those parameters (likely by invoking methods on the <code>PrintJob</code>
 object itself, which is likely the role object for the <code>PrintJobSetup</code>
 role) and indicates to the client that the dialog is finished. The <code>PrintJobSetup</code>
 interface's semantics would define how the client interacts with the UI, such
 as how the client knows the UI has been dismissed, and whether or not the user
 dismissed the UI with &quot;OK&quot; or &quot;Cancel.&quot; If the client
 receives &quot;OK,&quot; the client could then write print data to the <code>PrintJob</code>
 object and invoke <code>close()</code>
 on the <code>PrintJob</code>,
 thereby sending it to the printer. </p>

 <p>The semantics of the <code>PrintJobSetup</code>
 role interface defines the way in which the <code>PrintJobSetup</code> UI interacts with the
 client (i.e., communicates the configuration data and indicates the dialog's
 dismissal). As the dialog may require sophisticated UI and client interaction,
 the role interface may be more than just a tag interface; it may include
 methods that define how the UI and client interact. The word processor client
 would know how to display this <code>PrintJobSetup</code> dialog because the <code>PrintJobSetup</code>
 role interface, and its semantics, would be defined in the Jini Print Service
 API, of which that client has prior knowledge. </p>

 <h2>3.6. Working with Existing Role Types</h2>

 <p>Besides creating new role types for service-specific dialogs, a working
 group for a Jini service API or a provider of a Jini service API implementation
 could also provide multiple incarnations of an already-defined role. For
 example, what if the manufacturer of a combined printer/scanner/faxer/copier
 product (a &quot;four-in-one box&quot;) wanted to deliver four <code>AdminUI</code>s, each
 dedicated to administering one of four product functions? Such a manufacture
 could take several approaches. </p>

 <p>First, assuming the Jini Community has adopted a standard API for each
 product function (i.e., a Jini Print Service API, a Jini Scanner Service API, a
 Jini Faxer Service API, and a Jini Copier Service API), the four-in-one-box
 manufacturer could, rather than registering one Jini service whose service
 proxy implements four interfaces (such as <code>Printer</code>, <code>Scanner</code>, <code>Faxer</code>, and <code>Copier</code>),
 simply offer four separate Jini services, each of which implements only one
 interface. In this approach, each service could offer an <code>AdminUI</code>
 dedicated to that one function. </p>

 <p>Alternatively (or in addition), the manufacturer could register one Jini
 service whose service proxy implements all four interfaces. The <code>AdminUI</code> for
 that service could present a user interface device (such as a tabbed pane for a
 graphical UI) that lets users select between the four main functions. In this
 way, one <code>AdminUI</code>
 exists, which grants users access to the four conceptual administration UIs. </p>

 <p>Lastly, the manufacturer could propose to the Jini Community a Jini
 Four-in-One Service API that includes four new role types, each dedicated to
 administering a product subset. The Four-in-One working group, which defines
 the Jini Four-in-One Service API, could control a package that holds the role
 types, <code>PrinterAdminUI</code>,
 <code>ScannerAdminUI</code>,
 <code>FaxerAdminUI</code>,
 and <code>CopierAdminUI</code>.
 Clients with prior knowledge of the Jini Four-in-One Service API would also
 have prior knowledge of the four role types, and therefore could offer verb
 strings for them. Four-in-One service providers could offer those four admin UI
 types, but should also offer a basic <code>net.jini.lookup.ui.AdminUI</code>, which as
 described previously, grants a user access to all four admin UIs. Including an <code>AdminUI</code> lets
 clients that don't have prior knowledge of the Four-in-One service to offer a
 UI that will let users administer that service. </p>

 <h2>3.7. Choosing Superinterfaces for New Role Types</h2>

 <p>In general, role interfaces should not extend other role interfaces, because
 only one role interface is described in the UI descriptor's <code>role</code> field.
 For example, the <code>FaxerAdminUI</code>
 from the previous section appears to be able to extend <code>AdminUI</code>,
 because you could consider a <code>FaxerAdminUI</code> to be an <code>AdminUI</code>
 type.
 However, only one role interface can appear in the UI descriptor's <code>role</code> field. If
 a UI is both a <code>FaxerAdminUI</code>
 and an <code>AdminUI</code>,
 then which role goes into the <code>role</code> field? If the same UI registers twice, once
 with <code>AdminUI</code>
 and once with <code>FaxerAdminUI</code>,
 then what is the point of <code>FaxerAdminUI</code>?
 In other words, if a <code>FaxerAdminUI</code>
 is the default admin UI of the four, then the Four-in-One working group wouldn't
 need to define a <code>FaxerAdminUI</code>
 in the first place. They would only need to mention that an <code>AdminUI</code> should
 behave as an admin UI for the fax machine. </p>

 <p>Role interfaces can extend other interfaces; in general, they simply
 shouldn't extend other role interfaces. If a dialog UI role's semantics are
 already defined in an interface, then the role interface could extend that
 interface and thereby inherit those methods and semantics. </p>

 <p>Nevertheless, if a party decides to create a role interface that extends
 another role interface, any factory method that generates the subinterface UI
 role type must accept the same role object categories accepted by factory
 methods that generate the superinterface UI role type. For example, if <code>FaxerAdminUI</code>
 were declared as an <code>AdminUI</code>
 subinterface, any factory method that produces a <code>FaxerAdminUI</code> would have to accept
 as the role object the <code>FaxerAdminUI</code>-associated
 service item, because factory methods that produce <code>AdminUI</code>s
 accept that role object category. </p>

 <p>It is recommended that all role interfaces include a compile time <code>String</code>
 constant named <code>ROLE</code>,
 which gives the UI role interface's fully qualified string type name, as it
 should appear in UI descriptor's <code>role</code> fields. 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 <code>role</code>
 strings. </p>

 <P><B>splitwebpage</B>
 <h1>4. UI Attributes</h1>

 <p>The UI descriptor's <code>attributes</code>
 field references a <code>java.util.Set</code>
 of objects that describe the UI generated by the marshalled UI factory. Any
 object can appear in this set, so long as it is serializable. (Note that if any
 object in this set is not serializable, the entire set will not appear at the
 client side -- the UI descriptor's <code>attributes</code> field will be <code>null</code>.) </p>

 <p>If a UI provider wishes to register a UI descriptor that has no attributes,
 it may register the UI descriptor with either a reference to an empty <code>java.util.Set</code>
 or <code>null</code>
 in the UI descriptor's <code>attributes</code>
 field. Nevertheless, because clients would know little about the UI represented
 by that UI descriptor, many clients would likely ignore the descriptor
 entirely. </p>

 <p>Although all attributes are optional, this specification recommends that all
 UI descriptors include at least the attributes (all of which are members of the
 <code>net.jini.lookup.ui.attribute</code>
 package) described in this list: </p>

 <ul>
  <li>If (and only if) the UI
      supports the accessibility API, one <code>AccessibleUI</code> attribute
  <li>One <code>Locales</code>
      attribute: Lists the locales the UI supports
  <li>One <code>RequiredPackages</code>
      attribute: Lists packages the UI requires to be installed at the client
  <li>One <code>UIFactoryTypes</code>
      attribute: Lists Java types of which the marshalled UI factory is an
      instance
 </ul>

 <p>The remainder of this section describes these four attribute classes in
 detail. </p>

 <h2>4.1. The <code>AccessibleUI</code>
 Attribute</h2>

 <p><code>AccessibleUI</code>
 indicates that a generated UI implements the <code>javax.accessibility.Accessible</code>
 interface and that the UI's designer made sure the UI would work well with Java
 Accessibility API-aware assistive technologies. </p>

 <p>The attribute should appear in a <code>UIDescriptor</code>'s attributes set only if
 the marshalled UI factory produces an Accessibility API-supported UI. This
 attribute's presence in an attributes set means the produced UI will work well
 with Java Accessibility API-aware assistive technologies. </p>

 <p>The <code>AccessibleUI</code>
 attribute looks like this: </p>


 <PRE>
 package net.jini.lookup.ui.attribute;

 public class AccessibleUI implements java.io.Serializable {
 }
 </PRE>

 <h2>4.2. The <code>Locales</code>
 Attribute</h2>

 <p>
 The <code> Locales</code>
 attribute lists locales supported by a generated UI. </p>

 <p>Zero to many <code>Locales</code>
 instances may appear in a UI descriptor's attributes set. UI providers are encouraged to
 provide in any UI descriptor's attributes set one <code>Locales</code> object that contains the
 complete set of locales supported by the UI. Given that UI providers are not required
 to give complete or even accurate information about locales, clients should
 program defensively and consider the supported locales a strong hint that
 locales are supported by the UI, but not necessarily 100 percent complete or accurate.
 </p>

 <P>
 The public interface of <CODE>Locales</CODE> looks like this:

 <PRE>
 package net.jini.lookup.ui.attribute;

 import java.util.Locale;
 import java.util.Iterator;
 import java.util.Set;
 import java.util.List;

 public class Locales implements java.io.Serializable {

     public Locales(Set locales) {...}
     public boolean isLocaleSupported(Locale locale) {...}
     public Locale getFirstSupportedLocale(Locale[] locales) {...}
     public Locale getFirstSupportedLocale(List locales) {...}
     public Iterator iterator() {...}
     public Set getLocales() {...}
 }
 </PRE>

 <h2>4.3. The <code>RequiredPackages</code>
 Attribute</h2>

 <p class=MsoNormal><code>RequiredPackages</code>
 lets clients obtain a list of fully qualified names and version numbers of
 packages a UI requires. </p>

 <p>Zero to many <code>RequiredPackages</code>
 attributes may appear in a <code>UIDescriptor</code><code>'s</code><code> </code>attributes
 set. Client programs interested in a UI may wish to verify that they have all
 required packages mentioned in the <code>RequiredPackages</code> attributes (if any)
 before they attempt to create the UI. If the client lacks any required packages
 (either because the package is absent or because the package is incompatible),
 the client will not be able to use the UI. </p>

 <p>This attribute intends to provide a quick way for a client program to
 determine that a client cannot use a UI, not to guarantee that a client can
 definitely use a UI. If a client is missing a required package, or has an
 incompatible version, the client cannot use the UI. But if the client has
 compatible versions of all required packages, the client may or may not be able
 to use the UI. </p>

 <p>UI providers should attempt to list in a <code>RequiredPackages</code> attribute all
 packages that must be installed at the client for the UI to work. In this case,
 if the client has compatible versions of all listed packages and attempts to
 generate the UI via the factory method, the client will likely succeed. (Note
 that packages used by the UI that could potentially be installed at the client,
 but are also available at the UI's or service's codebase, should not be listed
 in a <code>RequiredPackages</code>
 attribute. The client does not actually require such packages, because if the
 client doesn't have them, it can download the packages.) </p>

 <p>Client programmers should bear in mind that a <code>RequiredPackages</code> attribute
 doesn't necessarily list <em>all</em> required packages. As a result,
 satisfying all required packages doesn't guarantee the UI will work on the
 client. Client programs should therefore program defensively. (For example,
 clients should probably catch <code>LinkageError</code> in appropriate places when dealing
 with UIs, even if they have compatible versions of all required packages.) </p>

 <p>The version numbers listed in <code>RequiredPackages</code> attributes must take
 the form of specification version numbers, as used by the <code>java.lang.Package</code>
 class: </p>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:.5in'>Specification version numbers use a &quot;Dewey
 Decimal&quot; syntax that consists of positive decimal integers separated by
 periods &quot;.&quot;, for example, &quot;2.0&quot; or
 &quot;1.2.3.4.5.6.7&quot;. This allows an extensible number to be used to
 represent major, minor, micro, etc versions. The version number must begin with
 a number. </p>

 <p>Here's what the <code>RequiredPackages</code>'s
 public interface looks like: </p>

 <PRE>
 package net.jini.lookup.ui.attribute;

 import java.util.Map;
 import java.util.Set;
 import java.util.Collection;
 import java.util.Iterator;

 public class RequiredPackages implements java.io.Serializable {

     public RequiredPackages(Map packages) {...}
     public Iterator iterator() {...}
     public String getVersion(String packageName) {...}
     public Map getRequiredPackages() {...}
 }
 </PRE>

 <h2>4.4. The <code>UIFactoryTypes</code>
 Attribute</h2>

 <p><code>UIFactoryTypes</code>
 allows client programs to determine Java types of which a UI factory (marshalled
 in the same <code>UIDescriptor</code>)
 is an instance. </p>

 <p>Zero to many <code>UIFactoryTypes</code>
 may appear in the UI descriptor's attributes set. The marshalled UI factory in
 a UI descriptor's <code>factory</code> field should be an instance of
 each type that appears in any <code>UIFactoryTypes</code>
 attribute in that UI descriptor's <code>attributes</code> set.
 </p>

 <p>Of all attributes that could appear in the attributes set, <code>UIFactoryTypes</code>
 is perhaps the most important. If a UI descriptor's attributes set includes no <code>UIFactoryTypes</code>
 attribute, then the only way for clients to know what kind of factory a UI
 descriptor represents is to unmarshal it. But unmarshalling a UI factory will
 likely involve downloading code, which a client wants to avoid unless it is
 fairly certain it can use the UI. As a result, UI providers are strongly
 encouraged to include in every UI descriptor a <code>UIFactoryTypes</code> attribute that
 includes those Java types (of which the UI factory is an instance) that clients
 would likely be searching for. In general, clients will be looking for
 well-known factory interface types, such as those appearing in the <code>net.jini.lookup.ui.factory</code>
 package. </p>

 <P>
 The public interface of <CODE>UIFactoryTypes</CODE> looks like this:

 <PRE>
 package net.jini.lookup.ui.attribute;

 import java.util.Set;
 import java.util.Iterator;

 public class UIFactoryTypes implements java.io.Serializable {

     public Types(Set typeNames) {...}
     public boolean isAssignableTo(Class classObj) {...}
     public Iterator iterator() {...}
     public Set getTypeNames() {...}
 }
 </PRE>

 <P><B>splitwebpage</B>
 <h1>5. UI Factories</h1>

 <p>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. </p>

 <p>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, <i>category</i> 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 <code>MainUI</code> role's semantics indicate that
 the role object is the service item. </p>

 <p>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. </p>

 <p>The Jini Service UI API's first version defines eight factory interfaces: </p>

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

 <p>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: </p>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:.5in'>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. </p>

 <p>Here's an example UI factory interface: </p>

 <PRE>
 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);
 }
 </PRE>

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

 <h2>5.1. Defining New Factory Types</h2>

 <p>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 <code>net.jini.lookup.ui.factory</code> 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 <code>net.jini.lookup.ui.factory</code>.
 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 <code>net.jini.lookup.ui.factory</code>.
 </p>

 <p>A UI factory must be an interface, and each method in the interface must
 take an <code>Object</code>
 called the <code>roleObject</code>
 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. </p>

 <p>It is recommended that all UI factory interfaces include two compile time <code>String</code>
 constants: </p>

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

 <p>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 <code>toolkit</code> strings and type names added
 to <code>UIFactoryTypes</code>
 attributes. </p>

 <P><B>splitwebpage</B>
 <h1>6. UI Objects</h1>

 <p>UI objects should be user adapters, as shown in Figure 2. Two temptations
 that service and UI providers may have are: </p>

 <ul>
  <li>Put UI code in the service
      proxy
  <li>Put service code in the UI
      object
 </ul>

 <p class=MsoNormal>Both temptations should be avoided. The Jini service proxy
 should contain the service functionality, the whole service functionality, and
 nothing but the service functionality. No user-interface code should appear in
 the service proxy, and no service functionality should appear in the UI object
 unless it also appears in the service proxy. In short, Jini Service UIs should
 merely offer users all or part of the functionality available to direct-use
 clients via the Jini service proxy's methods. </p>

 <p>Note that even though the service item may be passed as the role object for
 some roles -- as it is to factories that produce <code>MainUI</code>s, <code>AdminUI</code>s, and <code>AboutUI</code>s --
 the full service <em>functionality</em> should nevertheless be available
 exclusively through the service proxy. The service item may be passed as the
 role object to UI factories because extra information (but not extra
 functionality) could exist elsewhere in the service item, in the service ID
 or attribute sets, and the UI may wish to display that extra information to
 the user. </p>

 <p>It is strongly encouraged that service and UI providers decouple the class
 files required by a particular service item from the class files required by any
 UIs associated with that service via UI descriptors in the service item. If the
 class files for the service item and those of all service-associated UIs via UI
 descriptors are placed into the same JAR file, then a client must download all
 class files for all UIs just to download the service item, even if the client
 never uses a single UI. </p>

 <h2>6.1. What to Provide</h2>

 <p>This specification does not mandate any UI types to be associated with
 services. Service providers are free to provide any types of UI, or no UIs, with
 their services. Nevertheless, some discussion of client expectations may help
 service providers decide what UI types to supply. </p>

 <p>First, if a service provider only supplies one UI, it should likely be an
 embeddable component, such as an AWT <code>Panel</code> or Swing <code>JComponent</code>.
 Although Swing UIs can be more attractive than AWT UIs, an AWT <code>Panel</code> may
 allow the greatest reach with one UI type. </p>

 <p>A <code>Panel</code>
 allows clients to show a UI without another pop-up window, whether they support
 AWT or Swing. If a client wants to pop up a UI, it can embed a <code>Panel</code> UI in a
 new <code>Frame</code>
 and pop that up. If a client wants to display a <code>Panel</code> title and icon, it can use the
 localized name and icon provided by a <code>ServiceType</code>. </p>

 <p>A <code>Panel</code>
 doesn't usually provide an exit for the client, and a menu bar at the top of a <code>Panel</code>
 is uncommon.
 So as a UI provider, you may also want to provide either a <code>Frame</code> or a <code>Window</code> in
 which <code>Panel</code> is placed
 and add other UI elements, such as menu bar, status bar, and title. If you take
 this approach, one factory object could implement both the <code>PanelFactory</code>
 and the <code>FrameFactory</code>
 interfaces, because their toolkit is the same. This might make sense if the <code>Panel</code> is used
 in the <code>Frame</code>,
 and the <code>Frame</code>
 doesn't require many classes not already used by the panel. Alternatively, you could produce the <code>Panel</code> and <code>Frame</code> by two
 different UI factories sitting in two different UI descriptors. </p>

 <p>You may also wish to support Swing in addition to, or instead of,
 AWT. If so, at a minimum a Swing <code>JComponent</code> UI, or a <code>JComponent</code>
 with either a <code>JFrame</code>
 or a <code>JWindow, </code>may
 be more suitable. If you take the second approach, one factory object could
 implement both the <code>JComponentFactory</code>
 and the <code>JFrameFactory</code>
 interfaces, because their toolkit is the same. Alternatively, two different UI
 factories sitting in two different UI descriptors could produce the <code>JComponent</code> and
 <code>JFrame</code>.
 </p>

 <p>On the other hand, for those UI roles that represent user dialogs, an AWT <code>Dialog</code> or
 Swing <code>JDialog</code>
 may be more appropriate. </p>

 <p>Currently no direct support exists in the Jini Service UI API for
 speech-only interfaces, but an AWT or Swing UI could be enhanced with speech
 capabilities, produced by an appropriate AWT or Swing UI factory type, and
 identified as speech-enabled with the appropriate required package names (such
 as <code>javax.speech</code>)
 in the <code>RequiredPackages</code>
 attribute. If a speech-enhanced GUI is provided, a GUI-only version should also
 be provided, as many clients won't have speech capabilities. </p>

 <h2>6.2. Avoid Service-Level Data and Client Context</h2>

 <p>Service-level data and client-context data are two data types you may be tempted
 to pass to UI objects, either directly or via factory methods (which may then
 tempt you to define new factories). It is strongly recommended that you avoid
 both temptations. </p>

 <p>For example, imagine a service provider requires a user name and password for
 its service. The service provider wants clients to be able to save a user's
 name and password locally and enter them automatically the next time the user
 uses the service. If no user name and password were previously saved, the
 service UI would prompt the user to type them into a logon dialog box. But if
 the user name and password were saved, the user would never see the logon
 dialog box. Rather, the client program would log on automatically with the
 saved user name and password, and display to the user only the service UI that
 appears after a successful logon. </p>

 <p>To implement this functionality, a service provider might be tempted to
 define interfaces that allow the client to pass a saved user name and password
 to the UI. Alternatively, a service provider might be tempted to define new
 factory methods that enable clients to pass a user name and password to the
 factory, which could then send them to the UI. </p>

 <p>
 The trouble with either of these approaches is that functionality is being put into the UI that isn't in the service.
 As mentioned previously, a Jini service's
 functionality should be modeled in the service proxy, so direct-use client
 code can just use the service directly. If a service requires a user name and
 password, the service proxy's interface should allow the client to provide the
 user name and password. Thus, a client with a user could give the user name and
 password to the service proxy first, then create the UI. The UI could ask the
 service proxy if it has a user name and password yet. If not, the UI would
 show the logon dialog box prompting for the user name and password. Otherwise,
 the UI wouldn't show the logon dialog box. </p>

 <p>The recommended way to design a Jini service and its UIs is to make sure the
 full functionality is available via the service proxy interface, and keep the
 UIs focused on being user adapters -- adapting some or all functionality
 available via the service proxy interface, but offering no more functionality
 available via the service proxy interface. </p>

 <p>Service providers are not the only Jini Community members who will face
 UI-related temptations in the years ahead; client providers may also be tempted
 to pass client context data to UI objects. </p>

 <p>For example, a client provider wishing to differentiate his or her product
 from the competition might add a toolbar and status bar to the client program.
 The client provider might be tempted to define interfaces that allow the client
 to pass references to the toolbar and status bar to the UI. Alternatively, the
 client might be tempted to define new factory interfaces whose factory methods
 include parameters that allow the client to pass references to the toolbar and
 status bar to the factory, which could then pass it along to the UI. UIs that
 obtain references to the toolbar and status bar in either of these two ways
 could then put buttons on the toolbar and write messages to the status bar. </p>

 <p>The trouble lurking behind this seemingly innocuous value-add is that the
 toolbar and status bar references represent client context data, which complicates
 the UI providers' jobs. If other clients devise their own toolbar and status
 bar interfaces, and perhaps even up the ante by also defining other client
 context innovations, UI providers will have to worry about which kinds of
 client context to support. To the extent a UI provider supports various kinds
 of client context, that UI provider's test matrix will expand. To the extent
 that client context becomes complicated, such as the invention of a general
 compound document model for Jini Service UIs, everyone's job, and the user's
 experience, become more complicated. </p>

 <p>Client providers, therefore, should avoid the temptation to invent client
 context for Jini Service UIs. The only context data that should be passed to UI
 factory methods is context a UI toolkit requires, such as the <code>Frame</code> or <code>Window</code>
 reference required by an AWT <code>Dialog</code>. Similarly, the only context in which Jini
 Service UIs should be embedded is context the toolkit provides. For example, a
 client could embed a Jini Service UI <code>JComponent</code> in a <code>JFrame</code>, and
 then pop up the <code>JFrame</code>.
 The <code>JComponent</code>'s ability to embed
 is provided by its toolkit, Swing. </p>

 <p>UI providers can do their part by ensuring that their UIs don't depend on
 any context other than that provided by the UI toolkit. Jini Service UIs should
 be self-contained and care only about the context of their toolkit. If a UI
 provider wants its UI to write messages to a status bar, the UI should not look
 for a status bar provided by the client, the UI should itself include a status
 bar. </p>

 <P><B>splitwebpage</B>
 <h1>7. Add Third-Party UIs</h1>

 <p>To add a third-party UI to an existing service's attribute sets, you must
 have the service's cooperation. The service can veto your request at any of
 several points in the process. The steps are: </p>

 <ol>
  <li>Check to see if the service
      proxy implements <code>net.jini.admin.Administrable</code>
      (<code>Administrable</code>).

 </ol>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:1.0in'>If the service proxy does not implement <code>Administrable</code>,
 the service provider has already thwarted your wishes. You won't be able to add
 a third-party UI directly to the service item's attribute sets. </p>

 <ol>
  <li>Cast the service proxy to <code>Administrable</code>
      and invoke <code>getAdmin()</code>.

  <li>Check to see if the admin
      object returned by <code>getAdmin()</code>
      implements the <code>net.jini.admin.JoinAdmin</code>
      (<code>JoinAdmin</code>).

 </ol>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:1.0in'>If the admin object does not implement <code>JoinAdmin</code>, the
 service provider has thwarted your wishes. You won't be able to add a
 third-party UI directly to the service item's attribute sets. </p>

 <ol>
  <li>Cast the service proxy to <code>JoinAdmin</code>,
      and invoke appropriate methods to add or modify one or more <code>UIDescriptor</code>s.
 </ol>

 <p class=MsoNormal style='margin-right:.5in;mso-margin-top-alt:auto;mso-margin-bottom-alt:
 auto;margin-left:1.0in'>You add or modify <code>UIDescriptor</code>s in the same manner as
 you would add or modify any kind of <code>Entry</code> in the service's attribute sets.
 The <code>JoinAdmin</code>'s
 <code>addLookupAttribute()</code>
 method lets you add new <code>UIDescriptor</code>s.
 Its <code>modifyLookupAttribute()</code>
 method lets you modify existing <code>UIDescriptor</code>s. Once again, the service provider
 can veto your request, even at this step, by throwing an exception from these
 methods. </p>

 <p>Once a new <code>UIDescriptor</code>
 for a third-party UI is successfully added via the process described
 previously, the third party won't need to add it again. From that point
 forward, whenever a service registers itself with a lookup service, its service
 item will include the third-party <code>UIDescriptor</code>. It will also reregister
 itself with any lookup services with which it is currently registered, so that
 the new <code>UIDescriptor</code>
 will appear there as well. Even if the service provider crashes and restarts,
 it should remember the new <code>UIDescriptor</code> and include it in its registrations
 after the crash and restart. </p>

 <p>On the other hand, the UI, UI factory, and possibly the attributes require
 class files to be available in some codebase. Although the third party never
 needs to worry about the <code>UIDescriptor</code>
 being included in future service registrations, the third party must make sure
 the class files are forever available at some codebase. </p>

 <p>One potential problem with adding a third-party UI is that in a strict
 client-side security policy, downloaded code will by default only have
 permission to connect back to the host from which the code was downloaded. In
 that case, if the third-party UI's codebase is on a different host than the
 service proxy's codebase, the service proxy won't be allowed to talk back to
 its host at the behest of the UI. Therefore, for a third-party UI to work in
 practice, either the third-party UI's codebase must be on the same host that
 serves the service's codebase, or the client must specifically relax its
 security policy in order to use the third-party UI. </p>

 <P><B>splitwebpage</B>
 <h1>8. Evolution and Prior Knowledge</h1>

 <p>In the future, the Service UI API can evolve in several different ways. Any
 party can define new role types and their meanings, new attribute classes, and
 new factory types. Any party can identify new toolkit types. For clients to be
 able to use these new types, the new types will need to be publicized. Before a
 client will be able to use a role, factory, or attribute type, that client's
 programmers must have had prior knowledge of the type. </p>

 <p>Other than service-specific UI roles created under Jini Service APIs, new
 roles should come from the Service UI project at the Jini Community. Service
 providers should resist temptation to define new role types, as that
 complicates clients' jobs. Clients should be able to program to the interface
 (particular Jini Service APIs about which they have prior knowledge), rather
 than be forced to program to one or more implementations of that interface.
 Whether role types are being defined for particular Jini Service APIs, or
 globally for the Jini Service UI API, the preferred way to define the role
 interfaces is via the Jini Community Process. </p>

 <p>As mentioned previously, new UI factory interface types should be defined
 with great care. The main justification for a new set of UI factory types is
 when new UI toolkits appear on the scene. The preferred way to define these
 interfaces is via the Jini Community Process. Similarly, although anyone can
 define new attribute types, the preferred way to define these types is through
 the Jini Community Process. </p>

 <p>The Jini Community is the preferred process to define new role, factory, and
 attribute types because it is the best way to avoid a explosion of types. For
 example, if a certain attribute type is needed, and twenty different parties
 define basically the same attribute, but with twenty slightly different names
 and behaviors, and in twenty different packages, then clients wanting to use
 that kind of attribute would need to support all twenty variations. It would be
 far better if those twenty parties agreed on one attribute class. Enabling such
 collaborations is the Jini Community's main purpose. If twenty parties can agree
 upon one attribute class, then clients need to be aware of less
 information (one attribute class versus twenty), and the resulting client
 programs would likely work more reliably. </p>

 <P><B>splitwebpage</B>
 <H1>9. Consistent Serialized Forms</H1>

 <p>
 Because the Jini lookup service uses exact matching of the serialized forms of entry fields, it is critical that fields that will be used in template lookups have serialized forms that are consistent across all virtual machines.  However, there is no guarantee that implementations of the <code>Set</code> interface, the declared type of the <code>attributes</code> field of <code>UIDescriptor</code>, have consistent serialized forms across all virtual machines.  For example, <code>java.util.HashSet</code>, perhaps the most commonly used implementation of <code>Set</code>, does not guarantee a consistent serialized form.  As a result, if a <code>UIDescriptor</code> that contains a <code>HashSet</code> in its <code>attributes</code> field is retrieved from a Jini lookup service, the serialized a form of the <code>attributes</code> field could be different if the <code>UIDescriptor</code> is reserialized as part of a template.  This means that a <code>UIDescriptor</code>, when retrieved from a Jini lookup service and used immediately in a lookup template, may not match itself.

 <p>
 The Service UI API was defined under the assumption that
 <code>UIDescriptor</code>s in
 Jini lookup templates might contain non-<code>null</code>
 <code>role</code> and <code>toolkit</code> fields, but
 would always contain <code>null</code> in their
 <code>attributes</code> and <code>factory</code> fields.
 It was expected that attributes could be inspected on the client side to
 select between multiple matches of a Jini lookup. Once a
 <code>UIDescriptor</code> was selected, it was expected that clients would use
 the <code>factory</code> field to produce the selected UI. Because of
 these assumptions, the <code>UIDescriptor</code> class was not designed to
 ensure a template in which all four fields were non-<code>null</code>
 would work.  In other words, the designers were aware that the
 <code>attributes</code> field could not be used in lookup templates,
 but did not imagine that anyone would ever need to do that.

 <p>
 When used in templates intended for basic lookup of Jini services,
 <code>UIDescriptor</code>s will likely never have non-<code>null</code>
 <code>attributes</code> fields. Nevertheless, <code>UIDescriptor</code>s
 used in templates intended to modify the attribute sets of
 already-registered Jini services could very likely contain
 non-<code>null</code> <code>attributes</code> fields. For example,
 to add an object to the attributes set of a
 <code>UIDescriptor</code> already registered as part
 particular Jini service item, you must pass a template <code>UIDescriptor</code>
 that exactly matches the registered <code>UIDescriptor</code> in
 the <code>attrSetTemplates</code> parameter of either:

 <ul>
 <li><code>modifyAttributes</code> method of <code>net.jini.core.lookup.ServiceRegistration</code>
 <li><code>modifyLookupAttributes</code> method of <code>net.jini.admin.ServiceRegistration</code>
 </ul>

 <p>
 Unfortunately, the use case of modifying a <code>UIDescriptor</code> in
 an already-registered Jini service item was never considered during the initial
 design discussions leading to 1.0 release of the Service UI API. To
 address this need, the 1.1 version of this specification narrows slightly
 the contracts of these methods and constructors:

 <ul>
 <li><code>UIDescriptor(java.lang.String role,
     java.lang.String toolkit, java.util.Set attributes,
     java.rmi.MarshalledObject factory)</code> constructor of
     <code>net.jini.lookup.entry.UIDescriptor</code>
 <li><code>Locales(java.util.Set locales)</code> constructor of
     <code>net.jini.lookup.ui.attribute.Locales</code>
 <li><code>RequiredPackages(java.util.Map packages)</code> constructor of
     <code>net.jini.lookup.ui.attribute.RequiredPackages</code>
 <li><code>UIFactoryTypes(java.util.Set typeNames)</code> constructor of
     <code>net.jini.lookup.ui.attribute.UIFactoryTypes</code>
 </ul>

 <p>
 The 1.1 specification adds to the contracts of each of these constructors
 a requirement that they copy the contents of the passed <code>Set</code>
 or <code>Map</code> into a serializable read-only version that has a consistent serialized
 form across all VMs. This new requirement yields the desired behavior when
 attempting to modify <code>UIDescriptor</code>s already part of service items registered in lookup
 services.

 <P><B>splitwebpage</B>

 <H1>10. Package <CODE>net.jini.lookup.entry</CODE></H1>

 <P>
 The Service UI API defines two classes, <code>UIDescriptor</code> and <code>UIDescriptorBean</code>,
 that were placed in a pre-existing package,
 <code>net.jini.lookup.entry</code>.
 This specification does not provide a complete specification of
 the <code>net.jini.lookup.entry</code> package. It does, however,
 provide a complete specification of classes
 <code>net.jini.lookup.entry.UIDescriptor</code> and
 <code>net.jini.lookup.entry.UIDescriptorBean</code>.

 <H2>10.1. Class <CODE>net.jini.lookup.entry.UIDescriptor</CODE></H2>
 <P><CODE>public class UIDescriptor<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends net.jini.entry.AbstractEntry<BR>
 </CODE>
 <P>
 <CODE>Entry</CODE> that enables a UI for a service to be associated
  with the service in the attribute sets of the service item.
  <CODE>UIDescriptor</CODE> holds a marshalled UI factory object, as
  well as a role string, a sub-role string, and set of attributes that describe the
  UI generated by the factory.
 <H3>10.1.1. Constructor <CODE>UIDescriptor()</CODE></H3>
 <P>
 <CODE>
 public <STRONG>UIDescriptor</STRONG>()<BR>
 </CODE>
 <P>
 Constructs a <CODE>UIDescriptor</CODE> with all fields set to <CODE>null</CODE>.<H3>10.1.2. Constructor <CODE>UIDescriptor(java.lang.String, java.lang.String, java.util.Set, java.rmi.MarshalledObject)</CODE></H3>
 <P>
 <CODE>
 public <STRONG>UIDescriptor</STRONG>(java.lang.String role, java.lang.String toolkit, java.util.Set attributes, java.rmi.MarshalledObject factory)<BR>
 </CODE>
 <P>
 Constructs a <CODE>UIDescriptor</CODE> with the fields set to passed values.
  This constructor copies the contents of the passed attributes <code>Set</code> into a
  serializable read-only <code>Set</code> that has a
  consistent serialized form across all VMs, and initializes the <code>attributes</code>
  field with the consistent <code>Set</code>.<DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>role</CODE> - the role</DD>
 <DD><CODE>toolkit</CODE> - the toolkit</DD>
 <DD><CODE>attributes</CODE> - the attributes</DD>
 <DD><CODE>factory</CODE> - the factory</DD>
 </DL>
 <H3>10.1.3. Field <CODE>role</CODE></H3>
 <P>
 <CODE>
 public <STRONG>role</STRONG><BR>
 </CODE>
 <P>
 Gives the fully qualified name of the interface that represents
  the role of the UI generated by the marshalled UI factory.
  If the client program unmarshals the UI factory and invokes a factory method, the
  UI returned by the factory method must implement the role the interface specified by
  <CODE>role</CODE>.

  <P>
  For a client program to be able to use a UI, the client has to have prior knowledge
  of the UI semantics, which is defined by the UI's role type. Thus, for a client
  to be able to use a UI, the client must understand the semantics
  of the type whose fully qualified name is given in the <CODE>String</CODE>
  referenced from the <CODE>role</CODE> field of that UI's <CODE>UIDescriptor</CODE>.

  <P>
  For example, two role types that are defined in the <CODE>net.jini.lookup.ui</CODE>
  package by the Jini Service UI Specification are <CODE>MainUI</CODE>, for a main UI
  to a Jini service, and <CODE>AdminUI</CODE>, for an administration UI. Other role types
  may be defined by the Jini Service UI Specification and by individual Jini service API
  specifications.

  <P>
  As the strings referenced from the <CODE>role</CODE> field are Java type names, they
  are intended to be manipulated by client programs only. They should not be shown to a user.
 <H3>10.1.4. Field <CODE>toolkit</CODE></H3>
 <P>
 <CODE>
 public <STRONG>toolkit</STRONG><BR>
 </CODE>
 <P>
 A <code>String</code> to facilitate searching whose value represents the main UI toolkit (for example
  Swing or AWT) which the produced UI makes use of. The value to which this field should
  be set is defined by the semantics of the factory type. (This field is intended
  to facilitate searches. For example, a client can search for all blender services that have Swing
  MainUI's.)
 <H3>10.1.5. Field <CODE>attributes</CODE></H3>
 <P>
 <CODE>
 public <STRONG>attributes</STRONG><BR>
 </CODE>
 <P>
 A set of objects that describe the UI generated by the marshalled UI factory.
 <H3>10.1.6. Field <CODE>factory</CODE></H3>
 <P>
 <CODE>
 public <STRONG>factory</STRONG><BR>
 </CODE>
 <P>
 The <CODE>get()</CODE> method of this <CODE>MarshalledObject</CODE>
  must return an object that implements one or more UI factory interfaces. The actual
  UI factory type or types implemented by the returned object
  must be described by a <CODE>UIFactoryTypes</CODE> attribute placed in
  the attributes set of this <CODE>UIDescriptor</CODE>.
 <H3>10.1.7. Method <CODE>getUIFactory(java.lang.ClassLoader)</CODE></H3>
 <P>
 <CODE>
 public final java.lang.Object <STRONG>getUIFactory</STRONG>(java.lang.ClassLoader parentLoader)<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;throws java.io.IOException, java.lang.ClassNotFoundException<BR>
 </CODE>
 <P>
 A convenience method for unmarshalling the UI factory stored
  in the <CODE>MarshalledObject</CODE> referenced from the
  <CODE>factory</CODE> field. This method saves a reference
  to the current context class loader, sets the context class loader
  to the class loader passed as <CODE>parentLoader</CODE>, invokes
  <CODE>get()</CODE> on the marshalled object, then resets the
  context class loader to the saved reference before returning
  the object produced by <CODE>get()</CODE>.

  <P>The class loader
  passed in <CODE>parentLoader</CODE> should be able to load classes
  needed when the UI interacts with the <CODE>roleObject</CODE> passed as the first
  parameter to the factory method. For example, if the <CODE>roleObject</CODE> is
  the service item (as it is for the <CODE>MainUI</CODE> and <CODE>AdminUI</CODE>
  roles), the class loader passed in <CODE>parentLoader</CODE> could be
  the class loader with which the service proxy object referenced
  from the service item's <CODE>service</CODE> field was loaded.
  For example:

  <PRE>
  Object uiFactory = uiDescriptor.getUIFactory(
      serviceItem.service.getClass().getClassLoader());
  </PRE>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>parentLoader</CODE> is null.</DD>
 </DL>
 <H3>10.1.8. Serialized Form of <CODE>net.jini.lookup.entry.UIDescriptor</CODE></H3>
 <H4>10.1.8.1. Serialized Field <CODE>role</CODE></H4>
 <P>
 <CODE>
 java.lang.String <STRONG>role</STRONG><BR>
 </CODE>
 <P>
 Gives the fully qualified name of the interface that represents
  the role of the UI generated by the marshalled UI factory.
  If the client program unmarshals the UI factory and invokes a factory method, the
  UI returned by the factory method must implement the role the interface specified by
  <CODE>role</CODE>.

  <P>
  For a client program to be able to use a UI, the client has to have prior knowledge
  of the UI semantics, which is defined by the UI's role type. Thus, for a client
  to be able to use a UI, the client must understand the semantics
  of the type whose fully qualified name is given in the <CODE>String</CODE>
  referenced from the <CODE>role</CODE> field of that UI's <CODE>UIDescriptor</CODE>.

  <P>
  For example, two role types that are defined in the <CODE>net.jini.lookup.ui</CODE>
  package by the Jini Service UI Specification are <CODE>MainUI</CODE>, for a main UI
  to a Jini service, and <CODE>AdminUI</CODE>, for an administration UI. Other role types
  may be defined by the Jini Service UI Specification and by individual Jini service API
  specifications.

  <P>
  As the strings referenced from the <CODE>role</CODE> field are Java type names, they
  are intended to be manipulated by client programs only. They should not be shown to a user.
 <H4>10.1.8.2. Serialized Field <CODE>toolkit</CODE></H4>
 <P>
 <CODE>
 java.lang.String <STRONG>toolkit</STRONG><BR>
 </CODE>
 <P>
 A <code>String</code> to facilitate searching whose value represents the main UI toolkit (for example
  Swing or AWT) which the produced UI makes use of. The value to which this field should
  be set is defined by the semantics of the factory type. (This field is intended
  to facilitate searches. For example, a client can search for all blender services that have Swing
  MainUI's.)
 <H4>10.1.8.3. Serialized Field <CODE>attributes</CODE></H4>
 <P>
 <CODE>
 java.util.Set <STRONG>attributes</STRONG><BR>
 </CODE>
 <P>
 A set of objects that describe the UI generated by the marshalled UI factory.
 <H4>10.1.8.4. Serialized Field <CODE>factory</CODE></H4>
 <P>
 <CODE>
 java.rmi.MarshalledObject <STRONG>factory</STRONG><BR>
 </CODE>
 <P>
 The <CODE>get()</CODE> method of this <CODE>MarshalledObject</CODE>
  must return an object that implements one or more UI factory interfaces. The actual
  UI factory type or types implemented by the returned object
  must be described by a <CODE>UIFactoryTypes</CODE> attribute placed in
  the attributes set of this <CODE>UIDescriptor</CODE>.
 <H2>10.2. Class <CODE>net.jini.lookup.entry.UIDescriptorBean</CODE></H2>
 <P><CODE>public class UIDescriptorBean<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.lang.Object<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;implements net.jini.lookup.entry.EntryBean, java.io.Serializable<BR>
 </CODE>
 <P>
 A JavaBeans(TM) component that encapsulates a <code>UIDescriptor</code> object.
 <H3>10.2.1. Constructor <CODE>UIDescriptorBean()</CODE></H3>
 <P>
 <CODE>
 public <STRONG>UIDescriptorBean</STRONG>()<BR>
 </CODE>
 <P>
 Construct a new JavaBeans component, linked to a new empty <code>UIDescriptor</code> object.<H3>10.2.2. Field <CODE>assoc</CODE></H3>
 <P>
 <CODE>
 protected <STRONG>assoc</STRONG><BR>
 </CODE>
 <P>
 The <code>UIDescriptor</code> object associated with this JavaBeans component.
 <H3>10.2.3. Method <CODE>makeLink(net.jini.core.entry.Entry)</CODE></H3>
 <P>
 <CODE>
 public void <STRONG>makeLink</STRONG>(net.jini.core.entry.Entry e)<BR>
 </CODE>
 <P>
 Make a link to a <code>UIDescriptor</code> object.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>e</CODE> - the <code>Entry</code> object, which must be a <code>UIDescriptor</code>, to which to link</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>java.lang.ClassCastException</CODE> - the <code>Entry</code> is not
      a <code>UIDescriptor</code>, the correct type for this JavaBeans component</DD>
 </DL>
 <H3>10.2.4. Method <CODE>followLink()</CODE></H3>
 <P>
 <CODE>
 public net.jini.core.entry.Entry <STRONG>followLink</STRONG>()<BR>
 </CODE>
 <P>
 Return the <code>UIDescriptor</code> linked to by this JavaBeans component.
 <H3>10.2.5. Method <CODE>getRole()</CODE></H3>
 <P>
 <CODE>
 public java.lang.String <STRONG>getRole</STRONG>()<BR>
 </CODE>
 <P>
 Return the value of the <code>role</code> field in the object linked to by
  this JavaBeans component.
 <H3>10.2.6. Method <CODE>setRole(java.lang.String)</CODE></H3>
 <P>
 <CODE>
 public void <STRONG>setRole</STRONG>(java.lang.String role)<BR>
 </CODE>
 <P>
 Set the value of the <code>role</code> field in the object linked to by this
  JavaBeans component.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>role</CODE> - a <code>String</code> specifying the role value</DD>
 </DL>
 <H3>10.2.7. Method <CODE>getToolkit()</CODE></H3>
 <P>
 <CODE>
 public java.lang.String <STRONG>getToolkit</STRONG>()<BR>
 </CODE>
 <P>
 Return the value of the <code>toolkit</code> field in the object linked to by
  this JavaBeans component.
 <H3>10.2.8. Method <CODE>setToolkit(java.lang.String)</CODE></H3>
 <P>
 <CODE>
 public void <STRONG>setToolkit</STRONG>(java.lang.String toolkit)<BR>
 </CODE>
 <P>
 Set the value of the <code>toolkit</code> field in the object linked to by this
  JavaBeans component.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>toolkit</CODE> - a <code>String</code> specifying the toolkit value</DD>
 </DL>
 <H3>10.2.9. Method <CODE>getAttributes()</CODE></H3>
 <P>
 <CODE>
 public java.util.Set <STRONG>getAttributes</STRONG>()<BR>
 </CODE>
 <P>
 Return the value of the <code>attributes</code> field in the object linked to by
  this JavaBeans component.
 <H3>10.2.10. Method <CODE>setAttributes(java.util.Set)</CODE></H3>
 <P>
 <CODE>
 public void <STRONG>setAttributes</STRONG>(java.util.Set attributes)<BR>
 </CODE>
 <P>
 Set the value of the <code>attributes</code> field in the object linked to by this
  JavaBeans component.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>attributes</CODE> - a <code>Set</code> specifying the attributes value</DD>
 </DL>
 <H3>10.2.11. Method <CODE>getFactory()</CODE></H3>
 <P>
 <CODE>
 public java.rmi.MarshalledObject <STRONG>getFactory</STRONG>()<BR>
 </CODE>
 <P>
 Return the value of the <code>factory</code> field in the object linked to by
  this JavaBeans component.
 <H3>10.2.12. Method <CODE>setFactory(java.rmi.MarshalledObject)</CODE></H3>
 <P>
 <CODE>
 public void <STRONG>setFactory</STRONG>(java.rmi.MarshalledObject factory)<BR>
 </CODE>
 <P>
 Set the value of the <code>factory</code> field in the object linked to by this
  JavaBeans component.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>factory</CODE> - a <code>MarshalledObject</code> specifying the factory value</DD>
 </DL>
 <H3>10.2.13. Serialized Form of <CODE>net.jini.lookup.entry.UIDescriptorBean</CODE></H3>
 <H4>10.2.13.1. Serialized Field <CODE>assoc</CODE></H4>
 <P>
 <CODE>
 net.jini.lookup.entry.UIDescriptor <STRONG>assoc</STRONG><BR>
 </CODE>

 <P>
 The <code>UIDescriptor</code> object associated with this JavaBeans component.

 <H1>11. Package <CODE>net.jini.lookup.ui</CODE></H1>
 Provides UI role interfaces used to associate service UIs with Jini services.

 <H2>11.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui</CODE></H2>
 <UL>
 <LI><CODE>AboutUI</CODE> - UI role interface implemented by About UIs, which enable users to
  view (or in some way experience) information about a service.
 <LI><CODE>AdminUI</CODE> - UI role interface implemented by Admin UIs,
  which enable users to administer a service.
 <LI><CODE>MainUI</CODE> - UI role interface implemented by Main UIs,
  which enable client programs to grant users general access to a service.
 </UL>
 <H2>11.2. Summary of Classes In Package <CODE>net.jini.lookup.ui</CODE></H2>
 <P>No classes are declared in package <CODE>net.jini.lookup.ui</CODE>.
 <H2>11.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui</CODE></H2>
 <P>No <CODE>Exception</CODE>s are declared in package <CODE>net.jini.lookup.ui</CODE>.
 <H2>11.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui</CODE></H2>
 <P>No <CODE>Error</CODE>s are declared in package <CODE>net.jini.lookup.ui</CODE>.
 <H2>11.5. Interface <CODE>net.jini.lookup.ui.AboutUI</CODE></H2>
 <P><CODE>public interface AboutUI<BR>
 </CODE>
 <P>
 UI role interface implemented by About UIs, which enable users to
  view (or in some way experience) information about a service.
  If a UI descriptor's UI factory produces a UI that implements
  this interface (i.e., produces a About UI), the UI descriptor's
  <CODE>role</CODE> field must reference a <CODE>String</CODE> with the value
  <CODE>"net.jini.lookup.ui.AboutUI"</CODE>.

  <P>
  The first parameter of any factory method declared in a UI factory type is an
  object called the "role object."
  Any factory method that produces an About UI must accept as the role object the
  service item (the <CODE>net.jini.core.lookup.ServiceItem</CODE>) of the service
  with which the About UI is associated.

  <P>
  About UIs should allow clients to configure them before they
  begin. For example, About UIs produced by <CODE>FrameFactory</CODE>,
  <CODE>JFrameFactory</CODE>, <CODE>WindowFactory</CODE>
  and <CODE>JWindowFactory</CODE> (all members of the <CODE>net.jini.lookup.ui.factory</CODE> package)
  should not be visible when they are returned from the factory method. This allows clients to set
  the UI's position and size, for example, before making the UI
  visible by invoking <CODE>setVisible(true)</CODE> on the UI.

  <P>
  A client should be
  able to invoke a About UI factory method multiple times sequentially. In other words, if a user
  uses a service via a About UI, then says exit, then double clicks once again on the service icon,
  the client can just simply invoke a UI factory method again, and get another About UI for the same
  service. About UIs, therefore, should be written so that they work no matter what state
  the service object happens to be in when the About UI is created.

  <P>
  It is recommended that clients use multiple About UIs for the same service only sequentially, and
  avoid creating multiple About UIs for the same service that operate concurrently with one another.
  But because some clients may create and use multiple About UIs at the same time for the same service,
  providers of services and About UIs should program defensively, to ensure that multiple About UIs
  for the same service at the same time will all work together concurrently.
 <H3>11.5.1. Field <CODE>ROLE</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>ROLE</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>role</CODE>
  field of <CODE>UIDescriptor</CODE>s for AboutUI role UIs.
  The value of this constant is <CODE>"net.jini.lookup.ui.AboutUI"</CODE>.
 <H2>11.6. Interface <CODE>net.jini.lookup.ui.AdminUI</CODE></H2>
 <P><CODE>public interface AdminUI<BR>
 </CODE>
 <P>
 UI role interface implemented by Admin UIs,
  which enable users to administer a service.
  If a UI descriptor's UI factory produces a UI that implements
  this interface (i.e., produces a Admin UI), the UI descriptor's
  <CODE>role</CODE> field must reference a <CODE>String</CODE> with the value
  <CODE>"net.jini.lookup.ui.AdminUI"</CODE>.

  <P>
  The first parameter of any factory method declared in a UI factory type is an
  object called the "role object."
  Any factory method that produces an Admin UI must accept as the role object the
  service item (the <CODE>net.jini.core.lookup.ServiceItem</CODE>) of the service
  with which the Admin UI is associated.

  <P>
  Admin UIs should allow clients to configure them before they
  begin. For example, Admin UIs produced by <CODE>FrameFactory</CODE>,
  <CODE>JFrameFactory</CODE>, <CODE>WindowFactory</CODE>
  and <CODE>JWindowFactory</CODE> (all members of the <CODE>net.jini.lookup.ui.factory</CODE> package)
  should not be visible when they are returned from the factory method. This allows clients to set
  the UI's position and size, for example, before making the UI
  visible by invoking <CODE>setVisible(true)</CODE> on the UI.

  <P>
  A client should be
  able to invoke a Admin UI factory method multiple times sequentially. In other words, if a user
  uses a service via a Admin UI, then says exit, then double clicks once again on the service icon,
  the client can just simply invoke a UI factory method again, and get another Admin UI for the same
  service. Admin UIs, therefore, should be written so that they work no matter what state
  the service object happens to be in when the Admin UI is created.

  <P>
  It is recommended that clients use multiple Admin UIs for the same service only sequentially, and
  avoid creating multiple Admin UIs for the same service that operate concurrently with one another.
  But because some clients may create and use multiple Admin UIs at the same time for the same service,
  providers of services and Admin UIs should program defensively, to ensure that multiple Admin UIs
  for the same service at the same time will all work together concurrently.
 <H3>11.6.1. Field <CODE>ROLE</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>ROLE</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>role</CODE>
  field of <CODE>UIDescriptor</CODE>s for AdminUI role UIs.
  The value of this constant is <CODE>"net.jini.lookup.ui.AdminUI"</CODE>.
 <H2>11.7. Interface <CODE>net.jini.lookup.ui.MainUI</CODE></H2>
 <P><CODE>public interface MainUI<BR>
 </CODE>
 <P>
 UI role interface implemented by Main UIs,
  which enable client programs to grant users general access to a service.
  If a UI descriptor's UI factory produces a UI that implements
  this interface (i.e., produces a Main UI), the UI descriptor's
  <CODE>role</CODE> field must reference a <CODE>String</CODE> with the value
  <CODE>"net.jini.lookup.ui.MainUI"</CODE>.

  <P>
  The first parameter of any factory method declared in a UI factory type is an
  object called the "role object."
  Any factory method that produces an Main UI must accept as the role object the
  service item (the <CODE>net.jini.core.lookup.ServiceItem</CODE>) of the service
  with which the Main UI is associated.

  <P>
  Main UIs should allow clients to configure them before they
  begin. For example, Main UIs produced by <CODE>FrameFactory</CODE>,
  <CODE>JFrameFactory</CODE>, <CODE>WindowFactory</CODE>
  and <CODE>JWindowFactory</CODE> (all members of the <CODE>net.jini.lookup.ui.factory</CODE> package)
  should not be visible when they are returned from the factory method. This allows clients to set
  the UI's position and size, for example, before making the UI
  visible by invoking <CODE>setVisible(true)</CODE> on the UI.

  <P>
  A client should be
  able to invoke a Main UI factory method multiple times sequentially. In other words, if a user
  uses a service via a Main UI, then says exit, then double clicks once again on the service icon,
  the client can just simply invoke a UI factory method again, and get another Main UI for the same
  service. Main UIs, therefore, should be written so that they work no matter what state
  the service object happens to be in when the Main UI is created.

  <P>
  It is recommended that clients use multiple Main UIs for the same service only sequentially, and
  avoid creating multiple Main UIs for the same service that operate concurrently with one another.
  But because some clients may create and use multiple Main UIs at the same time for the same service,
  providers of services and main UIs should program defensively, to ensure that multiple Main UIs
  for the same service at the same time will all work together concurrently.
 <H3>11.7.1. Field <CODE>ROLE</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>ROLE</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>role</CODE>
  field of <CODE>UIDescriptor</CODE>s for MainUI role UIs.
  The value of this constant is <CODE>"net.jini.lookup.ui.MainUI"</CODE>.
 <H1>12. Package <CODE>net.jini.lookup.ui.factory</CODE></H1>
 Provides UI factory interfaces used to associate service UIs with Jini services.
 <H2>12.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui.factory</CODE></H2>
 <UL>
 <LI><CODE>DialogFactory</CODE> - UI factory for a modal or non-modal AWT <CODE>Dialog</CODE> with a
  predetermined title.
 <LI><CODE>FrameFactory</CODE> - UI factory for an AWT <CODE>Frame</CODE> with a predetermined
  title.
 <LI><CODE>JComponentFactory</CODE> - UI factory for a Swing <CODE>JComponent</CODE>.
 <LI><CODE>JDialogFactory</CODE> - UI factory for a modal or non-modal Swing <CODE>JDialog</CODE>
  with a predetermined title.
 <LI><CODE>JFrameFactory</CODE> - UI factory for a Swing <CODE>JFrame</CODE> with a predetermined
  title.
 <LI><CODE>JWindowFactory</CODE> - UI factory for a Swing <CODE>JWindow</CODE>.
 <LI><CODE>PanelFactory</CODE> - UI factory for an AWT <CODE>Panel</CODE>.
 <LI><CODE>WindowFactory</CODE> - UI factory for an AWT <CODE>Window</CODE> that isn't a <CODE>Frame</CODE>
  or a <CODE>Dialog</CODE>.
 </UL>
 <H2>12.2. Summary of Classes In Package <CODE>net.jini.lookup.ui.factory</CODE></H2>
 <P>No classes are declared in package <CODE>net.jini.lookup.ui.factory</CODE>.
 <H2>12.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui.factory</CODE></H2>
 <P>No <CODE>Exception</CODE>s are declared in package <CODE>net.jini.lookup.ui.factory</CODE>.
 <H2>12.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui.factory</CODE></H2>
 <P>No <CODE>Error</CODE>s are declared in package <CODE>net.jini.lookup.ui.factory</CODE>.
 <H2>12.5. Interface <CODE>net.jini.lookup.ui.factory.DialogFactory</CODE></H2>
 <P><CODE>public interface DialogFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for a modal or non-modal AWT <CODE>Dialog</CODE> with a
  predetermined title.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.5.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>DialogFactory</CODE>.
  The value of this constant is <CODE>"java.awt"</CODE>.
 <H3>12.5.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>DialogFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.DialogFactory"</CODE>.
 <H3>12.5.3. Method <CODE>getDialog(java.lang.Object, java.awt.Dialog)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Dialog <STRONG>getDialog</STRONG>(java.lang.Object roleObject, java.awt.Dialog owner)<BR>
 </CODE>
 <P>
 Returns a non-modal <CODE>Dialog</CODE> with predetermined title
  and the specified owner <CODE>Dialog</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Dialog</code> to act as owner of the returned
  <code>Dialog</code></DD>
 </DL>
 <H3>12.5.4. Method <CODE>getDialog(java.lang.Object, java.awt.Frame)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Dialog <STRONG>getDialog</STRONG>(java.lang.Object roleObject, java.awt.Frame owner)<BR>
 </CODE>
 <P>
 Returns a non-modal <CODE>Dialog</CODE> with predetermined title and the
  specified owner <CODE>Frame</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>Dialog</code></DD>
 </DL>
 <H3>12.5.5. Method <CODE>getDialog(java.lang.Object, java.awt.Dialog, boolean)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Dialog <STRONG>getDialog</STRONG>(java.lang.Object roleObject, java.awt.Dialog owner, boolean modal)<BR>
 </CODE>
 <P>
 Returns a <CODE>Dialog</CODE> with predetermined title and the
  specified modality and owner <CODE>Dialog</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Dialog</code> to act as owner of the returned
  <code>Dialog</code></DD>
 <DD><CODE>modal</CODE> - if <code>true</code>, the returned <code>Dialog</code> will block
  input to other windows when shown</DD>
 </DL>
 <H3>12.5.6. Method <CODE>getDialog(java.lang.Object, java.awt.Frame, boolean)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Dialog <STRONG>getDialog</STRONG>(java.lang.Object roleObject, java.awt.Frame owner, boolean modal)<BR>
 </CODE>
 <P>
 Returns a <CODE>Dialog</CODE> with predetermined title and the
  specified modality and owner <CODE>Frame</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>Dialog</code></DD>
 <DD><CODE>modal</CODE> - if <code>true</code>, the returned <code>Dialog</code> will block
  input to other windows when shown</DD>
 </DL>
 <H2>12.6. Interface <CODE>net.jini.lookup.ui.factory.FrameFactory</CODE></H2>
 <P><CODE>public interface FrameFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for an AWT <CODE>Frame</CODE> with a predetermined
  title.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.6.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>FrameFactory</CODE>.
  The value of this constant is <CODE>"java.awt"</CODE>.
 <H3>12.6.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>FrameFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.FrameFactory"</CODE>.
 <H3>12.6.3. Method <CODE>getFrame(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Frame <STRONG>getFrame</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a <CODE>Frame</CODE> with predetermined title.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 </DL>
 <H2>12.7. Interface <CODE>net.jini.lookup.ui.factory.JComponentFactory</CODE></H2>
 <P><CODE>public interface JComponentFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for a Swing <CODE>JComponent</CODE>.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.7.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>JComponentFactory</CODE>.
  The value of this constant is <CODE>"javax.swing"</CODE>.
 <H3>12.7.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>JComponentFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.JComponentFactory"</CODE>.
 <H3>12.7.3. Method <CODE>getJComponent(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JComponent <STRONG>getJComponent</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a <CODE>JComponent</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 </DL>
 <H2>12.8. Interface <CODE>net.jini.lookup.ui.factory.JDialogFactory</CODE></H2>
 <P><CODE>public interface JDialogFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for a modal or non-modal Swing <CODE>JDialog</CODE>
  with a predetermined title.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.8.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>JDialogFactory</CODE>.
  The value of this constant is <CODE>"javax.swing"</CODE>.
 <H3>12.8.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>JDialogFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.JDialogFactory"</CODE>.
 <H3>12.8.3. Method <CODE>getJDialog(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JDialog <STRONG>getJDialog</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a non-modal <CODE>JDialog</CODE> with
  predetermined title and no specified owner.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 </DL>
 <H3>12.8.4. Method <CODE>getJDialog(java.lang.Object, java.awt.Dialog)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JDialog <STRONG>getJDialog</STRONG>(java.lang.Object roleObject, java.awt.Dialog owner)<BR>
 </CODE>
 <P>
 Returns a non-modal <CODE>JDialog</CODE> with a
  predetermined title with the specified owner <CODE>Dialog</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Dialog</code> to act as owner of the returned
  <code>JDialog</code></DD>
 </DL>
 <H3>12.8.5. Method <CODE>getJDialog(java.lang.Object, java.awt.Frame)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JDialog <STRONG>getJDialog</STRONG>(java.lang.Object roleObject, java.awt.Frame owner)<BR>
 </CODE>
 <P>
 Returns a non-modal <CODE>JDialog</CODE> with a
  predetermined title with the specified owner </CODE>Frame</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>JDialog</code></DD>
 </DL>
 <H3>12.8.6. Method <CODE>getJDialog(java.lang.Object, java.awt.Dialog, boolean)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JDialog <STRONG>getJDialog</STRONG>(java.lang.Object roleObject, java.awt.Dialog owner, boolean modal)<BR>
 </CODE>
 <P>
 Returns a <CODE>JDialog</CODE> with predetermined title and the
  specified modality and owner <CODE>Dialog</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Dialog</code> to act as owner of the returned
  <code>JDialog</code></DD>
 <DD><CODE>modal</CODE> - if <code>true</code>, the returned <code>JDialog</code> will block
  input to other windows when shown</DD>
 </DL>
 <H3>12.8.7. Method <CODE>getJDialog(java.lang.Object, java.awt.Frame, boolean)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JDialog <STRONG>getJDialog</STRONG>(java.lang.Object roleObject, java.awt.Frame owner, boolean modal)<BR>
 </CODE>
 <P>
 Returns a <CODE>JDialog</CODE> with predetermined title and the
  specified modality and owner <CODE>Frame</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>JDialog</code></DD>
 <DD><CODE>modal</CODE> - if <code>true</code>, the returned <code>JDialog</code> will block
  input to other windows when shown</DD>
 </DL>
 <H2>12.9. Interface <CODE>net.jini.lookup.ui.factory.JFrameFactory</CODE></H2>
 <P><CODE>public interface JFrameFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for a Swing <CODE>JFrame</CODE> with a predetermined
  title.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.9.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>JFrameFactory</CODE>.
  The value of this constant is <CODE>"javax.swing"</CODE>.
 <H3>12.9.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>JFrameFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.JFrameFactory"</CODE>.
 <H3>12.9.3. Method <CODE>getJFrame(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JFrame <STRONG>getJFrame</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a <CODE>JFrame</CODE> with predetermined title.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 </DL>
 <H2>12.10. Interface <CODE>net.jini.lookup.ui.factory.JWindowFactory</CODE></H2>
 <P><CODE>public interface JWindowFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for a Swing <CODE>JWindow</CODE>.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.10.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>JWindowFactory</CODE>.
  The value of this constant is <CODE>"javax.swing"</CODE>.
 <H3>12.10.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>JWindowFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.JWindowFactory"</CODE>.
 <H3>12.10.3. Method <CODE>getJWindow(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JWindow <STRONG>getJWindow</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a <CODE>JWindow</CODE> with no specified
  owner.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 </DL>
 <H3>12.10.4. Method <CODE>getJWindow(java.lang.Object, java.awt.Window)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JWindow <STRONG>getJWindow</STRONG>(java.lang.Object roleObject, java.awt.Window owner)<BR>
 </CODE>
 <P>
 Returns a <CODE>JWindow</CODE> with specified
  owner <CODE>Window</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Window</code> to act as owner of the returned
  <code>JWindow</code></DD>
 </DL>
 <H3>12.10.5. Method <CODE>getJWindow(java.lang.Object, java.awt.Frame)</CODE></H3>
 <P>
 <CODE>
 public javax.swing.JWindow <STRONG>getJWindow</STRONG>(java.lang.Object roleObject, java.awt.Frame owner)<BR>
 </CODE>
 <P>
 Returns a <CODE>JWindow</CODE> with specified
  owner <CODE>Frame</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>JWindow</code></DD>
 </DL>
 <H2>12.11. Interface <CODE>net.jini.lookup.ui.factory.PanelFactory</CODE></H2>
 <P><CODE>public interface PanelFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for an AWT <CODE>Panel</CODE>.

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.

  <P>A <CODE>PreferredTitle</CODE> may be placed in the attributes set to indicate
  a preferred title of a pop-up window containing this component.
 <H3>12.11.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>PanelFactory</CODE>.
  The value of this constant is <CODE>"java.awt"</CODE>.
 <H3>12.11.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>JPanelFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.PanelFactory"</CODE>.
 <H3>12.11.3. Method <CODE>getPanel(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Panel <STRONG>getPanel</STRONG>(java.lang.Object roleObject)<BR>
 </CODE>
 <P>
 Returns a <CODE>Panel</CODE>.
 <H2>12.12. Interface <CODE>net.jini.lookup.ui.factory.WindowFactory</CODE></H2>
 <P><CODE>public interface WindowFactory<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.io.Serializable<BR>
 </CODE>
 <P>
 UI factory for an AWT <CODE>Window</CODE> that isn't a <CODE>Frame</CODE>
  or a <CODE>Dialog</CODE>.
  AWT <CODE>Frame</CODE>s should be produced by a <CODE>FrameFactory</CODE>.
  AWT <CODE>Dialog</CODE>s should be produced by a <CODE>DialogFactory</CODE>.)

  <P>If the UI generated by the method declared in this interface implements
  <CODE>javax.accessibility.Accessible</CODE> and supports the Java Accessibility
  API, an <CODE>AccessibleUI</CODE> attribute
  should be placed in the <CODE>UIDescriptor</CODE>'s <CODE>attributes</CODE> set.
 <H3>12.12.1. Field <CODE>TOOLKIT</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TOOLKIT</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>toolkit</CODE>
  field of <CODE>UIDescriptor</CODE>s that contain a
  <CODE>WindowFactory</CODE>.
  The value of this constant is <CODE>"java.awt"</CODE>.
 <H3>12.12.2. Field <CODE>TYPE_NAME</CODE></H3>
 <P>
 <CODE>
 public static final <STRONG>TYPE_NAME</STRONG><BR>
 </CODE>
 <P>
 Convenience constant to use in the <CODE>UIFactoryTypes</CODE>
  set in the <CODE>attributes</CODE> set of <CODE>UIDescriptor</CODE>s
  that contain a <CODE>WindowFactory</CODE>.
  The value of this constant is <CODE>"net.jini.lookup.ui.factory.WindowFactory"</CODE>.
 <H3>12.12.3. Method <CODE>getWindow(java.lang.Object, java.awt.Window)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Window <STRONG>getWindow</STRONG>(java.lang.Object roleObject, java.awt.Window owner)<BR>
 </CODE>
 <P>
 Returns a <CODE>Window</CODE> with specified
  owner <CODE>Window</CODE>
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>roleObject</CODE> - an object defined by the semantics of the UI role interface
  implemented by the returned UI object. (UI role is indicated in the
  <code>role</code> field of <code>UIDescriptor</code>s.)</DD>
 <DD><CODE>owner</CODE> - the <code>Window</code> to act as owner of the returned
  <code>Window</code></DD>
 </DL>
 <H3>12.12.4. Method <CODE>getWindow(java.lang.Object, java.awt.Frame)</CODE></H3>
 <P>
 <CODE>
 public java.awt.Window <STRONG>getWindow</STRONG>(java.lang.Object roleObject, java.awt.Frame owner)<BR>
 </CODE>
 <P>
 Returns a <CODE>Window</CODE> with specified
  owner <CODE>Frame</CODE>
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>owner</CODE> - the <code>Frame</code> to act as owner of the returned
  <code>Window</code></DD>
 </DL>
 <H1>13. Package <CODE>net.jini.lookup.ui.attribute</CODE></H1>
 Provides attribute classes used to associate service UIs with Jini services.
 <H2>13.1. Summary of Interfaces In Package <CODE>net.jini.lookup.ui.attribute</CODE></H2>
 <P>No interfaces are declared in package <CODE>net.jini.lookup.ui.attribute</CODE>.
 <H2>13.2. Summary of Classes In Package <CODE>net.jini.lookup.ui.attribute</CODE></H2>
 <UL>
 <LI><CODE>AccessibleUI</CODE> - UI attribute that indicates a generated
  UI implements the the <CODE>javax.accessibility.Accessible</CODE> interface
  and that the designer of the UI did the necessary work to make sure the UI
  would work well with assistive technologies that are aware of the Java Accessibility API.
 <LI><CODE>Locales</CODE> - UI attribute that lists the locales supported
  by a generated UI.
 <LI><CODE>RequiredPackages</CODE> - UI attribute that enables clients to get a list of
  the fully qualified names and version numbers of packages
  required by a UI.
 <LI><CODE>UIFactoryTypes</CODE> - UI attribute that lists UI factory interfaces of which a UI factory
  is an instance.
 </UL>
 <H2>13.3. Summary of <CODE>Exception</CODE>s In Package <CODE>net.jini.lookup.ui.attribute</CODE></H2>
 <P>No <CODE>Exception</CODE>s are declared in package <CODE>net.jini.lookup.ui.attribute</CODE>.
 <H2>13.4. Summary of <CODE>Error</CODE>s In Package <CODE>net.jini.lookup.ui.attribute</CODE></H2>
 <P>No <CODE>Error</CODE>s are declared in package <CODE>net.jini.lookup.ui.attribute</CODE>.
 <H2>13.5. Class <CODE>net.jini.lookup.ui.attribute.AccessibleUI</CODE></H2>
 <P><CODE>public class AccessibleUI<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.lang.Object<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;implements java.io.Serializable<BR>
 </CODE>
 <P>
 UI attribute that indicates a generated
  UI implements the the <CODE>javax.accessibility.Accessible</CODE> interface
  and that the designer of the UI did the necessary work to make sure the UI
  would work well with assistive technologies that are aware of the Java Accessibility API.

  <P>
  Only <CODE>UIDescriptor</CODE>s whose marshalled UI factory produces
  a UI that supports the Accessibility API should include this attribute.
  The presence of this attribute in an attribute set means the produced
  UI will work well with assistive technologies that are aware of the Java
  Accessibility API.
 <H3>13.5.1. Constructor <CODE>AccessibleUI()</CODE></H3>
 <P>
 <CODE>
 public <STRONG>AccessibleUI</STRONG>()<BR>
 </CODE>
 <P>
 Constructs a new <code>AccessibleUI</code> attribute.<H3>13.5.2. Method <CODE>equals(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>equals</STRONG>(java.lang.Object o)<BR>
 </CODE>
 <P>
 Compares the specified object (passed in <CODE>o</CODE>) with this
  <CODE>AccessibleUI</CODE> object for equality. Returns <CODE>true</CODE> if
  <CODE>o</CODE> is non-<code>null</code> and the fully qualified class name of the specified object (passed
  in <CODE>o</CODE>) is the same as the fully qualified class name of this object.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>o</CODE> - the object to compare against</DD>
 </DL>
 <H3>13.5.3. Method <CODE>hashCode()</CODE></H3>
 <P>
 <CODE>
 public int <STRONG>hashCode</STRONG>()<BR>
 </CODE>
 <P>
 Returns the hash code value for this <CODE>AccessibleUI</CODE>. As
  all <CODE>AccessibleUI</CODE> objects are conceptually equivalent, this
  method returns the hash code value for this object's fully qualified
  class name <code>String</code>.
 <H3>13.5.4. Serialized Form of <CODE>net.jini.lookup.ui.attribute.AccessibleUI</CODE></H3>
 <P>
 Serialized form of class
 <CODE>net.jini.lookup.ui.attribute.AccessibleUI</CODE>
  has no serialized fields.
 <H2>13.6. Class <CODE>net.jini.lookup.ui.attribute.Locales</CODE></H2>
 <P><CODE>public class Locales<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.lang.Object<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;implements java.io.Serializable<BR>
 </CODE>
 <P>
 UI attribute that lists the locales supported
  by a generated UI.
 <H3>13.6.1. Constructor <CODE>Locales(java.util.Set)</CODE></H3>
 <P>
 <CODE>
 public <STRONG>Locales</STRONG>(java.util.Set locales)<BR>
 </CODE>
 <P>
 Constructs a <CODE>Locales</CODE> using the
  passed <CODE>Set</CODE>. The <CODE>Set</CODE> can
  be mutable or immutable, and must contain only
  <CODE>java.util.Locale</CODE> objects. Each <CODE>Locale</CODE> must
  represent a locale that is supported by the UI generated
  by the UI factory stored in marshalled form in the
  same <CODE>UIDescriptor</CODE>. This constructor copies
  the contents of the passed <code>Set</code> into a
  serializable read-only <code>Set</code> that has a
  consistent serialized form across all VMs.<DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>locales</CODE> - A <CODE>Set</CODE> of <CODE>Locale</CODE>
  objects. Each element must be non-null and an instance
  of <CODE>java.util.Locale</CODE>.</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>locales</CODE>
  is <CODE>null</CODE> or any element of <CODE>locales</CODE>
  set is <CODE>null</CODE>.</DD>
 <DD><CODE>IllegalArgumentException</CODE> - if any non-null element of
  <CODE>locales</CODE> set is not an instance of
  <CODE>java.util.Locale</CODE>.</DD>
 </DL>
 <H3>13.6.2. Method <CODE>isLocaleSupported(java.util.Locale)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>isLocaleSupported</STRONG>(java.util.Locale locale)<BR>
 </CODE>
 <P>
 Indicates whether or not a locale is supported
  by the UI generated by the UI factory stored in
  the marshalled object of the same <CODE>UIDescriptor</CODE>.
  This method returns <CODE>true</CODE> only if the passed
  <CODE>Locale</CODE> exactly matches a <CODE>Locale</CODE>
  supported by the UI, as defined by the <CODE>equals()</CODE>
  method of class <CODE>java.util.Locale</CODE>. For example, imagine the UI supports the
  "en" (General English) locale, but not the "en_US" (US English) locale.
  Then, if "en_US" is passed to this method, the method will return
  <CODE>false</CODE>.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>locale</CODE> - the locale to check</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>locale</CODE>
  is <CODE>null</CODE>.</DD>
 </DL>
 <H3>13.6.3. Method <CODE>getFirstSupportedLocale(java.util.Locale[])</CODE></H3>
 <P>
 <CODE>
 public java.util.Locale <STRONG>getFirstSupportedLocale</STRONG>(java.util.Locale[] locales)<BR>
 </CODE>
 <P>
 Looks through the passed array of <CODE>Locale</CODE>s
  (in the order they appear in the array)
  and returns the first <CODE>Locale</CODE> that is
  supported by the UI (as defined by <CODE>isLocaleSupported()</CODE>),
  or <CODE>null</CODE>, if none of the <CODE>Locale</CODE>s in
  the passed array are supported by the UI.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>locales</CODE> - an array of locales in order of most desired to
      least desired</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>locales</CODE>
  is <CODE>null</CODE>.</DD>
 </DL>
 <H3>13.6.4. Method <CODE>getFirstSupportedLocale(java.util.List)</CODE></H3>
 <P>
 <CODE>
 public java.util.Locale <STRONG>getFirstSupportedLocale</STRONG>(java.util.List locales)<BR>
 </CODE>
 <P>
 Iterates through the passed <CODE>List</CODE> of <CODE>Locale</CODE>s
  and returns the first <CODE>Locale</CODE> that is
  supported by the UI (as defined by <CODE>isLocaleSupported()</CODE>),
  or <CODE>null</CODE>, if none of the <CODE>Locale</CODE>s in
  the passed array are supported by the UI.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>locales</CODE> - a <code>List</code> of locales in order of most
       desired to least desired</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>locales</CODE>
  is <CODE>null</CODE>.</DD>
 </DL>
 <H3>13.6.5. Method <CODE>iterator()</CODE></H3>
 <P>
 <CODE>
 public java.util.Iterator <STRONG>iterator</STRONG>()<BR>
 </CODE>
 <P>
 Returns an iterator over the set of <CODE>java.util.Locale</CODE>
  objects, one for each locale supported
  by the UI generated by the UI factory stored in
  the marshalled object of the same <CODE>UIDescriptor</CODE>.
  The returned <CODE>Iterator</CODE> does not support
  <CODE>remove()</CODE>.
 <H3>13.6.6. Method <CODE>getLocales()</CODE></H3>
 <P>
 <CODE>
 public java.util.Set <STRONG>getLocales</STRONG>()<BR>
 </CODE>
 <P>
 Returns an unmodifiable <CODE>java.util.Set</CODE> that contains
  <CODE>java.util.Locale</CODE> objects, one for each locale supported
  by the UI generated by the UI factory stored in
  the marshalled object of the same <CODE>UIDescriptor</CODE>.
 <H3>13.6.7. Method <CODE>equals(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>equals</STRONG>(java.lang.Object o)<BR>
 </CODE>
 <P>
 Compares the specified object (the <CODE>Object</CODE> passed
  in <CODE>o</CODE>) with this <CODE>Locales</CODE>
  object for equality. Returns true if the specified object
  is not null, if the specified object's class is
  <CODE>Locales</CODE>, if the two sets of
  supported locales are the same size, and if every locale mentioned in the
  specified <CODE>Locales</CODE> object (passed in <CODE>o</CODE>) is also mentioned
  in this <CODE>Locales</CODE> object.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>o</CODE> - the object to compare against</DD>
 </DL>
 <H3>13.6.8. Method <CODE>hashCode()</CODE></H3>
 <P>
 <CODE>
 public int <STRONG>hashCode</STRONG>()<BR>
 </CODE>
 <P>
 Returns the hash code value for this <CODE>Locales</CODE> object.
 <H3>13.6.9. Serialized Form of <CODE>net.jini.lookup.ui.attribute.Locales</CODE></H3>
 <H4>13.6.9.1. Serialized Field <CODE>supportedLocales</CODE></H4>
 <P>
 <CODE>
 java.util.Set <STRONG>supportedLocales</STRONG><BR>
 </CODE>
 <P>
 A <code>Set</code> of <code>java.util.Locale</code> objects,
      each of which represents one locale supported by the UI generated
      by the UI factory stored in marshalled form in the same
      <code>UIDescriptor</code>.
 <H2>13.7. Class <CODE>net.jini.lookup.ui.attribute.RequiredPackages</CODE></H2>
 <P><CODE>public class RequiredPackages<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.lang.Object<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;implements java.io.Serializable<BR>
 </CODE>
 <P>
 UI attribute that enables clients to get a list of
  the fully qualified names and version numbers of packages
  required by a UI.

  <P>
  One or more <CODE>RequiredPackages</CODE> attributes may appear
  in the attributes of a <CODE>UIDescriptor</CODE>. Client programs
  interested in a UI may wish to verify that they have all required
  packages mentioned in the <CODE>RequiredPackages</CODE> attributes
  (if any) contained in the UI's <CODE>UIDescriptor</CODE>, before
  they attempt to create the UI. If the client is lacking any required
  packages (either because the entire package is absent or because the
  package is present but of an incompatible version), the client will
  not be able to use the UI,

  <P>
  The intent of this attribute is to provide a quick way for a client program
  to determine that a UI is unusable by a client, not to grant a guarantee that a UI
  is definitely usable by the client. If a client is missing a required package,
  or has an incompatible version of a required package, the client cannot use the UI.
  But if the client has compatible versions of all required packages listed in a
  <CODE>RequiredPackage</CODE> attribute, the client may or may not be able to
  use the UI.

  <P>
  UI providers should take bold and valiant strides to list in a <CODE>RequiredPackage</CODE>
  attribute all known packages required of the client, so that if
  the client discovers it has compatible versions of all listed packages and
  attempts to generate the UI via the factory method, the client will likely
  succeed. However, client programmers should bear in mind that a
  <CODE>RequiredPackage</CODE> attribute doesn't necessarily list
  <EM>all</EM> required packages. As a result, satisfying all required packages
  doesn't absolutely guarantee the UI will work on the client.
  As a result, client programs should program defensively.
  (For example, clients should probably catch <CODE>LinkageError</CODE>
  in appropriate places when dealing with UIs, even if they find they have
  compatible versions of all required packages listed in <CODE>RequiredPackage</CODE>
  attributes.)

  The version numbers must take the form of "specification version numbers," as used
  by the <CODE>java.lang.Package</CODE> class:

  <BLOCKQUOTE>
  Specification version numbers use a "Dewey Decimal" syntax that consists of positive
  decimal integers separated by periods ".", for example, "2.0" or "1.2.3.4.5.6.7". This
  allows an extensible number to be used to represent major, minor, micro, etc versions.
  The version number must begin with a number.
  </BLOCKQUOTE>
 <H3>13.7.1. Constructor <CODE>RequiredPackages(java.util.Map)</CODE></H3>
 <P>
 <CODE>
 public <STRONG>RequiredPackages</STRONG>(java.util.Map packages)<BR>
 </CODE>
 <P>
 Constructs a <CODE>RequiredPackages</CODE> attribute
  with the passed <CODE>Map</CODE>. The keys contained
  in the passed <CODE>Map</CODE> must be <CODE>String</CODE>s
  that represent fully qualified names of required packages.
  Each value contained in the passed <CODE>Map</CODE> must
  be the oldest version number of the package (defined by the
  key) that is compatible with the UI. Version numbers are
  <CODE>String</CODE>s in the form of
  "specification version numbers," as used
  by the <CODE>java.lang.Package</CODE> class. This constructor copies
  the contents of the passed <code>Map</code> into a
  serializable unmodifiable <code>Map</code> that has a
  consistent serialized form across all VMs.<DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>packages</CODE> - a map of <code>String</code> fully qualified
  names of required packages to <code>String</code> version
  numbers</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>packages</CODE>
  is <CODE>null</CODE> or if any keys or values contained
  in <CODE>packages</CODE> are <CODE>null</CODE>.</DD>
 <DD><CODE>IllegalArgumentException</CODE> - if any non-null key or
  value contained in <CODE>packages</CODE> set is not an instance of
  <CODE>java.lang.String</CODE>.</DD>
 </DL>
 <H3>13.7.2. Method <CODE>iterator()</CODE></H3>
 <P>
 <CODE>
 public java.util.Iterator <STRONG>iterator</STRONG>()<BR>
 </CODE>
 <P>
 Returns an iterator over the set of <CODE>String</CODE>
  fully qualified package names required
  by the UI generated by the UI factory stored in
  the marshalled object of the same <CODE>UIDescriptor</CODE>.
  The returned <CODE>Iterator</CODE> does not support
  <CODE>remove()</CODE>.
 <H3>13.7.3. Method <CODE>getVersion(java.lang.String)</CODE></H3>
 <P>
 <CODE>
 public java.lang.String <STRONG>getVersion</STRONG>(java.lang.String packageName)<BR>
 </CODE>
 <P>
 Returns a version number for the required package
  whose fully qualified package name is passed as
  the <CODE>packageName</CODE> parameter. If the
  passed <CODE>String</CODE> does not represent a
  required package listed in this <CODE>RequiredPackage</CODE>
  attribute, this method returns <CODE>null</CODE>.

  The version number returned should be a "specification version number," as used
  by the <CODE>java.lang.Package</CODE> class:

  <BLOCKQUOTE>
  Specification version numbers use a "Dewey Decimal" syntax that consists of positive
  decimal integers separated by periods ".", for example, "2.0" or "1.2.3.4.5.6.7". This
  allows an extensible number to be used to represent major, minor, micro, etc versions.
  The version number must begin with a number.
  </BLOCKQUOTE>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>packageName</CODE>
  is <CODE>null</CODE>.</DD>
 </DL>
 <H3>13.7.4. Method <CODE>getRequiredPackages()</CODE></H3>
 <P>
 <CODE>
 public java.util.Map <STRONG>getRequiredPackages</STRONG>()<BR>
 </CODE>
 <P>
 Returns a <CODE>java.util.Map</CODE> whose keys
  are <CODE>String</CODE>s that represent fully
  qualified names of required packages and whose
  values are be the oldest version number of the
  package (defined by the
  key) that is compatible with the UI. Version numbers are
  <CODE>String</CODE>s in the form of
  "specification version numbers," as used
  by the <CODE>java.lang.Package</CODE> class:

  The version numbers contained as values in the returned <CODE>Map</CODE>
  should be a "specification version number," as used
  by the <CODE>java.lang.Package</CODE> class:

  <BLOCKQUOTE>
  Specification version numbers use a "Dewey Decimal" syntax that consists of positive
  decimal integers separated by periods ".", for example, "2.0" or "1.2.3.4.5.6.7". This
  allows an extensible number to be used to represent major, minor, micro, etc versions.
  The version number must begin with a number.
  </BLOCKQUOTE>
 <H3>13.7.5. Method <CODE>equals(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>equals</STRONG>(java.lang.Object o)<BR>
 </CODE>
 <P>
 Compares the specified object (the <CODE>Object</CODE> passed
  in <CODE>o</CODE>) with this <CODE>RequiredPackages</CODE>
  object for equality. Returns true if the specified object
  is not null, if the specified object's class is
  <CODE>RequiredPackages</CODE>, if the two sets of
  package-version pairs are the same size, and if every package-version pair mentioned in the
  specified <CODE>RequiredPackages</CODE> object (passed in <CODE>o</CODE>) is also mentioned
  in this <CODE>RequiredPackages</CODE> object.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>o</CODE> - the object to compare against</DD>
 </DL>
 <H3>13.7.6. Method <CODE>hashCode()</CODE></H3>
 <P>
 <CODE>
 public int <STRONG>hashCode</STRONG>()<BR>
 </CODE>
 <P>
 Returns the hash code value for this <CODE>RequiredPackages</CODE> object.
 <H3>13.7.7. Serialized Form of <CODE>net.jini.lookup.ui.attribute.RequiredPackages</CODE></H3>
 <H4>13.7.7.1. Serialized Field <CODE>requiredPackages</CODE></H4>
 <P>
 <CODE>
 java.util.Map <STRONG>requiredPackages</STRONG><BR>
 </CODE>
 <P>
 A <code>Map</code> of <code>String</code> keys to
      <code>String</code> values.  The keys contained
      in the <CODE>Map</CODE> must be <CODE>String</CODE>s
      that represent fully qualified names of required packages.
      Each value contained in the <CODE>Map</CODE> must
      be the oldest version number of the package (defined by the
      key) that is compatible with the UI. Version numbers are
      <CODE>String</CODE>s in the form of "specification version
      numbers," as used by the <CODE>java.lang.Package</CODE> class.
 <H2>13.8. Class <CODE>net.jini.lookup.ui.attribute.UIFactoryTypes</CODE></H2>
 <P><CODE>public class UIFactoryTypes<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extends java.lang.Object<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;implements java.io.Serializable<BR>
 </CODE>
 <P>
 UI attribute that lists UI factory interfaces of which a UI factory
  is an instance.
 <H3>13.8.1. Constructor <CODE>UIFactoryTypes(java.util.Set)</CODE></H3>
 <P>
 <CODE>
 public <STRONG>UIFactoryTypes</STRONG>(java.util.Set typeNames)<BR>
 </CODE>
 <P>
 Constructs a <CODE>UIFactoryTypes</CODE> attribute using the
  passed <CODE>Set</CODE>. The <CODE>Set</CODE> can
  be mutable or immutable, and must contain only
  <CODE>String</CODE>s. Each <CODE>String</CODE> should
  represent a fully qualified Java type name of a UI factory
  interface. This constructor copies
  the contents of the passed <code>Set</code> into a
  serializable read-only <code>Set</code> that has a
  consistent serialized form across all VMs.

  <P>
  The <code>isAssignableTo</code> method of this class will only
  return <code>true</code> for types whose names are passed
  explicitly to this constructor via the <CODE>typeNames</CODE> parameter.
  This constructor does not inspect the inheritance hierarchies of the
  types whose names are passed via the <code>typeNames</code>
  parameter. It is the client's responsibility to include the name of
  every UI factory interface of which the relevant UI factory (the UI factory being described
  by this class) is an instance.<DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>typeNames</CODE> - A <CODE>Set</CODE> of <CODE>String</CODE>
  objects. Each element must be non-null and an instance
  of <CODE>java.lang.String</CODE>.</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>typeNames</CODE>
  is <CODE>null</CODE> or any element of <CODE>typeNames</CODE>
  set is <CODE>null</CODE>.</DD>
 <DD><CODE>IllegalArgumentException</CODE> - if any non-null element of
  <CODE>typeNames</CODE> set is not an instance of
  <CODE>java.lang.String</CODE>.</DD>
 </DL>
 <H3>13.8.2. Method <CODE>isAssignableTo(java.lang.Class)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>isAssignableTo</STRONG>(java.lang.Class classObj)<BR>
 </CODE>
 <P>
 Returns <CODE>true</CODE> if the UI factory (contained in
  marshalled form in the same <CODE>UIDescriptor</CODE>) is
  an instance of the UI factory interface
  type passed in parameter <CODE>classObj</CODE>.
  Else, returns <CODE>false</CODE>.

  <P>
  This method compares the fully qualified name
  of the type represented by the passed <CODE>Class</CODE> with
  the fully qualified names of UI factory interfaces implemented
  by the UI factory's class. If
  an exact string match is found, this method returns <CODE>true</CODE>.
  If the UI factory is ultimately loaded with a class loader whose
  parent-delegation chain doesn't include the class loader
  that defined the passed class, a type with the same name
  would be loaded into a different namespace of
  the virtual machine. If so, the two types would
  be considered different by the virtual machine, even though
  they shared the same fully qualified name.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>classObj</CODE> - the type to check</DD>
 </DL>
 <DL>
 <DT><STRONG>Throws:</STRONG></DT>
 <DD><CODE>NullPointerException</CODE> - if <CODE>classObj</CODE>
  is <CODE>null</CODE></DD>
 </DL>
 <H3>13.8.3. Method <CODE>iterator()</CODE></H3>
 <P>
 <CODE>
 public java.util.Iterator <STRONG>iterator</STRONG>()<BR>
 </CODE>
 <P>
 Returns an iterator over the set of types of which
  a UI factory object is an instance in no particular order.
  The returned <CODE>Iterator</CODE> does not support
  <CODE>remove()</CODE>.
 <H3>13.8.4. Method <CODE>getTypeNames()</CODE></H3>
 <P>
 <CODE>
 public java.util.Set <STRONG>getTypeNames</STRONG>()<BR>
 </CODE>
 <P>
 Returns an unmodifiable Set of fully qualified type name
  <CODE>String</CODE>s of which
  a UI factory is an instance in no particular order.
 <H3>13.8.5. Method <CODE>equals(java.lang.Object)</CODE></H3>
 <P>
 <CODE>
 public boolean <STRONG>equals</STRONG>(java.lang.Object o)<BR>
 </CODE>
 <P>
 Compares the specified object (the <CODE>Object</CODE> passed
  in <CODE>o</CODE>) with this <CODE>UIFactoryTypes</CODE>
  object for equality. Returns true if the specified object
  is not null, if the specified object's class is
  <CODE>UIFactoryTypes</CODE>, if the two sets of
  factory types are the same size, and if every factory type mentioned in the
  specified <CODE>UIFactoryTypes</CODE> object (passed in <CODE>o</CODE>) is also mentioned
  in this <CODE>UIFactoryTypes</CODE> object.
 <DL>
 <DT><STRONG>Parameters:</STRONG></DT>
 <DD><CODE>o</CODE> - the object to compare against</DD>
 </DL>
 <H3>13.8.6. Method <CODE>hashCode()</CODE></H3>
 <P>
 <CODE>
 public int <STRONG>hashCode</STRONG>()<BR>
 </CODE>
 <P>
 Returns the hash code value for this <CODE>UIFactoryTypes</CODE> object.
 <H3>13.8.7. Serialized Form of <CODE>net.jini.lookup.ui.attribute.UIFactoryTypes</CODE></H3>
 <H4>13.8.7.1. Serialized Field <CODE>typeNames</CODE></H4>
 <P>
 <CODE>
 java.util.Set <STRONG>typeNames</STRONG><BR>
 </CODE>
 <P>
 A <code>Set</code> of <code>String</code>s,
      each of which represents one fully qualified type name.
      Each <code>String</code> type name should indicate one
      UI factory interface implemented by the UI factory contained
      in marshalled form in the same <code>UIDescriptor</code> in
      which this <code>UIFactoryTypes</code> appears.
 </P>
 <hr>
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership. The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License. You may obtain a copy of the License at
 <ul>
      <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
 </ul>
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

 </body>
 </html>