Аннотация (Java)

Java-аннотация — в языке Java специальная форма синтаксических метаданных, которая может быть добавлена в исходный код.

Аннотации используются для анализа кода, компиляции или выполнения.Аннотируемы пакеты, классы, методы, переменные и параметры.

Выглядит как @ИмяАннотации, предваряющее определение переменной, параметра, метода, класса, пакета.

Применение

Аннотация выполняет следующие функции:

даёт необходимую информацию для компилятора / интерпретатора;
даёт информацию различным инструментам для генерации другого кода, конфигураций и т. д.;
может использоваться во время выполнения для получения данных через отражение (reflection);

Встроенные аннотации

Аннотации, применяемые к исходному коду:

@Override — аннотация-маркер, которая может применяться только к методам. Метод, аннотированный как @Override, должен переопределять метод супер класса. @Override — проверяет, переопределён ли метод. Вызывает ошибку компиляции / интерпретации, если метод не найден в родительском классе или интерфейсе;

@Deprecated — отмечает, что метод устарел и не рекомендуется к использованию. Предполагается, что по каким-то причинам этот метод пока оставлен, но будет удалён в будущих версиях. Вызывает предупреждение компиляции, если метод используется;
@SuppressWarnings — указывает компилятору подавить предупреждения компиляции, определённые в параметрах аннотации;
@SafeVarargs — указывает, что никакие небезопасные действия, связанные с параметром переменного количества аргументов, недопустимы. Применяется только к методам и конструкторам с переменным количеством аргументов, которые объявлены как static или final.

Аннотации, применяемые к другим аннотациям:

@Retention — определяет, как отмеченная аннотация может храниться — в коде, в скомпилированном классе или во время работы кода. Аннотация @Retention позволяет указать жизненный цикл аннотации: будет она присутствовать только в исходном коде, в скомпилированном файле, или она будет также видна и в процессе выполнения. Выбор нужного типа зависит от того, как вы хотите использовать аннотацию, например, генерировать что-то побочное из исходных кодов, или в процессе выполнения стучаться к классу через reflection.
@Documented — отмечает аннотацию для включения в документацию. Аннотация @Documented указывает, что помеченная таким образом аннотация должна быть добавлена в javadoc поля/метода и так далее. Например, класс, помеченный аннотацией без @Documented, будет выглядеть так:
```
public class TestClass extends java.lang.Object
```

@Target — отмечает аннотацию как ограничивающую, какие элементы аннотации могут быть к ней применены. Аннотация @Target указывает, что именно мы можем пометить этой аннотацией, это может быть поле, метод, тип и т. д.
@Inherited — отмечает, что аннотация может быть расширена подклассами аннотируемого класса. Аннотация @Inherited помечает аннотацию, которая будет унаследована потомком класса, отмеченного такой аннотацией.

Пример

public class Animal {    public void speak() {    }    }public class Cat extends Animal {    @Override // Аннотация, говорящая о том, что этот метод переопределяет одноимённый метод родительского класса    public void speak() {        System.out.println("Meow.");     }    @Deprecated // Аннотация, говорящая о том, что этот метод устарел и будет удалён в ближайшее время    public boolean soundsGood() {        return true;    }}

Создание аннотаций

Объявление аннотации похоже на объявление интерфейсов с использованием знака @ перед ключевым словом interface :

@EdibleFood food = new Food();public @interface Edible{    //создание собственной аннотации}

Пользовательские аннотации могут включать в себя различные значения, которые описываются как методы аннотации. Каждое объявление метода определяет элемент аннотации. Объявление метода не должно включать в себя каких-либо аргументов или инструкции throws. Возвращаемый тип обязан быть одним из: примитивный тип, строка, класс, перечисляемый тип, а также массив, содержащий перечисленный ранее тип данных. Методы могут иметь значения по умолчанию.

@Edible(true) // присваивание значения true для edibleFood food = new Food();public @interface Edible{    boolean edible() default false; // по умолчанию edible будет false}public @interface Author{    String first_name();    String last_name();}@Author(first_name="James", last_name="Gosling")Book book = new Book();// Аннотация также может быть аннотирована для определения области её применения@Target({ElementType.METHOD})public @interface SomeAnnotation{}public class SomeClass{    @SomeAnnotation    private void doSomething(){}}

История

Первоначально в платформе Java имелся механизм, предваряющий механизм аннотаций — например, модификатор transient или тег @Deprecated.В сентябре 2002 года сообществу Java представлен документ JSR-175, описывающий основные тезисы по аннотациям. Он был утверждён в 2004 году.Аннотации стали доступны в самом языке начиная с версии 1.5 JDK и описаны в JSR-269.В версии 1.6 аннотации были интегрированы в компилятор javac.

Search