Примечания

• Статья написана на основе курса от компании Oracle "Learning the Java language", раздела "Annotations".

• Статья подойдет тем, кто встречался с аннотациями на практике и хочет углубить или освежить теоретические знания.

Основы аннотаций

Определение

Аннотации - это форма метаданных. Они предоставляют информацию о программе, при том сами частью программы не являются.

Применение

• Информация для компилятора. Могут использоваться компилятором для обнаружения ошибок и подавления предупреждений.

• Обработка во время компиляции и развертывания. Программа может создавать код, XML-файлы и т.п. на основе аннотаций.

• Обработка во время выполнения. Некоторые аннотации могут использоваться во время выполнения программы.

Синтаксис

Начинаются с @, могут включать элементы, которым присваиваются значения:

@Author(
    name = "Benjamin Franklin"
    date = "3/27/2003"
)
class MyClass{...}

Если такой элемент один, его имя можно опустить:

@SupressWarnings("unchecked")
void MyMethod() {...}

Если таких элементов нет, можно опустить скобки. Можно использовать несколько аннотаций в одном объявлении:

@Author(name = "Jane Doe")
@EBook 
class MyClass { ... }

Аннотации могут быть повторяющимися.

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { ... }

Где в коде можно использовать аннотации

Аннотации применяются с объявлениями классов, полей и других элементов программы.

Аннотации, использующиеся с типами, называются аннотациями типов. Примеры таких аннотаций:

• Создание экземпляра класса:

new @Interned MyObject(); 

• Приведение к типу:

myString = (@NonNull String) str;

• Имплементация:

class UnmodifiableList<T>
    implements @Readonly List<@Readonly T> { ... }

• Объявление бросаемых исключений:

void monitorTemperature() throws
    @Critical TemperatureException { ... }

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

Синтаксис

Описание аннотации напоминает описание интерфейса. Оно начинается с @Interface, а его элементы похожи на методы, которые могут иметь дефолтные значения.

Пример

Допустим, в какой-то IT-компании тела всех классов начинаются с комментариев, содержащих важную информацию:

public class Generation3List extends Generation2List { 

    // Author: John Doe 
    // Date: 3/17/2002
    // Current revision: 6 
    // Last modified: 4/12/2004 
    // By: Jane Doe 
    // Reviewers: Alice, Bill, Cindy 
    // class code goes here
 }

Описание аннотации, которая заменит комментарии:

@interface ClassPreamble {
    String author();
    String date(); 
    int currentRevision() default 1; 
    String lastModified() default "N/A";
    String lastModifiedBy() default "N/A"; 
    // Можно использовать массив
    String[] reviewers(); 
 }

Использование созданной аннотации:

@ClassPreamble ( 
    author = "John Doe", 
    date = "3/17/2002", 
    currentRevision = 6, 
    lastModified = "4/12/2004", 
    lastModifiedBy = "Jane Doe", 
    reviewers = {"Alice", "Bob", "Cindy"} 
) 
public class Generation3List extends Generation2List {
...
...
} 

Замечание: для добавления аннотации в Javadocs нужно использовать @Documented:

import java.lang.annotation.*; 

@Documented 
@interface ClassPreamble { 
    // Описание элементов аннотации 
}

Предопределенные аннотации

В Java есть аннотации, описанные заранее. Часть из них предоставляют информацию для компилятора, часть применяется к другим аннотациям.

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

Располагаются в пакете java.lang.

@Deprecated

Помеченный этой аннотацией элемент устарел и больше не должен использоваться (это стоит отметить в Javadoc). При наличии такого элемента в программе компилятор сгенерирует предупреждение.

// Комментарий Javadoc:
/** 
* @deprecated 
* объяснение, почему метод устарел.
*/ 
@Deprecated 
static void deprecatedMethod() { }

@Override

Информирует компилятор о том, что аннотируемый элемент должен переопределять элемент родительского класса. При некорректном переопределении компилятор сгенерирует ошибку.

@Override
int overriddenMethod() { }

@SuppressWarnings

Подавляет генерируемые компилятором предупреждения.

Предупреждения делятся на непроверенные (unchecked) и устаревшие (deprecation). Первые возникают при использовании устаревшего кода, написанного до дженериков, вторые - при использовании кода, помеченного аннотацией @Deprecated.

Можно подавить как одну категорию, так и обе сразу:

@SuppressWarnings({"unchecked", "deprecation"})

@SafeVarargs

Применяется к методу или конструктору и утверждает, что код не выполняет потенциально небезопасных операций с параметрами varargs. При использовании аннотации подавляются unchecked предупреждения, связанные с varargs.

