Аннотации

Аннотации обеспечивают данные о программе, которая не является частью программы непосредственно. Они не оказывают прямого влияния на работу кода, который они аннотируют.

У аннотаций есть много использования среди них:

• Информация для компилятора — Аннотации может использоваться компилятором, чтобы обнаружить ошибки или подавить предупреждения.
• Разовая компилятором и разовая развертыванием обработка — Программные инструменты могут обработать информацию об аннотации, чтобы генерировать код, XML-файлы, и т.д.
• Обработка времени выполнения — Некоторые аннотации доступны, чтобы быть исследованными во времени выполнения.

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

Аннотация кажется первой, часто (условно) на ее собственной строке, и может включать элементы с именованными или безымянными значениями:

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

или

@SuppressWarnings(value = "unchecked")
void myMethod() { }

Если есть только один элемент, названный "значением", то имя может быть опущено, как в:

@SuppressWarnings("unchecked")
void myMethod() { }

Кроме того, если у аннотации нет никаких элементов, круглые скобки могут быть опущены, как в:

@Override
void mySuperMethod() { }

Документация

Много аннотаций заменяют то, что иначе было бы комментариями в коде.

Предположите, что группа программного обеспечения традиционно начала тело каждого class с комментариями, обеспечивающими важную информацию:

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";
   // Note use of array
   String[] reviewers();
}

Определение типа аннотации несколько походит на определение интерфейса где ключевое слово interface предшествуется символ (= "AT" как в Типе Аннотации). Типы аннотации являются, фактически, формой интерфейса, который будет покрыт более поздним уроком. В настоящий момент Вы не должны понять интерфейсы.

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

Как только тип аннотации был определен, можно использовать аннотации того типа, с заполненными значениями, как это:

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

// class code goes here

}

// import this to use @Documented
import java.lang.annotation.*;

@Documented
@interface ClassPreamble {

   // Annotation element definitions
   
}

Аннотации, Используемые Компилятором

Есть три типа аннотации, которые предопределяются спецификацией языка непосредственно: @Deprecated, @Override, и @SuppressWarnings.

@Deprecated — @Deprecated аннотация указывает, что отмеченный элемент осуждается и больше не должен использоваться. Компилятор генерирует предупреждение всякий раз, когда программа использует метод, class, или поле с @Deprecated аннотация. Когда элемент осуждается, он должен также быть задокументирован, используя Javadoc @deprecated тег, как показано в следующем примере. Использование символ и в комментариях Джейвэдока и в аннотациях не является случайным — они связываются концептуально. Кроме того, отметьте, что тег Javadoc запускается с нижнего регистра "d", и аннотация запускается с верхнего регистра "D".

   // Javadoc comment follows
    /**
     * @deprecated
     * explanation of why it
     * was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
}

@Override — @Override аннотация сообщает компилятору, что элемент предназначается, чтобы переопределить элемент, объявленный в суперклассе (переопределяющий методы, будет обсужден в урок, названный "Интерфейсы и Наследование").

   // mark method as a superclass method
   // that has been overridden
   @Override 
   int overriddenMethod() { }

В то время как это не обязано использовать эту аннотацию, переопределяя метод, это помогает предотвратить ошибки. Если метод, отмеченный с @Override сбои, чтобы правильно переопределить метод в одном из его суперклассов, компилятор генерирует ошибку.

@SuppressWarnings — @SuppressWarnings аннотация говорит компилятору подавлять определенные предупреждения, что это иначе генерировало бы. В примере ниже, используется осуждаемый метод, и компилятор обычно генерировал бы предупреждение. В этом случае, однако, аннотация заставляет предупреждение быть подавленным.

   // use a deprecated method and tell 
   // compiler not to generate a warning
   @SuppressWarnings("deprecation")
    void useDeprecatedMethod() {
        // deprecation warning
        // - suppressed
        objectOne.deprecatedMethod();
    }

Каждое предупреждение компилятора принадлежит категории. Спецификация языка Java перечисляет две категории: "осуждение" и "непроверенный". Предупреждение "непроверенное" может произойти, когда взаимодействие через интерфейс с наследством кодирует записанный перед появлением обобщений (обсужденный в уроке, названном "Обобщения"). Чтобы подавить больше чем одну категорию предупреждений, используйте следующий синтаксис:

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

Обработка аннотации

Более усовершенствованное использование аннотаций включает запись процессора аннотации, который может считать программу Java и предпринять меры, основанные на ее аннотациях. Это могло бы, например, генерировать вспомогательный исходный код, освобождая программиста от необходимости создать шаблонный код, который всегда следует за предсказуемыми образцами. Чтобы облегчить эту задачу, выпуск 5.0 JDK включает инструмент обработки аннотации, вызванный apt. В выпуске 6 JDK, функциональности apt стандартный компонент компилятора Java.

Чтобы сделать информацию об аннотации доступной во времени выполнения, тип самой аннотации должен быть аннотирован @Retention(RetentionPolicy.RUNTIME), следующим образом:

import java.lang.annotation.*; 

@Retention(RetentionPolicy.RUNTIME)
@interface AnnotationForRuntime {

   // Elements that give information
   // for runtime processing
   
}