Задание правил сохранения

Прежде чем продолжить изучение метаданных, следует обсудить правше сохранения аннотаций (annotation retention policies). Правила сохранения определяют, в какой момент аннотации уничтожаются. В языке Java описаны три таких правила — source, class и runtime, включенные в перечислимый тип Java.lang.annotation.RetentionPolicy.

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

Аннотация, заданная с правилом сохранения class, помещается в файл .class в процессе компиляции. Но она не доступна в JVM (виртуальная машина Java) во время выполнения.

Аннотация, заданная с правилом сохранения runtime, помещается в факт .class в процессе компиляции и доступна в JVM во время выполнения. Следовательно, правило runtime предлагает максимальную продолжительность существования аннотации.

Правило сохранения для аннотации задается с помощью одной из встроенных аннотаций @Retention. Ее синтаксическая запись приведена в следующей строке:

@Retention {retention-policy)

В этой записи retention-policy задается одной из описанных ранее констант перечислимого типа. Если для аннотации не задано правило сохранения, по умолчанию задается правило class.

В приведенном далее фрагменте аннотация типа MуАnnо использует аннотацию @Retention для задания правила сохранения runtime. Следовательно, аннотация типа МуАnnо будет доступна в JVM во время выполнения программы:

@Retention(RetentionPolicy.RUNTIME)

@interface МуАnnо {

String str() ;

int val();

}

Получение аннотаций во время выполнения программы с помощью рефлексии

Несмотря на то, что аннотации созданы для других программных средств разработки и распространения или установки, их может запросить любая Java-программа во время выполнения с помощью средств рефлексии. Многие читатели, вероятно, знают, рефлексия — это функциональная возможность, позволяющая получать информацию о классе во время выполнения. Интерфейс рефлексии (Reflection API) содержится в пакете java.lang.reflect. Существует ряд способов применения рефлексии, но мы не будем обсуждать их все в этой книге. Рассмотрим несколько примеров применения этого программного средства для получения информации об аннотации.

Первый вариант использования рефлексии — получение объекта типа class, представляющего класс, аннотации которого Вы хотите получить. Существуют разные способы получения объекта типа class. Простейший — вызов метода getClass(), который определен в классе Object. В следующей строке приведен общий вид такого вызова:

final Class<? Extends Object>getClass()

Метод возвращает объект типа Class, который представляет вызывающий объект. Учтите, что тип class теперь, настраиваемый.

После того, как Вы получили объект типа Class, можно использовать его методы для извлечения информации об отдельных элементах, объявленных в классе, включая аннотации. Если Вы хотите получить аннотации, связанные с конкретным элементом, определенным в пределах класса, то сначала необходимо извлечь объект, представляющий этот элемент. Например, тип класс предоставляет (среди прочих) методы: getMethod(), getField() и getConstructor(), получающие сведения о методе, поле и конструкторе соответственно. Эти методы возвращают объекты типа Method, Field и Constructor.

Для того чтобы лучше понять процесс, рассмотрим пример, в котором извлекаются аннотации, связанные с методом. Для этого Вы сначала получаете объект типа Class, представляющий класс, а затем вызываете метод get-Method о для этого объекта типа Class, задавая имя интересующего Вас метода. Синтаксическая запись вызова метода getMethod() приведена в следующей строке: Method getMethod(String methName, Class ... paramTypes)

Имя метода передается в параметре methName. Если у метода есть аргументы, то в параметре paramTypes следует указать объекты типа class, представляющие их типы. Обратите внимание на то, что paramTypes — параметр переменной длины (varargs parameter). Это означает, что можно задать столько параметров, сколько нужно, включая их отсутствие. Метод getMethod() возвращает объект типа Method, который представляет метод. Если метод не найден, генерируется исключение NoSuchMethodException.

Из объекта типа Class, Method, Field, Constructor или Package Вы можете получить конкретную аннотацию, связанную с объектом, с помощью вызова метода getAnnotation(), синтаксическая запись которого приведена в следующей строке:

<Т extends Annotation> T getAnnotation(class<T>annoType)

Параметр аппоType — это объект типа Class, который представляет интересующую вас аннотацию. Он возвращает ссылку на аннотацию. Используя ее, Вы можете получить значения, связанные с методами-членами аннотации.

В листинге 7.1 собраны все приведенные ранее фрагменты кода и использована рефлексия для отображения аннотации, связанной с методом.

Листинг 7.1. Применение рефлексии для отображения аннотации, связанной с методом

import java.lang.annotation.*;

import java.lang.reflect.*;

// An annotation type declaration.

@Retention(RetentionPolicy.RUNTIME)

@interface MyAnno {

String str();

int val();

}

class Meta {

// Annotate a method.

@MyAnno(str = "Annotation Example", val = 100)

public static void myMeth() {

Meta ob = new Meta();

// Obtain the annotation for this method

// and display the values of the members.

try {

// First, get a Class Object that represents

// this class.

Class c = ob.getClass();

// Now, get a Method Object that represents

// this method.

Method m = c.getMethod("myMeth");

// Next, get the annotation for this class.

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

// Finally, display the values.

System.out.println(anno.str() + " " + anno.val());

} catch (NoSuchMethodException exc) {

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

}

}

public static void main(String args[]) {

myMeth();

}

}

Далее приведен вывод результатов работы программы из листинга 7.1:

Annotation Example 100

В программе используется рефлексия для получения и отображения значений методов str и val аннотации типа MyAnno, связанной с методом myMeth() в классе Meta.

Листинг 7.2 Применение рефлексии для отображения аннотации, связанной с методом, имеющим аргументы

import java.lang.annotation.*;

import java.lang.reflect.*;

@Retention(RetentionPolicy.RUNTIME)

@interface MyAnno {

String str();

int val();

}

class Meta {

// myMeth now has two arguments.

@MyAnno(str = "Two Parameters", val = 19)

public static void myMeth(String str, int i)

{

Meta ob = new Meta();

try {

Class c = ob.getClass();

// Here, the parameter types are specified.

Method m = c.getMethod("myMeth", String.class, int.class);

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

System.out.println(anno.str() + " " + anno.val());

} catch (NoSuchMethodException exc) {

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

}

}

public static void main(String args[]) {

myMeth("test", 10);

}

}