Аннотация (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 :

@Edible
Food food = new Food();

public @interface Edible{
    //создание собственной аннотации
}

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

@Edible(true) // присваивание значения true для edible
Food 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.

Ссылки

• Introduction to Java 5.0 Annotations by Joy Christy
• Of Java Annotations by John Hunt
• An Introduction to Java Annotations by M. M. Islam Chisty
• Introduction to Java 6 Annotations at Sun Developer Network Site