java.lang
Class Package

java.lang.Object
  extended by java.lang.Package
All Implemented Interfaces:
AnnotatedElement

public class Package
extends Object
implements AnnotatedElement

Everything you ever wanted to know about a package. This class makes it possible to attach specification and implementation information to a package as explained in the Package Versioning Specification section of the Product Versioning Specification. It also allows packages to be sealed with respect to the originating URL.

The most useful method is the isCompatibleWith() method that compares a desired version of a specification with the version of the specification as implemented by a package. A package is considered compatible with another version if the version of the specification is equal or higher then the requested version. Version numbers are represented as strings of positive numbers separated by dots (e.g. "1.2.0"). The first number is called the major number, the second the minor, the third the micro, etc. A version is considered higher then another version if it has a bigger major number then the another version or when the major numbers of the versions are equal if it has a bigger minor number then the other version, etc. (If a version has no minor, micro, etc numbers then they are considered the be 0.)

Since:
1.2
See Also:
ClassLoader.definePackage(String, String, String, String, String, String, String, URL)

Method Summary
<A extends Annotation>
A
getAnnotation(Class<A> annotationClass)
          Returns this package's annotation for the specified annotation type, or null if no such annotation exists.
 Annotation[] getAnnotations()
          Returns all annotations associated with this package.
 Annotation[] getDeclaredAnnotations()
          Returns all annotations directly defined by this package.
 String getImplementationTitle()
          Returns the name of the implementation, or null if unknown.
 String getImplementationVendor()
          Returns the vendor that wrote this implementation, or null if unknown.
 String getImplementationVersion()
          Returns the version of this implementation, or null if unknown.
 String getName()
          Returns the Package name in dot-notation.
static Package getPackage(String name)
          Returns the named package if it is known by the callers class loader.
static Package[] getPackages()
          Returns all the packages that are known to the callers class loader.
 String getSpecificationTitle()
          Returns the name of the specification, or null if unknown.
 String getSpecificationVendor()
          Returns the name of the specification designer, or null if unknown.
 String getSpecificationVersion()
          Returns the version of the specification, or null if unknown.
 int hashCode()
          Returns the hashCode of the name of this package.
 boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
          Returns true if an annotation for the specified type is associated with this package.
 boolean isCompatibleWith(String version)
          Checks if the version of the specification is higher or at least as high as the desired version.
 boolean isSealed()
          Returns true if this Package is sealed.
 boolean isSealed(URL url)
          Returns true if this Package is sealed and the origin of the classes is the given URL.
 String toString()
          Returns a string representation of this package.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getName

public String getName()
Returns the Package name in dot-notation.

Returns:
the non-null package name

getSpecificationTitle

public String getSpecificationTitle()
Returns the name of the specification, or null if unknown.

Returns:
the specification title

getSpecificationVersion

public String getSpecificationVersion()
Returns the version of the specification, or null if unknown.

Returns:
the specification version

getSpecificationVendor

public String getSpecificationVendor()
Returns the name of the specification designer, or null if unknown.

Returns:
the specification vendor

getImplementationTitle

public String getImplementationTitle()
Returns the name of the implementation, or null if unknown.

Returns:
the implementation title

getImplementationVersion

public String getImplementationVersion()
Returns the version of this implementation, or null if unknown.

Returns:
the implementation version

getImplementationVendor

public String getImplementationVendor()
Returns the vendor that wrote this implementation, or null if unknown.

Returns:
the implementation vendor

isSealed

public boolean isSealed()
Returns true if this Package is sealed.

Returns:
true if the package is sealed

isSealed

public boolean isSealed(URL url)
Returns true if this Package is sealed and the origin of the classes is the given URL.

Parameters:
url - the URL to test
Returns:
true if the package is sealed by this URL
Throws:
NullPointerException - if url is null

isCompatibleWith

public boolean isCompatibleWith(String version)
Checks if the version of the specification is higher or at least as high as the desired version. Comparison is done by sequentially comparing dotted decimal numbers from the parameter and from getSpecificationVersion.

Parameters:
version - the (minimal) desired version of the specification
Returns:
true if the version is compatible, false otherwise
Throws:
NumberFormatException - if either version string is invalid
NullPointerException - if either version string is null

getPackage

public static Package getPackage(String name)
Returns the named package if it is known by the callers class loader. It may return null if the package is unknown, when there is no information on that particular package available or when the callers classloader is null.

Parameters:
name - the name of the desired package
Returns:
the package by that name in the current ClassLoader

getPackages

public static Package[] getPackages()
Returns all the packages that are known to the callers class loader. It may return an empty array if the classloader of the caller is null.

Returns:
an array of all known packages

hashCode

public int hashCode()
Returns the hashCode of the name of this package.

Overrides:
hashCode in class Object
Returns:
the hash code
See Also:
Object.equals(Object), System.identityHashCode(Object)

toString

public String toString()
Returns a string representation of this package. It is specified to be "package " + getName() + (getSpecificationTitle() == null ? "" : ", " + getSpecificationTitle()) + (getSpecificationVersion() == null ? "" : ", version " + getSpecificationVersion()).

Overrides:
toString in class Object
Returns:
the string representation of the package
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

getAnnotation

public <A extends Annotation> A getAnnotation(Class<A> annotationClass)
Returns this package's annotation for the specified annotation type, or null if no such annotation exists.

Specified by:
getAnnotation in interface AnnotatedElement
Parameters:
annotationClass - the type of annotation to look for.
Returns:
this package's annotation for the specified type, or null if no such annotation exists.
Since:
1.5

getAnnotations

public Annotation[] getAnnotations()
Returns all annotations associated with this package. If there are no annotations associated with this package, then a zero-length array will be returned. The returned array may be modified by the client code, but this will have no effect on the annotation content of this package, and hence no effect on the return value of this method for future callers.

Specified by:
getAnnotations in interface AnnotatedElement
Returns:
this package' annotations.
Since:
1.5

getDeclaredAnnotations

public Annotation[] getDeclaredAnnotations()
Returns all annotations directly defined by this package. If there are no annotations associated with this package, then a zero-length array will be returned. The returned array may be modified by the client code, but this will have no effect on the annotation content of this package, and hence no effect on the return value of this method for future callers.

Specified by:
getDeclaredAnnotations in interface AnnotatedElement
Returns:
the annotations directly defined by this package.
Since:
1.5

isAnnotationPresent

public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
Returns true if an annotation for the specified type is associated with this package. This is primarily a short-hand for using marker annotations.

Specified by:
isAnnotationPresent in interface AnnotatedElement
Parameters:
annotationClass - the type of annotation to look for.
Returns:
true if an annotation exists for the specified type.
Since:
1.5