Одночленные аннотации

Одночленная аннотация (single-member annotation) — это еще один специальный тип аннотации, содержащий единственный метод-член. Она применяется так же, как и обычная аннотация, за исключением того, что для этого типа аннотации допускается краткая условная форма задания значения для метода-члена. Если есть только один метод-член, Вы можете просто указать значение для этого метода-члена, когда создается аннотация; при этом не нужно указывать имя метода-члена. Но для того чтобы воспользоваться краткой формой, следует для метода-члена использовать имя value.

Листинг 7.6. Создание и применение одночленной аннотации

import java.lang.annotation.*;

import java.lang.reflect.*;

// A single-member annotation.

@Retention(RetentionPolicy.RUNTIME)

@interface MySingle {

int value(); // this variable name must be value

}

class Single {

// Annotate a method using a marker.

@MySingle(100)

public static void myMeth() {

Single ob = new Single();

try {

Method m = ob.getClass().getMethod("myMeth");

MySingle anno = m.getAnnotation(MySingle.class);

System.out.println(anno.value()); // displays 100

} catch (NoSuchMethodException exc) {

System.out.println("Method Not Found.");

}

}

public static void main(String args[]) {

myMeth();

}

}

Как и ожидалось, программа выводит на экран значение 100. В листинге 7.6 аннотация типа @MySingle используется для создания примечания к методу myMeth (), как показано в следующей строке:

@MySingle(100)

Обратите внимание на то, что не указано выражение value =.

Вы можете применять синтаксическую запись одночленной аннотации, когда создаете аннотацию, у которой есть и другие методы-члены, но для них должны быть заданы значения по умолчанию. В приведенном далее фрагменте добавлен метод-член xyz со значением по умолчанию, равным 0.

@interface SomeAnno {

int valued ;

int xyz() default 0;

}

Если Вы хотите использовать значение по умолчанию для метода xyz, можно создать аннотацию типа @SomeAnno, как показано в следующей строке, применяя синтаксическую запись для одночленной аннотации с указанием значения для метода value:

@SomeAnno (88)

В этом случае в метод xyz передается нулевое значение по умолчанию, а метод value получает значение 88. Конечно, передача в метод xyz значения, отличного от значения по умолчанию, потребует явного задания имен обоих методов-членов, как показано в следующей строке:

@SomeAnno (value = 88, xyz = 99)

Помните, у одночленной аннотации имя метода-члена должно быть value.

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

В языке Java определено семь типов встроенных аннотаций, четыре типа — @Retention, @Documented, @Target и @Inherited — импортируются из пакета java.lang.annotation. Оставшиеся три — @Ovveride, @Deprecated и @Suppresswarnings — из пакета java.lang. Далее описаны все встроенные типы.

@Retention

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

@Documented

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

@Target

Аннотация типа @Target задает типы объявлений, которые могут снабжаться аннотациями. Она разработана для применения в качестве аннотации к другой аннотации. Тип @Target принимает один аргумент, который должен быть константой перечислимого типа ElementType. Этот аргумент задает типы объявлений, которые могут снабжаться аннотациями. В табл. 7.2 перечислены константы и соответствующие им типы объявлений.

Таблица 7.2. Перечень констант ElementType и типы объектов,

сопровождаемых аннотациями

Константа для типа @Target	Объект, снабженный аннотацией
ANNOTATION_TYPE	Другая аннотация
CONSTRUCTOR	Конструктор
FIELD	Поле
LOCAL_VARIABLE	Локальная переменная
METHOD	Метод
PACKAGE	Пакет
PARAMETER	Параметр
TYPE	Класс, интерфейс или перечислимый тип

Вы можете задать одну или несколько констант из табл. 7.2 в аннотации типа @Target. При указании нескольких значений их следует заключить фигурные скобки. Например, если необходимо создать аннотации к полям и локальным переменным, можно использовать аннотацию типа @Target, описанную в следующей строке:

@Target( { ElementType.FIELD, ElementType.LOCAL_VARIABLE } )

@Inherited

Тип @inherited предназначен для аннотации-маркера, которая может применяться только для объявления другой аннотации. Более того, аннотация этого типа влияет только на аннотации к объявлениям классов. Тип @Inherited вызывает наследование производным классом аннотации суперкласса. Следовательно, когда определенная аннотация запрашивается в производном классе и не обнаруживается в нем, ее поиск продолжается в суперклассе. Если в суперклассе есть эта аннотация, и она снабжена аннотацией-маркером типа @Inherited, аннотация извлекается.

@Ovveride

Аннотация типа @Ovveride — это аннотация-маркер, которая может применяться только для методов. Метод, снабженный аннотацией типа @Ovveride, должен переопределять метод суперкласса. Если этого не происходит, возникает ошибка на этапе компиляции. Аннотация этого типа используется для подтверждения того, что метод суперкласса действительно переопределен (overridden), а не просто перегружен (overloaded).

@Deprecated

Аннотация-маркер типа @Deprecated указывает, что объявление является устаревшим или вышедшим из употребления и было заменено новым вариантом.

@Suppress Warnings

Тип @SuppressWarnings указывает, что одно или несколько предупреждений компилятора должны быть подавлены. Эти предупреждения задаются с помощью имен в строковой форме. Данным типом аннотации можно снабжать объявления любого типа.