So how do you actually annotate a package? There is no required way to deal with this "single annotated
package statement" rule. The suggested approach is to create a file called package-info.java within the
package directory, and to put in that file nothing but a package statement with any annotations for the package
(plus any useful comments, of course). For example, a package-info.java file for the attr package
might look like this:
@PackageSpec(name = "Attr Project", version = "1.0")
@DevelopmentSite("attr.project.org")
@DevelopmentModel("open-source")
package attr;
where PackageSpec, DevelopmentSite, and DevelopmentModel are made up annotation
typeswith a runtime retention policy, of course. The package-info.java file should be compiled along
with the rest of the package source files.
The package-info.java file is recommended as the single place to put all package-related information.
To that end, you can place a documentation comment at the start of the file, and that will be the package
documentation for that package. Package documentation is covered in more detail in "Package and Overview
Documentation" on page 496.
The java.lang.Package class implements AnnotatedElement, so you can ask about any applied
annotations using the methods discussed in "Annotation Queries" on page 414.
18.6. Package Objects and Specifications
Packages typically implement a specification, and they are also typically from one organization. A Package
object, unlike the other reflection types (see Chapter 16), is not used to create or manipulate packages, but acts
only as a repository for information about the specification implemented by a package (its title, vendor, and
version number) and for information about the implementation itself (its title, vendor, and version number).
Although a package typically comes from a single organization, the specification for that package (such as a
statistical analysis library) may have been defined by someone else. Programs using a package may need to be
able to determine the version of the specification implemented by the package so that they use only
functionality defined in that version. Similarly, programs may need to know which version of the
implementation is provided, primarily to deal with bugs that may exist in different versions. The main
methods of Package allow access to this information:
public StringgetName()Returns the name of this package.public StringgetSpecificationTitle()Returns the title of the specification this package implements, or null if the
title is unknown.public StringgetSpecificationVersion()Returns a string describing the version of the specification that this package
implements, or null if the version is unknown.public StringgetSpecificationVendor()