Интерфейс Processor

Интерфейс для обработчика аннотаций.

Обработка аннотаций происходит в последовательности раундов. В каждом раунде обработчик может быть запрошен на обработку подмножества аннотаций, найденных в исходных и class-файлах, сгенерированных в предыдущем раунде. Входные данные для первого раунда обработки — это начальные входные данные для выполнения инструмента; эти начальные входные данные можно рассматривать как вывод виртуального нулевого раунда обработки. Если обработчик был запрошен на обработку в определенном раунде, он будет запрошен на обработку в последующих раундах, включая последний, даже если для него нет аннотаций для обработки. Инфраструктура инструмента также может запросить обработчик на обработку файлов, неявно сгенерированных в процессе работы инструмента.

Каждая реализация Processor должна предоставлять публичный конструктор без аргументов, который будет использоваться инструментами для создания экземпляра обработчика. Инфраструктура инструмента будет взаимодействовать с классами, реализующими этот интерфейс, следующим образом:

1. Если существующий объект Processor не используется, для создания экземпляра обработчика инструмент вызывает конструктор без аргументов класса обработчика.
2. Далее инструмент вызывает метод init с соответствующим ProcessingEnvironment.
3. Затем инструмент вызывает getSupportedAnnotationTypes, getSupportedOptions и getSupportedSourceVersion. Эти методы вызываются только один раз за выполнение, а не в каждом раунде.
4. По мере необходимости инструмент вызывает метод process объекта Processor; новый объект Processor не создается для каждого раунда.

Инструмент использует процесс обнаружения для поиска обработчиков аннотаций и определения, следует ли их запускать. Настройка инструмента позволяет управлять набором потенциальных обработчиков. Например, для JavaCompiler список кандидатных обработчиков для запуска можно установить непосредственно или управлять им с помощью пути поиска, используемого для поиска в стиле сервиса. Другие реализации инструмента могут иметь различные механизмы настройки, такие как параметры командной строки; подробную информацию см. в документации конкретного инструмента. Какие обработчики инструмент просит запустить, зависит от типов аннотаций присутствующих в корневых элементах, от типов аннотаций, поддерживаемых обработчиком, и от того, заявляет ли обработчик обрабатываемые типы аннотаций. Обработчик будет запрошен на обработку подмножества типов аннотаций, которые он поддерживает, возможно, пустого набора. Для данного раунда инструмент вычисляет набор типов аннотаций, присутствующих в элементах, вложенных в корневые элементы. Если присутствует хотя бы один тип аннотации, обработчики, заявляющие о типах аннотаций, удаляются из набора несовпадающих типов аннотаций. Когда набор пуст или больше обработчиков недоступны, раунд завершен. Если типов аннотаций нет, обработка аннотаций все равно происходит, но только универсальные обработчики, которые поддерживают обработку всех типов аннотаций, "*", могут заявить о (пустом) наборе типов аннотаций.

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

Аннотация присутствует, если она соответствует определению присутствия, приведенному в AnnotatedConstruct. Вкратце, аннотация считается присутствующей для целей обнаружения, если она непосредственно присутствует или присутствует через наследование. Аннотация не считается присутствующей в силу того, что она обернута контейнерной аннотацией. Оперативно это эквивалентно тому, что аннотация присутствует на элементе, если и только если она будет включена в результаты вызова Elements.getAllAnnotationMirrors(Element) для данного элемента. Поскольку аннотации внутри контейнерных аннотаций не считаются присутствующими, для правильной обработки повторяемых типов аннотаций обработчикам рекомендуется включать как тип повторяемой аннотации, так и содержащий тип аннотации в набор поддерживаемых типов аннотаций обработчика.

Обратите внимание, что если обработчик поддерживает "*" и возвращает true, все аннотации заявляются. Поэтому универсальный обработчик, используемый, например, для реализации дополнительных проверок на валидность, должен возвращать false, чтобы не препятствовать работе других таких проверок.

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

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

Если методы, возвращающие конфигурационную информацию об обработчике аннотаций, возвращают null, возвращают другие недопустимые входные данные или генерируют исключение, инфраструктура инструмента должна обрабатывать это как условие ошибки.

Для повышения надежности при работе с различными реализациями инструментов обработчик аннотаций должен обладать следующими свойствами:

1. Результат обработки заданного входного значения не зависит от наличия или отсутствия других входных данных (ортогональность).
2. Обработка одного и того же входного значения приводит к одному и тому же результату (согласованность).
3. Обработка входного значения A, за которой следует обработка входного значения B, эквивалентна обработке B, за которой следует обработка A (коммутативность).
4. Обработка входного значения не зависит от наличия результата обработки других обработчиков аннотаций (независимость).

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

Обратите внимание, что реализаторам этого интерфейса может быть удобно расширить AbstractProcessor, а не реализовывать этот интерфейс напрямую.

Методы

getSupportedOptions

Set<String> getSupportedOptions()

Возвращает:

опции, распознаваемые этим процессором, или пустой набор, если их нет

См. также:

SupportedOptions

getSupportedAnnotationTypes

Set<String> getSupportedAnnotationTypes()

Возвращает:

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

См. также:

SupportedAnnotationTypes

getSupportedSourceVersion

SourceVersion getSupportedSourceVersion()

Возвращает последнюю поддерживаемую версию исходного кода этим процессором аннотаций.

Возвращает:

последнюю поддерживаемую версию исходного кода этим процессором аннотаций.

См. также:

SupportedSourceVersion, ProcessingEnvironment.getSourceVersion()

init

void init(ProcessingEnvironment processingEnv)

Инициализирует процессор с помощью среды обработки.

Параметры:

processingEnv - среда для функций, предоставляемых инструментом фреймворка процессору

process

boolean process(Set<? extends TypeElement> annotations,
                RoundEnvironment roundEnv)

Параметры:

annotations - типы аннотаций, запрошенные для обработки

roundEnv - среда для получения информации о текущем и предыдущем раунде

Возвращает:

являются ли типы аннотаций заявленными этим процессором

getCompletions

Iterable<? extends Completion> getCompletions(Element element,
                                              AnnotationMirror annotation,
                                              ExecutableElement member,
                                              String userText)

@MersennePrime {
   int value();
}

import static javax.annotation.processing.Completions.*;
...
return Arrays.asList(of("3"),
                     of("7"),
                     of("31"),
                     of("127"),
                     of("8191"),
                     of("131071"),
                     of("524287"),
                     of("2147483647"));

return Arrays.asList(of("3",          "M2"),
                     of("7",          "M3"),
                     of("31",         "M5"),
                     of("127",        "M7"),
                     of("8191",       "M13"),
                     of("131071",     "M17"),
                     of("524287",     "M19"),
                     of("2147483647", "M31"));

@MersennePrime(1

return Arrays.asList(of("127",        "M7"),
                     of("131071",     "M17"));

@MersennePrime(9

return Collections.emptyList();

return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));

Параметры:

element - элемент, к которому применяется аннотация

annotation - (возможно, частичная) аннотация, применяемая к элементу

member - член аннотации, для которого нужно вернуть возможные дополнения

userText - текст исходного кода, который должен быть дополнен

Возвращает:

предлагаемые дополнения к аннотации