net.jini.lookup.ui.attribute

Class RequiredPackages

java.lang.Object

net.jini.lookup.ui.attribute.RequiredPackages

All Implemented Interfaces:

Serializable

public class RequiredPackages
extends Object
implements Serializable

UI attribute that enables clients to get a list of the fully qualified names and version numbers of packages required by a UI.

One or more RequiredPackages attributes may appear in the attributes of a UIDescriptor. Client programs interested in a UI may wish to verify that they have all required packages mentioned in the RequiredPackages attributes (if any) contained in the UI's UIDescriptor, 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,

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 RequiredPackage attribute, the client may or may not be able to use the UI.

UI providers should take bold and valiant strides to list in a RequiredPackage 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 RequiredPackage attribute doesn't necessarily list all 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 LinkageError in appropriate places when dealing with UIs, even if they find they have compatible versions of all required packages listed in RequiredPackage attributes.) The version numbers 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.

Author:

Bill Venners

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
RequiredPackages(Map packages) Constructs a RequiredPackages attribute with the passed Map.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o) Compares the specified object (the Object passed in o) with this RequiredPackages object for equality.
Map	getRequiredPackages() Returns a java.util.Map whose keys are Strings 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.
String	getVersion(String packageName) Returns a version number for the required package whose fully qualified package name is passed as the packageName parameter.
int	hashCode() Returns the hash code value for this RequiredPackages object.
Iterator	iterator() Returns an iterator over the set of String fully qualified package names required by the UI generated by the UI factory stored in the marshalled object of the same UIDescriptor.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RequiredPackages

public RequiredPackages(Map packages)

Constructs a RequiredPackages attribute with the passed Map. The keys contained in the passed Map must be Strings that represent fully qualified names of required packages. Each value contained in the passed Map must be the oldest version number of the package (defined by the key) that is compatible with the UI. Version numbers are Strings in the form of "specification version numbers," as used by the java.lang.Package class. This constructor copies the contents of the passed Map into a serializable unmodifiable Map that has a consistent serialized form across all VMs.

Parameters:

packages - a map of String fully qualified names of required packages to String version numbers

Throws:

NullPointerException - if packages is null or if any keys or values contained in packages are null.

IllegalArgumentException - if any non-null key or value contained in packages set is not an instance of java.lang.String.

Method Detail

iterator

public Iterator iterator()

Returns an iterator over the set of String fully qualified package names required by the UI generated by the UI factory stored in the marshalled object of the same UIDescriptor. The returned Iterator does not support remove().

Returns:

an iterator over the set of String fully qualified names for required packages

getVersion

public String getVersion(String packageName)

Returns a version number for the required package whose fully qualified package name is passed as the packageName parameter. If the passed String does not represent a required package listed in this RequiredPackage attribute, this method returns null. The version number returned should be a "specification version number," 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.

Returns:

the version number for the passed required package, or null if the passed package is not required

Throws:

NullPointerException - if packageName is null.

getRequiredPackages

public Map getRequiredPackages()

Returns a java.util.Map whose keys are Strings 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 Strings in the form of "specification version numbers," as used by the java.lang.Package class: The version numbers contained as values in the returned Map should be a "specification version number," 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.

Returns:

an unmodifiable map of package name keys to version number values

equals

public boolean equals(Object o)

Compares the specified object (the Object passed in o) with this RequiredPackages object for equality. Returns true if the specified object is not null, if the specified object's class is RequiredPackages, if the two sets of package-version pairs are the same size, and if every package-version pair mentioned in the specified RequiredPackages object (passed in o) is also mentioned in this RequiredPackages object.

Overrides:

equals in class Object

Parameters:

o - the object to compare against

Returns:

true if the objects are the same, false otherwise.

hashCode

public int hashCode()

Returns the hash code value for this RequiredPackages object.

Overrides:

hashCode in class Object

Returns:

the hashcode for this object