Аннотации в Java, часть I

Это первая часть статьи, посвященной такому языковому механизму Java 5+ как аннотации. Она имеет вводный характер и рассчитана на Junior разработчиков или тех, кто только приступает к изучению языка.

Я занимаюсь онлайн обучением Java и опубликую часть учебных материалов в рамках переработки курса Java Core.
Мой метод обучения состоит в том, что я

1. строю усложняющуюся последовательность примеров
2. объясняю возможные варианты применения
3. объясняю логику двигавшую авторами (по мере возможности)
4. даю большое количество тестов (50-100) всесторонне проверяющее понимание и демонстрирующих различные комбинации
5. даю лабораторные для самостоятельной работы

Данная статье следует пунктам #1 (последовательность примеров) и #2(варианты применения).

Поехали!

Учебный пример: снабдить классы пользователя мета-информацией о «версии класса».

Итерация #1:
Просто ставим @ перед interface.

public @interface Version {}

Итерация #2:
У аннотаций могут быть атрибуты.

public @interface Version {
    public int version();
}

И заполнять их при использовании аннотации

@Version(version = 42)
public class MyClass {}

Аннотация выше полностью эквивалентна следующей (без public). В этом аннотации эквивалентны интерфейсам: отсутствие модификатора области видимости автоматически означает public (а не package private как у классов).

public @interface Version {
    int version();
}

С protected и private — не компилируется

public @interface Version {
    protected int version();
}
>> COMPILATION ERROR: Modifier 'protected' not allowed here

Далее я буду использовать вариант без модификатора public

Итерация #3:
Если объявить атрибут с именем value, то его можно опускать при использовании

public @interface Version {
    public int value();
}

@Version(42)
public class MyClass {}

Хотя можно и по старинке

@Version(value = 42)
public class MyClass {}

Итерация #4:
Для атрибута можно объявить значения по умолчанию

public @interface Version {
    int value();
    String author() default "UNKNOWN";
}

Теперь у нас два варианта использования. Так

@Version(42)
public class MyClass {}

Или вот так

@Version(value = 42, author = "Jim Smith")
public class MyClass {
}

Но не вот так (слушай, обидно, да)

@Version(42, author = "Jim Smith")
public class MyClass {}
>> COMPILATION ERROR: Annotation attribute must be of the form 'name=value'

Итерация #5:
Атрибуты могут иметь тип массива

public @interface Author {
    String[] value() default {};
}

@Author({"Anna", "Mike", "Sara"})
public class MyClass {}

Но только одномерного

public @interface Author2D {
    String[][] value() default {};
}
>> COMPILATION ERROR: Invalid type of annotation member

Итерация #6:
Возможен забавный трюк: аннотация — атрибут аннотации

public @interface Version {
    int value();
    String author() default "UNKNOWN";
}

public @interface History {
    Version[] value() default {};
}

Применяется вот так

@History({
        @Version(1),
        @Version(value = 2, author = "Jim Smith")
})
public class MyClass {}

У аннотаций много ограничений. Перечислим некоторые из них.

Ограничение: тип атрибута

1. Атрибуты могут иметь только следующие типы

• примитивы
• String
• Class или «any parameterized invocation of Class»
• enum
• annotation
• массив элементов любого из вышеперечисленных типов

Последний пункт надо понимать как то, что допустимы только одномерные массивы.

Ну что же, давайте действовать в рамках ограничений

Итерация #7:
В качестве типа атрибута нельзя использовать «обычные» классы Java (за исключением java.lang.String и java.lang.Class), скажем java.util.Date

import java.util.Date;

public @interface Version {
    Date date();
}
>> COMPILATION ERROR: Invalid type for annotation member

Но можно эмулировать записи/структуры на аннотациях

public @interface Date {
    int day();
    int month();
    int year();
}

public @interface Version {
    Date date();
}

@Date(year = 2001, month = 1, day = 1)
public class MyClass {}

Итерация #8:
Атрибутом аннотации может быть enum. Из приятного, его можно объявить в объявлении аннотации (как и в объявлении интерфейса тут может быть объявление enum, class, interface, annotation)

