4. UI Attributes

The UI descriptor's attributes field references a java.util.Set 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 attributes field will be null.)

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 java.util.Set or null in the UI descriptor's attributes field. Nevertheless, because clients would know little about the UI represented by that UI descriptor, many clients would likely ignore the descriptor entirely.

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

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

The remainder of this section describes these four attribute classes in detail.

4.1. The `AccessibleUI` Attribute

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

The attribute should appear in a UIDescriptor'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.

The AccessibleUI attribute looks like this:

package net.jini.lookup.ui.attribute;

public class AccessibleUI implements java.io.Serializable {
}

4.2. The `Locales` Attribute

The Locales attribute lists locales supported by a generated UI.

Zero to many Locales instances may appear in a UI descriptor's attributes set. UI providers are encouraged to provide in any UI descriptor's attributes set one Locales 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.

The public interface of Locales looks like this:

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() {...}
}

4.3. The `RequiredPackages` Attribute

RequiredPackages lets clients obtain a list of fully qualified names and version numbers of packages a UI requires.

Zero to many RequiredPackages attributes may appear in a UIDescriptor's attributes set. Client programs interested in a UI may wish to verify that they have all required packages mentioned in the RequiredPackages 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.

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.

UI providers should attempt to list in a RequiredPackages 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 RequiredPackages attribute. The client does not actually require such packages, because if the client doesn't have them, it can download the packages.)

Client programmers should bear in mind that a RequiredPackages attribute doesn't necessarily list all 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 LinkageError in appropriate places when dealing with UIs, even if they have compatible versions of all required packages.)

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

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.

Here's what the RequiredPackages's public interface looks like:

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() {...}
}

4.4. The `UIFactoryTypes` Attribute

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

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

Of all attributes that could appear in the attributes set, UIFactoryTypes is perhaps the most important. If a UI descriptor's attributes set includes no UIFactoryTypes 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 UIFactoryTypes 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 net.jini.lookup.ui.factory package.

The public interface of UIFactoryTypes looks like this:

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() {...}
}

<< Page 6 of 12 >>


	Web Artima.com

4. UI Attributes

4.1. The AccessibleUI Attribute

4.2. The Locales Attribute

4.3. The RequiredPackages Attribute

4.4. The UIFactoryTypes Attribute

4.1. The `AccessibleUI` Attribute

4.2. The `Locales` Attribute

4.3. The `RequiredPackages` Attribute

4.4. The `UIFactoryTypes` Attribute