Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Start a free Courses trial
to watch this video
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.
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!
Related Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign upRelated Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign up
You need to sign up for Treehouse in order to download course files.
Sign upYou need to sign up for Treehouse in order to set up Workspace
Sign up