CODEWITHSUNDEEP
javaannotations
Gili
Gili

Reputation: 90180

What's the point of package annotations?

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?

Upvotes: 41

Views: 16046

Answers (6)

Marat Salikhov
Marat Salikhov

Reputation: 6627

  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.

Upvotes: 45

Will
Will

Reputation: 7057

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.

Upvotes: 0

Joachim Sauer
Joachim Sauer

Reputation: 308259

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.

Upvotes: 2

Paŭlo Ebermann
Paŭlo Ebermann

Reputation: 74800

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

Upvotes: 1

Amir Moghimi
Amir Moghimi

Reputation: 1429

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.

Upvotes: 4

Thilo
Thilo

Reputation: 262834

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?

Upvotes: 7

Related Questions