public @interface Colored {
    public enum Color {RED, GREEN, BLUE}
    Color value();
}

import static net.golovach.Colored.Color.RED;

@Colored(RED)
public class MyClass {}

Итерация #9:
Атрибутом аннотации может быть классовый литерал.
Аннотация версии включает ссылку на предыдущую версию класса.

public @interface Version {
    int value();
    Class<?> previous() default Void.class;
}

Первая версия класса

@Version(1)
public class ClassVer1 {}

Вторая версия со ссылкой на первую

@Version(value = 2, previous = ClassVer1.class)
public class ClassVer2 {}

// Да, я знаю, что нормальные люди не включают версию класса в имя класса. Но знаете как нудно придумывать примеры согласованные с реальной практикой?

Итерация #10:
Менее тривиальный пример с классовым литералом, где я не удержался и добавил generic-ов.
Интерфейс «сериализатора» — того, кто может записать экземпляр T в байтовый поток вывода

import java.io.IOException;
import java.io.OutputStream;

public interface Serializer<T> {
    void toStream(T obj, OutputStream out) throws IOException;
}

Конкретный «сериализатор» для класса MyClass

import java.io.IOException;
import java.io.OutputStream;

public class MySerializer implements Serializer<MyClass> {
    @Override
    public void toStream(MyClass obj, OutputStream out) throws IOException {
        throw new UnsupportedOperationException();
    }
}

Аннотация, при помощи которой мы «приклеиваем сериализатор» к конкретному классу

public @interface SerializedBy {
    Class<? extends Serializer> value();
}

Ну и сам класс MyClass отмеченный, как сериализуемый «своим сериализатором» MySerializer

@SerializedBy(MySerializer.class)
public class MyClass {}

Итерация #11:
Сложный пример

public enum JobTitle {
    JUNIOR, MIDDLE, SENIOR, LEAD,
    UNKNOWN
}

public @interface Author {
    String value();
    JobTitle title() default JobTitle.UNKNOWN;
}

public @interface Date {
    int day();
    int month();
    int year();
}

public @interface Version {
    int version();
    Date date();
    Author[] authors() default {};
    Class<?> previous() default Void.class;
}

Ну и наконец использование аннотации

import static net.golovach.JobTitle.*;

@History({
        @Version(
                version = 1,
                date = @Date(year = 2001, month = 1, day = 1)),
        @Version(
                version = 2,
                date = @Date(year = 2002, month = 2, day = 2),
                authors = {@_8_Author(value = "Jim Smith", title = JUNIOR)},
                previous = MyClassVer1.class),
        @Version(
                version = 3,
                date = @Date(year = 2003, month = 3, day = 3),
                authors = {
                        @Author(value = "Jim Smith", title = MIDDLE),
                        @Author(value = "Anna Lea")},
                previous = MyClassVer2.class)
})
public class MyClassVer3 {}

Ограничение: значения атрибутов — константы времени компиляции/загрузки JVM

Должна быть возможность вычислить значения атрибутов аннотаций в момент компиляции или загрузки класса в JVM.

public @interface SomeAnnotation {
    int count();
    String name();
}

Пример

@SomeAnnotation(
        count = 1 + 2,
        name = MyClass.STR + "Hello"
)
public class MyClass {
    public static final String STR = "ABC";
}

Еще пример

@SomeAnnotation(
        count = (int) Math.PI,
        name = "" + Math.PI
)
public class MyClass {}

А вот вызовы методов — это уже runtime, это уже запрещено

@SomeAnnotation(
        count = (int) Math.sin(1),
        name = "Hello!".toUpperCase()
)
public class MyClass {}
>> COMPILATION ERROR: Attribute value must be constant

Заключение

Это первая часть статьи про аннотации в Java. Во второй части мы рассмотрим следующие темы:

• Аннотации, модифицирующие поведение других аннотаций: @ Target, @ Retention, @ Documented, @ Inherited
• Аннотации, модифицирующие поведение компилятора и JVM: @ Deprecated, @ Override, @ SafeVarargs, @ SuppressWarnings
• Чтение аннотаций с помощью Reflection API

Автор: IvanGolovach

Источник