@SafeVarargs // На самом деле не безопасно!
static void m(List<String>... stringLists) { 
    Object[] array = stringLists; 
    List<Integer> tmpList = Arrays.asList(42);
    array[0] = tmpList; //Написано неверно, но скомпилируется без предупреждения
    String s = stringLists[0].get(0); //ClassCastException 
}

@FunctionalInterface

Используется при описании функционального интерфейса. Подчеркивает, что это именно функциональный интерфейс.

@FunctionalInterface
public interface Predicate<T> {

    boolean test(T t);

}

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

Располагаются в пакете java.lang.annotation.

@Retention

Указывает, сколько хранится отмеченная аннотация.

• RetentionPolicy.SOURCE. Отмеченная аннотация сохраняется только на уровне исходного кода и игнорируется компилятором.

• RetentionPolicy.CLASS. Сохраняется компилятором во время компиляции, но игнорируется JVM.

• RetentionPolicy.RUNTIME. Сохраняется JVM для использования во время выполнения программы.

@Documented

Указывает, что аннотация, должна быть задокументирована в Javadoc (по умолчанию аннотации не документируются).

@Target

Определяет права доступа аннотации (к каким элементам ее можно применять). В аннотации @Target указывается одно из следующих значений:

• ElementType.ANNOTATION_TYPE. Применяется к аннотации

• ElementType.CONSTRUCTOR. Применяется к конструктору.

• ElementType.FIELD. Применяется к полю или свойству.

• ElementType.LOCAL_VARIABLE. Применяется к локальной переменной.

• ElementType.METHOD. Применяется к методу.

• ElementType.PARAMETER. Применяется к параметру метода.

• ElementType.TYPE. Применяется к любому элементу класса.

@Inherited

Аннотация будет наследоваться дочерним классом (по умолчанию аннотации не наследуются). Применима только к описаниям классов.

@Repeatable

Указывает, что аннотация повторяющаяся.

Повторяющиеся аннотации

Определение

Аннотации, которые могут применяться к одному и тому же элементу более одного раза.

Пример

Допустим, вам надо написать аннотацию, запускающую метод в заданное время или по определенному расписанию. В примере созданная аннотация @Schedule будет запускать метод каждый последний день месяца и каждую пятницу в 23:00.

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23") 
public void doPeriodicCleanup() { ... }

Создание повторяющейся аннотации

Для обеспечения обратной совместимости повторяющиеся аннотации хранятся в контейнере аннотаций, который автоматически генерируется java компилятором. Для генерации нужны следующие описания:

1. Описание повторяющейся аннотации

Аннотация должна быть помечена @Repeatable, в скобках указан тип контейнера аннотаций.

import java.lang.annotation.Repeatable;

@Repeatable(Schedules.class) 
public @interface Schedule { 
    String dayOfMonth() default "first"; 
    String dayOfWeek() default "Mon"; 
    int hour() default 12; 
}

• Описание контейнера аннотаций

Контейнер должен содержать массив повторяющихся аннотаций.

public @interface Schedules { 
    Schedule[] value(); 
} 

Получение повторяющихся аннотаций

Reflection API предоставляет методы для получения аннотаций. При получении повторяющихся аннотаций поведение методов, которые возвращают одну аннотацию (например, AnnotatedElement.getAnnotation(Class<T>)) не меняется. Если нужно вернуть более одной, то необходимо сначала получить контейнер. Таким образом устаревший код продолжает работать. Также, для получения повторяющихся аннотаций можно использовать методы Java SE 8 ('AnnotatedElement.getAnnotationsByType(Class)').

Для получения информации о всех методах, обратитесь к документации класса AnnotatedElement.

Аннотации типов

Определение

Аннотации типов - аннотации, которые применяются вместе с типами. Везде, где вы видите тип, можно использовать эту аннотацию. Например, с оператором new, при приведении, при имплементации и при использовании throws.

Создание аннотации типов

Для создания аннотации типов в @Target указываются следующие значения, либо одно из них:

@Target ({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
public @interface Test {

}

TYPE_PARAMETER, означает, что аннотацию можно применять к переменным типа (например, MyClass<T>). TYPE_USE, разрешает применение с любыми типами.

Применение

Аннотации типов предназначены для улучшенного анализа программ и более строгой проверки типов. Например, @NonNull String str;. Java SE8 определяет аннотации типов, но не реализует. Вместо этого предлагается использовать сторонние фреймворки, реализующие их (Checker Framework).