Starting the Annotation - Declaration and Retention4:15 with Chris Ramacciotti
Setting up the annotation is quite simple. In this video we'll get started by getting a look at the overall structure of the annotation, as well as specifying its retention. The retention is essentially how long it's kept around, from writing our source code to running our application.
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
There's More to the
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
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!
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
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!
You need to sign up for Treehouse in order to download course files.Sign up