Spec-Zone .ru
спецификации, руководства, описания, API
|
public interface Processor
Обработка аннотации происходит в последовательности раундов. На каждом раунде процессор можно попросить обработать подмножество аннотаций, найденных на источнике и файлах class, произведенных предшествующим раундом. Вводы к первому раунду обработки являются начальными вводами к выполнению инструмента; эти начальные вводы могут быть расценены как вывод виртуального нулевого раунда обработки. Если процессор попросили обработать на данном раунде, попросят обработать на последующих раундах, включая последний раунд, даже если не будет никаких аннотаций для этого, чтобы обработать. Инфраструктура инструмента может также попросить, чтобы процессор обработал файлы, сгенерированные неявно работой инструмента.
Каждая реализация a Processor
должен предоставить общедоступному конструктору без параметров, чтобы использоваться инструментами, чтобы инстанцировать процессора. Инфраструктура инструмента будет взаимодействовать с классами, реализовывая этот интерфейс следующим образом:
Processor
объект не используется, чтобы создать экземпляр процессора, инструмент вызывает конструктора без аргументов процессора class. init
метод с соответствующим ProcessingEnvironment
. getSupportedAnnotationTypes
, getSupportedOptions
, и getSupportedSourceVersion
. Однажды эти методы только вызывают на выполнение, не на каждом раунде. process
метод на Processor
объект; новое Processor
объект не создается для каждого раунда. Инструмент использует процесс открытия, чтобы найти процессоры аннотации и решить, должны ли они быть выполнены. Конфигурируя инструмент, набором потенциальных процессоров можно управлять. Например, для a JavaCompiler
список процессоров кандидата, чтобы работать может быть установлен непосредственно или управляться путем поиска, используемым для поиска стиля службы. У других реализаций инструмента могут быть различные механизмы конфигурации, такие как параметры командной строки; для деталей сошлитесь на документацию определенного инструмента. Какие процессоры, которые инструмент просит выполнять, являются функцией того, какие аннотации присутствуют на корневых элементах, какая аннотация вводит процессор процессы, и требует ли процессор аннотаций, которые это обрабатывает. Процессор попросят обработать подмножество типов аннотации, которые он поддерживает, возможно пустое множество. Для данного раунда инструмент вычисляет набор типов аннотации на корневых элементах. Если есть по крайней мере один существующий тип аннотации, поскольку процессоры требуют типов аннотации, они удаляются из набора несогласованных аннотаций. Когда набор пуст, или больше процессоров не доступно, раунд работал к завершению. Если нет никаких существующих типов аннотации, аннотация, обрабатывающая все еще, происходит, но только универсальные процессоры, которые поддерживают обработку "*"
может требовать (пустого) набора типов аннотации.
Отметьте это, если процессор поддерживает "*"
и возвраты true
, все аннотации требуются. Поэтому, универсальный процессор, привыкший к, например, реализует дополнительные проверки достоверности, должен возвратиться false
чтобы не предотвратить другие такие средства проверки от возможности работать.
Если процессор выдает непойманное исключение, инструмент может прекратить другие активные процессоры аннотации. Если процессор повысит ошибку, то текущий раунд будет работать к завершению, и последующий раунд укажет, что ошибка была повышена. Так как процессоры аннотации выполняются в совместной среде, процессор должен выдать непойманное исключение только в ситуациях, где никакое восстановление после ошибки или создание отчетов не выполнимы.
Среда инструмента не обязана поддерживать процессоры аннотации что доступ экологические ресурсы, или на раунд или перекрестный вокруг, многопоточным способом.
Если методы, которые возвращают конфигурационную информацию о возврате процессора аннотации null
, возвратите другой недопустимый ввод, или выдайте исключение, инфраструктура инструмента должна обработать это как состояние ошибки.
Чтобы быть устойчивым, работая в различных реализациях инструмента, у процессора аннотации должны быть следующие свойства:
Filer
интерфейс обсуждает ограничения на то, как процессоры могут работать на файлах.
Отметьте, что конструкторы этого интерфейса могут счесть удобным расшириться AbstractProcessor
вместо того, чтобы реализовывать этот интерфейс непосредственно.
Модификатор и Тип | Метод и Описание |
---|---|
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)
Ряд процессов аннотации вводит на элементах типа, происходящих из предшествующего раунда и возвратов, требуются ли эти аннотации этим процессором.
|
Set<String> getSupportedOptions()
getOptions
. Каждая строка, возвращенная в наборе, должна быть периодом разделенная последовательность идентификаторов:
- SupportedOptionString:
- Идентификаторы
- Идентификаторы:
- Идентификатор
- Идентификатор
.
Идентификаторы
- Идентификатор:
- Синтаксический идентификатор, включая ключевые слова и литералы
Инструмент мог бы использовать эту информацию, чтобы определить, являются ли какие-либо возможности, предоставленные пользователем, нераспознанными каким-либо процессором, когда это может хотеть сообщить о предупреждении.
SupportedOptions
Set<String> getSupportedAnnotationTypes()
"*"
отдельно представляет набор всех типов аннотации, включая пустое множество. Отметьте, что процессор не должен требовать "*"
если это фактически не обрабатывает все файлы; требование ненужных аннотаций может вызвать замедление производительности в некоторых средах. Каждая строка, возвращенная в наборе, должна быть принята следующей грамматикой:
где TypeName как определяется в Спецификации языка Java™.
- SupportedAnnotationTypeString:
- TypeName DotStaropt
- *
- DotStar:
- . *
SupportedAnnotationTypes
SourceVersion getSupportedSourceVersion()
SupportedSourceVersion
, ProcessingEnvironment.getSourceVersion()
void init(ProcessingEnvironment processingEnv)
processingEnv
- среда для средств платформа инструмента обеспечивает для процессораboolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
true
возвращается, аннотации требуются, и последующие процессоры не попросят обработать их; если false
возвращается, аннотации невостребованны, и последующие процессоры можно попросить обработать их. Процессор может всегда возвращать то же самое булево значение или может изменить результат, основанный на выбранных критериях. Входной набор будет пуст, если процессор будет поддерживать "*"
и у корневых элементов нет никаких аннотаций. A Processor
должен корректно обработать пустое множество аннотаций.
annotations
- типы аннотации, которые требуют быть обработаннымиroundEnv
- среда для информации о текущем и предшествующем раунде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
; если у процессора нет никаких завершений, чтобы предложить основанный на предоставленной информации, пустое повторяемое может быть возвращено. Процессор может также возвратить единственное завершение с пустой строкой значения и сообщением, описывающим, почему нет никаких завершений.
Завершения информативны и могут отразить дополнительные проверки достоверности, выполняемые процессорами аннотации. Например, рассмотрите простую аннотацию:
(Начало Mersenne является простым числом формы 2n - 1.) Данный@MersennePrime { int value(); }
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"
; и только два из начал являются возможными завершениями: Иногда никакое допустимое завершение не возможно. Например, нет никакого Mersenne в диапазоне главного запуска с 9: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
- текст исходного кода, который будет завершен
Для дальнейшей ссылки API и документации разработчика, см. Java Документация SE. Та документация содержит более подробные, предназначенные разработчиком описания, с концептуальными краткими обзорами, определениями сроков, обходных решений, и рабочих примеров кода.
Авторское право © 1993, 2013, Oracle и/или его филиалы. Все права защищены.
Проект сборка-b92