39

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 post and §7.4.1 of the Java Language Specification?

Why would you want to associate metadata with a package? What kinds of things could you do?

Community
  • 1
  • 1
Gili
  • 86,244
  • 97
  • 390
  • 689

6 Answers6

42
  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.
C. Ross
  • 31,137
  • 42
  • 147
  • 238
Marat Salikhov
  • 6,367
  • 4
  • 32
  • 35
7

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?

Thilo
  • 257,207
  • 101
  • 511
  • 656
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.
Amir Moghimi
  • 1,391
  • 1
  • 11
  • 19
  • Are you saying that annotating a package is equivalent to annotating all classes within that package in one swoop? – Gili Jan 20 '10 at 14:41
  • No, I mean you can use it to indicate that the whole classes in that package should be weaved. – Amir Moghimi Jan 20 '10 at 15:05
  • How is that different from what I wrote? – Gili Feb 04 '10 at 16:52
  • 4
    @Gili: I understood your comment to mean that the classes would appear to actually have that annotation *themselves*, at the language level. And I understood Amir's comment to mean that an annotation processor could see the annotation on the package (not on the classes per se), and then **decide** based on that to perform some action on every class within that package. Very different in terms of the result when one calls `Class.getAnnotations()`. – Andrzej Doyle Mar 17 '11 at 12:20
  • @Andrzej: You got my comment right. Your comment further explains mine. – Amir Moghimi Jun 24 '11 at 05:56
2

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.

Joachim Sauer
  • 302,674
  • 57
  • 556
  • 614
1

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.)

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
0

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.

Will
  • 6,601
  • 3
  • 31
  • 42