java.lang

Class Package

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

extends Annotation> A getAnnotation(Class 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(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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

extends Annotation> A getAnnotation

public extends Annotation> A getAnnotation(Class annotationClass)

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

getImplementationTitle

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

getImplementationVendor

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

getImplementationVersion

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

getName

public String getName()
Returns the Package name in dot-notation.
Returns:
the non-null package name

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

getSpecificationTitle

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

getSpecificationVendor

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

getSpecificationVersion

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

hashCode

public int hashCode()
Returns the hashCode of the name of this package.
Overrides:
hashCode in interface Object
Returns:
the hash code

isAnnotationPresent

public boolean isAnnotationPresent(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

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

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

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 interface Object
Returns:
the string representation of the package

Package.java -- information about a package Copyright (C) 2000, 2001, 2002, 2003, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.