Starting the Annotation - Declaration and Retention

Meta-Annotation: @Documented

There is one more annotation worth mentioning when declaring your custom annotation, and that is the @Documented annotation. This annotation can be applied to your custom annotations to instruct any documentation-generators (such as Javadoc) to include your annotation in the generated documentation. Though it doesn't affect the functionality of your annotation, it is nice to be able to control whether or not it will appear in your generated API docs, using any number of standard tools.

This annotation can only be applied at the top, declaration-level of an annotation, as the @Documented annotation is declared with @Target(ElementType.ANNOTATION_TYPE).

There's More to the RetentionPolicy Story

As you'll see in the coming videos, we will use reflection to analyze the presence of our @Doc annotation on classes and methods. In order to use reflection during this analysis, the annotation must be declared with RetentionPolicy.RUNTIME.

However, there is actually a way for to use RetentionPolicy.SOURCE and still have access to annotations for processing, using a method other than reflection. If you want to check out that approach, I’ve created a sample project for you. Let's consider the following scenario.

Sometimes developers find themselves writing a bunch of standard code. For example, a class containing a bunch of fields, each of which has getters & setters. The code for this follows a simple set of rules based on the field names and types. Any code that follows a set of reasonably standard rules and has consistent structure is commonly called “boilerplate code”.

In order to leverage SOURCE-level annotations, you must write what's called an annotation processor, typically by extending javax.annotation.processing.AbstractProcessor, providing an implementation of the process method. To run the processor, you'll use the javac console command and include the -processor option.

The project I’ve provided allows you to create a simple class containing a list of annotated fields. The included annotation processor reads the annotations and generates a full Java class, including all fields, getters and setters. In this example, the final Java class contains 40 lines of code, but it takes only 18 lines of annotated code to generate it. That’s a savings of 22 lines of code. Now imagine you have 20 classes like this to generate. You just saved yourself 440 lines of code. Go Java!

Download the sample java-annotations-processor

To use this sample, download and extract the ZIP file. Then in a console, change directories into the java-annotations-processor directory, and run the following commands:

Compile all Java files in the boilerplate directory

javac -d out -cp src src/com/teamtreehouse/boilerplate/**

Run the annotation processor on the PersonStub.java file

javac -cp out -processor com.teamtreehouse.boilerplate.BoilerplateGenerator src/com/teamtreehouse/sample/PersonStub.java

Result

The result of the second command will be a Person.java file that contains the full Person class. Compare this generated code with the original PersonStub.java code, and you’ll see the difference.

In general, one of the most common uses of source-level annotations - that is, using RetentionPolicy.SOURCE - is to generate other code files. This is certainly not the only use, but it sure is a powerful one!