What's the point of package annotations?

Question

I understand the purpose of class annotations, thanks to How and where are Annotations used in Java?. What is the purpose of package annotations, as described in this blog p

Answer 1

JAXB for example allows most annotations that are normally used on a type to be equally well applied to a package. The meaning in that case would be to specify the default for all classes in that package.

For example, if you want all properties of all classes in a package that are exposed via getter/setters to be mapped in XML you could specify @XmlAccessorType(XMLAccessType.PROPERTY) on each class or simply specify it on the package.

Answer 2

I suppose @Deprecated would make sense. And maybe something like @Generated if the whole package was generated by some tool from non-Java source. Or @Internal if this package is not part of a public API.

Maybe OSGi tools (where you need to declare the versions of your packages, and the packages you depend on) could make use of this, too.

Has anyone seen those in the wild?

Answer 3

This is not the real purpose, but I'm using them as a workaround to avoid recompilation of the package-info.java files.

The problem is that javac (and the Ant task <javac>) creates no class file for the package-info.java if there is only documentation (the reason for their existence) and the package bla; statement, and that the ant task recompiles every file for which there is no (or an older) corresponding .class file.

Adding a dummy annotation there (like SuppressWarnings) had the effect that a package-info.class is produced and thus the file is not recompiled until changed again.

(Ant 1.8.0 solved this by creating an empty package-info.class, even if there was no annotation, but I'm using an older ant here.)

Answer 4

Two reasons that I can think of:

• Annotating special packages to let some aspects (for example using AspectJ) to weave the classes in them for specific functionality.
• Annotating some packages that are to be read by some tools, for example for source, meta-data or other kinds of resource generation.

Answer 5

Test metadata -- that is metadata around test packages (unit tests or otherwise). You can ascribe various pieces of test metadata that are appropriate at the package level, such as: features, owners, versions, bugs/issues, etc. These could be refined at the class or method level, but having package-level definitions or defaults could be handy for brevity. I've utilized a variant of this approach (before the benefit of annotations).

A similar argument could be made for generalized code metadata around the same sorts of things: features, ownership, defects, historical information, etc.

Answer 6

1. bnd tool (and maven-bundle-plugin) makes use of package annotations. Putting @Version and @Export annotation in package-info.java allows it to generate OSGi metadata.
2. javadoc uses package annotations.
3. JAXB uses package-level annotations, for example, to specify mapping of a Java type to XML Schema type package-wide. Package annotations are also used in JBoss's xml binding.
4. Struts 2 Convention plugin uses an annotation to specify a default interceptor for all actions in a package.
5. There are some package-level Hibernate Annotations. An example of those annotations' usage can be found here.