Аннотации в JAVA: обзор синтаксиса и создание собственных
Статья ориентирована больше на новичков, или тех, кто еще не работал с данным механизмом в языке. Я постараюсь рассказать, что это такое, зачем они нужны, и как можно самому создавать удобные для себя аннотации.
Аннотации представляют из себя дескрипторы, включаемые в текст программы, и используются для хранения метаданных программного кода, необходимых на разных этапах жизненного цикла программы.
Информация, хранимая в аннотациях, может использоваться соответствующими обработчиками для создания необходимых вспомогательных файлов или для маркировки классов, полей и т.д.
Синтаксис
Аннотация задается описанием соответствующего интерфейса.
Например так:
import java.lang.annotation.*; @Target(value=ElementType.FIELD) @Retention(value= RetentionPolicy.RUNTIME) public @interface Name
Как видно из примера выше, аннотация определяется описанием с ключевым словом interface и может включать в себя несколько полей, которые можно задать как обязательными, так и не обязательными. В последнем случае подставляется default значение поля.
Также из примера видно, что саму аннотацию можно пометить несколькими аннотациями.
Разберемся для начала, чем можно пометить собственную аннотацию, и зачем.
Аннотация @Retention позволяет указать жизненный цикл аннотации: будет она присутствовать только в исходном коде, в скомпилированном файле, или она будет также видна и в процессе выполнения. Выбор нужного типа зависит от того, как вы хотите использовать аннотацию, например, генерировать что-то побочное из исходных кодов, или в процессе выполнения стучаться к классу через reflection.
Аннотация @Target указывает, что именно мы можем пометить этой аннотацией, это может быть поле, метод, тип и т.д.
Аннотация @Documentedуказывает, что помеченная таким образом аннотация должна быть добавлена в javadoc поля/метода и т.д.
Например, класс, помеченный аннотацией без @Documented, будет выглядеть так:
public class TestClass extends java.lang.ObjectА если в описание аннотации добавить @Documented, получим:
@ControlledObject(name="name") public class TestClass extends java.lang.ObjectАннотация @Inherited помечает аннотацию, которая будет унаследована потомком класса, отмеченного такой аннотацией.
Сделаем для примера пару аннотаций и пометим ими класс.
@Inherited @interface PublicAnnotate < >@interface PrivateAnnotate < >@PublicAnnotate @PrivateAnnotate class ParentClass < >class ChildClass extends ParentClass
Класс ChildClass унаследует от родительского класса только аннотацию PublicAnnotate.
Пример своей аннотации.
Попробуем теперь написать рабочий пример с использованием аннотаций.
Представим себе, что у нас есть какой-то самодельный проект, который на вход получает класс, специально заанотированный, чтобы проект мог управлять жизненным циклом объектов этого класса, и пусть там будут аннотации StartObject, StopObject для описания методов класса, и ControlledObject для описания самого класса. Последней аннотации дадим еще поле name, путь там хранится якобы имя для поиска.
Аннотации будут выглядеть так:
@Target(value=ElementType.METHOD) @Retention(value= RetentionPolicy.RUNTIME) public @interface StartObject < >@Target(value=ElementType.METHOD) @Retention(value= RetentionPolicy.RUNTIME) public @interface StopObject < >@Target(value=ElementType.TYPE) @Retention(value= RetentionPolicy.RUNTIME) public @interface ControlledObject
Напишем модуль, проверяющий подходит ли класс для загрузки в наш гипотетический проект или нет.
Сперва определим сам проверяемый класс.
@ControlledObject(name="biscuits") public class Cookies < @StartObject public void createCookie()< //бизнес логика >@StopObject public void stopCookie() < //бизнес логика >>Для того, чтобы работать с классом, сначала необходимо загрузить класс в контекст приложения. Используем:
Class cl = Class.forName(«org.annotate.test.classes.Cookies»);
Далее, через механизм reflection мы получаем доступ к полям и аннотациям класса.
Проверим наличие аннотированных методов в классе и аннотации на самом классе:
if(!cl.isAnnotationPresent(ControlledObject.class)) < System.err.println("no annotation"); >else < System.out.println("class annotated ; name - " + cl.getAnnotation(ControlledObject.class)); >boolean hasStart=false; boolean hasStop=false; Method[] method = cl.getMethods(); for(Method md: method) < if(md.isAnnotationPresent(StartObject.class)) if(md.isAnnotationPresent(StopObject.class)) if(hasStart && hasStop) > System.out.println("Start annotaton - " + hasStart + "; Stop annotation - " + hasStop ); Запустив, на выходе мы получим:
Start annotaton — true; Stop annotation — true.
Если попробовать убрать одну из аннотаций, то вывод сообщит о несоответствии требованиям.
Итог
Надеюсь, мне удалось показать, что аннотации предоставляют широкие возможности для работы с кодом программ, и имеет смысл не только пользоваться стандартными аннотациями языка, но и облегчать себе жизнь, создавая аннотации под свои нужды.
Подробнее ознакомиться с данным механизмом могу порекомендовать в книге «Java 2. Библиотека профессионала, том 2. Тонкости программирования» Кей С. Хорстманна, Гари Корнелла, или на сайте oracle, где так же есть подробные туториалы.
Annotations Basics
In its simplest form, an annotation looks like the following:
The at sign character ( @ ) indicates to the compiler that what follows is an annotation. In the following example, the annotation’s name is Override :
@Override void mySuperMethod()
The annotation can include elements, which can be named or unnamed, and there are values for those elements:
@Author( name = «Benjamin Franklin», date = «3/27/2003» ) class MyClass
@SuppressWarnings(value = «unchecked») void myMethod()
If there is just one element named value , then the name can be omitted, as in:
@SuppressWarnings(«unchecked») void myMethod()
If the annotation has no elements, then the parentheses can be omitted, as shown in the previous @Override example.
It is also possible to use multiple annotations on the same declaration:
@Author(name = «Jane Doe») @EBook class MyClass
If the annotations have the same type, then this is called a repeating annotation:
@Author(name = «Jane Doe») @Author(name = «John Smith») class MyClass
Repeating annotations are supported as of the Java SE 8 release. For more information, see Repeating Annotations.
The annotation type can be one of the types that are defined in the java.lang or java.lang.annotation packages of the Java SE API. In the previous examples, Override and SuppressWarnings are predefined Java annotations. It is also possible to define your own annotation type. The Author and Ebook annotations in the previous example are custom annotation types.
Where Annotations Can Be Used
Annotations can be applied to declarations: declarations of classes, fields, methods, and other program elements. When used on a declaration, each annotation often appears, by convention, on its own line.
As of the Java SE 8 release, annotations can also be applied to the use of types. Here are some examples:
- Class instance creation expression:
myString = (@NonNull String) str;
class UnmodifiableList implements @Readonly List
void monitorTemperature() throws @Critical TemperatureException
This form of annotation is called a type annotation. For more information, see Type Annotations and Pluggable Type Systems.