javax.annotation.processing

Интерфейсный Процессор

Все Известные Классы с реализацией:

AbstractProcessor

public interface Processor

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

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

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

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

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

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

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

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

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

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

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

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

Filer интерфейс обсуждает ограничения на то, как процессоры могут работать на файлах.

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

С тех пор:

1.6

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
Iterable<? extends Completion>	getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText) Возвраты к инфраструктуре инструмента повторяемое из предложенных завершений к аннотации.
Set<String>	getSupportedAnnotationTypes() Возвращает имена типов аннотации, поддерживаемых этим процессором.
Set<String>	getSupportedOptions() Возвращает опции, распознанные этим процессором.
SourceVersion	getSupportedSourceVersion() Возвращает последнюю исходную версию, поддерживаемую этим процессором аннотации.
void	init(ProcessingEnvironment processingEnv) Инициализирует процессор со средой обработки.
boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) Ряд процессов аннотации вводит на элементах типа, происходящих из предшествующего раунда и возвратов, требуются ли эти аннотации этим процессором.

Деталь метода

getSupportedOptions

Set<String> getSupportedOptions()

Возвращает опции, распознанные этим процессором. Реализация инструмента обработки должна обеспечить способ передать специфичные для процессора опции отчетливо от опций, которые передают к инструменту непосредственно, видеть getOptions.

Каждая строка, возвращенная в наборе, должна быть периодом разделенная последовательность идентификаторов:

SupportedOptionString:

Идентификаторы

Идентификаторы:

Идентификатор

Идентификатор . Идентификаторы

Идентификатор:

Синтаксический идентификатор, включая ключевые слова и литералы

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

Возвраты:

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

См. Также:

SupportedOptions

getSupportedAnnotationTypes

Set<String> getSupportedAnnotationTypes()

Возвращает имена типов аннотации, поддерживаемых этим процессором. Элемент результата может быть каноническим (полностью определенным) именем поддерживаемого типа аннотации. Поочередно это может иметь форму "name.*", представляющий набор всех типов аннотации с каноническими именами, начинающимися "с name.". Наконец, "*" отдельно представляет набор всех типов аннотации, включая пустое множество. Отметьте, что процессор не должен требовать "*" если это фактически не обрабатывает все файлы; требование ненужных аннотаций может вызвать замедление производительности в некоторых средах.

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

SupportedAnnotationTypeString:

TypeName DotStaropt

*

DotStar:

. *

где TypeName как определяется в Спецификации языка Java™.

Возвраты:

имена типов аннотации поддерживаются этим процессором

См. Также:

SupportedAnnotationTypes

См. Спецификацию языка Java™:

3.8 Идентификаторы, 6.5.5 Значений Имен типов

getSupportedSourceVersion

SourceVersion getSupportedSourceVersion()

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

Возвраты:

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

См. Также:

SupportedSourceVersion, ProcessingEnvironment.getSourceVersion()

init

void init(ProcessingEnvironment processingEnv)

Инициализирует процессор со средой обработки.

Параметры:

processingEnv - среда для средств платформа инструмента обеспечивает для процессора

процесс

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

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

Входной набор будет пуст, если процессор будет поддерживать "*" и у корневых элементов нет никаких аннотаций. A Processor должен корректно обработать пустое множество аннотаций.

Параметры:

annotations - типы аннотации, которые требуют быть обработанными

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

Возвраты:

требуется ли набор аннотаций этим процессором

getCompletions

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

Возвраты к инфраструктуре инструмента повторяемое из предложенных завершений к аннотации. Так как относительно завершений просят, информация, предоставленная об аннотации, может быть неполной, как будто для фрагмента исходного кода. Процессор может возвратить пустое повторяемое. Процессоры аннотации должны фокусировать свои усилия на обеспечении завершений для элементов аннотации с дополнительными ограничениями законности, известными процессору, например int элемент, значение которого должно находиться между 1 и 10 или строковый элемент, который должен быть распознан известной грамматикой, такой как регулярное выражение или URL.

Так как неполные программы моделируются, некоторые из параметров могут только иметь частичную информацию или могут быть null. По крайней мере один из element и userText должен быть не -null. Если element не -null, annotation и member может быть null. Процессоры, возможно, не бросают a NullPointerException если некоторые параметры null; если у процессора нет никаких завершений, чтобы предложить основанный на предоставленной информации, пустое повторяемое может быть возвращено. Процессор может также возвратить единственное завершение с пустой строкой значения и сообщением, описывающим, почему нет никаких завершений.

Завершения информативны и могут отразить дополнительные проверки достоверности, выполняемые процессорами аннотации. Например, рассмотрите простую аннотацию:

 @MersennePrime {
    int value();
 }
 

(Начало Mersenne является простым числом формы ²ⁿ - 1.) Данный AnnotationMirror для этого типа аннотации, списка всех таких начал в int диапазон мог быть возвращен, не исследуя никакие другие параметры getCompletions:

 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"));
 

Однако, если userText доступно, это может быть проверено, чтобы видеть, допустимо ли только подмножество начал Mersenne. Например, если пользователь ввел

@MersennePrime(1

значение userText будет "1"; и только два из начал являются возможными завершениями:

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

Иногда никакое допустимое завершение не возможно. Например, нет никакого Mersenne в диапазоне главного запуска с 9:

@MersennePrime(9

Соответствующий ответ в этом случае должен или возвратить пустой список завершений,

 return Collections.emptyList();
 

или единственное пустое завершение с полезным сообщением

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

Параметры:

element - аннотируемый элемент

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

member - элемент аннотации, чтобы возвратить возможные завершения для

userText - текст исходного кода, который будет завершен

Возвраты:

предложенные завершения к аннотации