net.jini.lookup.ui.attribute
Class RequiredPackages

java.lang.Object
  |
  +--net.jini.lookup.ui.attribute.RequiredPackages

public class RequiredPackages
extends java.lang.Object
implements java.io.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.

See Also:
Serialized Form

Constructor Summary
RequiredPackages(java.util.Map packages)
          Constructs a RequiredPackages attribute with the passed Map.
 
Method Summary
 boolean equals(java.lang.Object o)
          Compares the specified object (the Object passed in o) with this RequiredPackages object for equality.
 java.util.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.
 java.lang.String getVersion(java.lang.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.
 java.util.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(java.util.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:
Throws:
NullPointerException - if packages is null or if any keys or values contained in packages are null.
java.lang.IllegalArgumentException - if any non-null key or value contained in packages set is not an instance of java.lang.String.
Method Detail

iterator

public java.util.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().

getVersion

public java.lang.String getVersion(java.lang.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.
Throws:
NullPointerException - if packageName is null.

getRequiredPackages

public java.util.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.

equals

public boolean equals(java.lang.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 java.lang.Object

hashCode

public int hashCode()
Returns the hash code value for this RequiredPackages object.
Overrides:
hashCode in class java.lang.Object