|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 전의 클래스 다음의 클래스 | 프레임 있어 프레임 없음 | |||||||||
| 개요: 상자 | 필드 | 생성자 | 메소드 | 상세: 필드 | 생성자 | 메소드 | |||||||||
public interface Processor
주석 프로세서의 인터페이스.
주석 처리는, 일련 라운드 내에서 실행됩니다. 각 라운드에서는, 전회의 라운드로 생성된 원시 파일과 클래스 파일로 발견된 주석의 부분집합의 처리 를, 어느 프로세서가 의뢰받을 가능성이 있습니다. 1 번째의 처리 라운드에의 입력은 툴의 실행에의 초기 입력이 됩니다만, 이러한 초기 입력은, 가상적인 0 번째의 처리 라운드의 출력으로 간주할 수가 있습니다. 어느 프로세서가 특정의 라운드로 처리를 의뢰받았을 경우, 비록 그 프로세서의 처리 대상이 되는 주석이 존재하지 않는 경우에서도, 그 프로세서는 최종 라운드를 포함한 후속의 라운드에서도 처리를 의뢰받습니다. 또, 툴 인프라스트럭쳐(infrastructure)는, 그 툴의 조작에 의해 암묵적으로 생성된 파일의 처리를, 프로세서에 의뢰하는 일도 있습니다.
Processor 의 각 구현에서는, 툴이 프로세서를 인스턴스화하기 위해서(때문에) 사용하는 인수 없음의 public 생성자 을 제공할 필요가 있습니다. 툴 인프라스트럭쳐(infrastructure)와 이 인터페이스를 구현한 클래스와의 상호작용은, 다음과 같이 됩니다.
Processor 객체가 사용되지 않는 경우, 툴은, 어느 프로세서의 인스턴스를 작성하기 위해서, 그 프로세서의 클래스의 인수 없음 생성자 을 호출한다.
init 메소드를 적절한 ProcessingEnvironment 를 지정해 호출한다.
getSupportedAnnotationTypes ,getSupportedOptions , 및 getSupportedSourceVersion 를 호출한다. 이러한 메소드가 불려 가는 것은, 실행 마다 1 회 뿐이다. 라운드 마다 1 회는 아니다.
Processor 객체의 process 메소드를 호출한다. 라운드 마다 새로운 Processor 객체가 작성되는 것은 아니다.
툴은, 「검출 처리」를 사용해 주석 프로세서를 찾아내, 그것들을 실행해야할 것인가 제발을 결정합니다. 툴을 구성하는 것으로, 가능성이 있는 프로세서세트를 제어할 수 있습니다. 예를 들어,JavaCompiler 의 경우, 실행 후보 프로세서의 리스트는,직접 설정 하는 일도,서비스 스타일 의 검색으로 사용되는검색 패스 를 사용해 제어할 수도 있습니다. 다른 툴 구현은, 커멘드행 옵션 등, 다른 구성 기구를 갖추고 있을 가능성도 있습니다만, 그 상세한 것에 대하여는, 특정의 툴의 문서를 참조해 주세요. 툴이 어느 프로세서에 실행 을 의뢰할까는,루트 요소 상에 어느 주석이 존재하고 있는지, 어느 주석형을 각 프로세서가 처리하는 인가, 및 각 프로세서가 처리 대상의 주석을 요구하는 화도인가, 에 의해 정해집니다. 각 프로세서는, 자신이 지원하는 주석형의 부분집합의 처리를 의뢰받습니다. 다만, 그 부분집합이 빈 상태(empty) 세트가 될 가능성도 있습니다.
어느 특정의 라운드로, 툴은, 루트 요소상의 주석형세트를 계산합니다. 주석형이 적어도 1 개(살) 존재하는 경우, 프로세서가 주석형을 요구할 때마다, 그러한 주석형이 불일치의 주석 세트로부터 삭제되어 갑니다. 이 세트가 비우는지, 사용 가능한 프로세서가 없어지면(자), 그 라운드는 종료합니다. 주석형이 존재하지 않는 경우도 주석 처리는 실행됩니다만, (빈 상태(empty)의) 주석형 세트를 요구할 수 있는 것은,「*」 의 처리를 지원하는 「범용 프로세서」 뿐입니다.
「*」 을 지원하는 프로세서가 true 를 돌려주면(자), 모든 주석이 요구되는 것에 주의해 주세요. 따라서, 예를 들어, 추가의 타당성 체크의 구현에 사용되는 범용 프로세서는,false 를 돌려주어야 합니다. 그러면, 다른 그러한 checker의 실행을 방해하지 않고 끝납니다.
어느 프로세서가 캐치 되지 않는 예외를 throw 하면(자), 툴은, 다른 액티브한 주석 프로세서를 중지할 가능성이 있습니다. 어느 프로세서가 에러를 발행하면(자), 현재의 라운드는 종료해, 후속의 라운드가,에러가 발행된 일을 통지합니다. 주석 프로세서는 협조적인 환경내에서 실행되기 (위해)때문에, 캐치 되지 않는 예외를 프로세서로부터 throw 하는 것은, 에러의 복구나 보고가 실행 불가능한 경우에 한정해야 합니다.
툴 환경은,라운드 마다, 혹은 라운드를 걸쳐, multi-thread 방식에서 환경 자원에 액세스 하는 주석 프로세서를 지원할 필요는 없습니다.
주석 프로세서에 관한 구성 정보를 돌려주는 메소드가 null 를 돌려주었는지, 그 외의 무효인 입력을 돌려주었는지, 혹은 예외를 throw 했을 경우, 툴 인프라스트럭쳐(infrastructure)는 그것을 에러 상태로 간주합니다.
어느 주석 프로세서를 다양한 툴 구현내에서 실행시키는 경우, 그 동작을 안정시키려면 , 그 프로세서는 다음의 특성을 갖추고 있어야 합니다.
Filer 인터페이스에서는, 프로세서가 어떻게 파일을 조작할 수 있을까에 관한 제한에 대해 설명하고 있습니다.
이 인터페이스의 구현자는, 이 인터페이스를 직접 구현하는 것보다도,AbstractProcessor 를 확장하는 편이 편리하다라고 느낄 것입니다.
| 메소드의 개요 | |
|---|---|
Iterable <? extends Completion > |
getCompletions (Element element,
AnnotationMirror annotation,
ExecutableElement member,
String userText)
있는 주석에 대한 추천의 컴플리트로부터 완성되는 반복 가능 객체를, 툴 인프라스트럭쳐(infrastructure)에 돌려줍니다. |
Set <String > |
getSupportedAnnotationTypes ()
이 프로세서가 지원하는 주석형의 이름을 돌려줍니다. |
Set <String > |
getSupportedOptions ()
이 프로세서가 인식하는 옵션을 돌려줍니다. |
SourceVersion |
getSupportedSourceVersion ()
이 주석 프로세서가 지원하는 최신 소스 버젼을 돌려줍니다. |
void |
init (ProcessingEnvironment processingEnv)
지정된 처리 환경 processingEnv 를 사용해 프로세서를 초기화합니다. |
boolean |
process (Set <? extends TypeElement > annotations,
RoundEnvironment roundEnv)
전회의 라운드로 생성된 형태 요소의 주석형세트를 처리해, 이 프로세서가 그러한 주석을 요구할지 어떨지를 돌려줍니다. |
| 메소드의 상세 |
|---|
Set <String > getSupportedOptions()
getOptions 를 참조해 주세요.
세트내에 반환되는 각 캐릭터 라인은, 다음과 같은, 피리어드로 단락지어진 일련의 식별자 가 됩니다.
- SupportedOptionString:
- Identifiers
- Identifiers:
- Identifier
- Identifier
.Identifiers
- Identifier:
- 키워드나 리터럴이라고 한, 구문상의 식별자
툴은, 이 정보를 사용해, 사용자가 지정한 옵션을 프로세서가 인식할지 어떨지를 판정합니다. 인식하지 않는 경우, 툴은 경고를 보고합니다.
SupportedOptions Set <String > getSupportedAnnotationTypes()
「*」 은 그 만큼으로, 빈 상태(empty) 세트를 포함한, 모든 주석형세트를 나타냅니다. 프로세서는, 실제로 모든 파일을 처리하므로 없는 한,「*」 을 요구해야 하지는 않습니다. 불필요한 주석을 요구했을 경우, 환경에 따라서는 퍼포먼스가 저하할 가능성이 있습니다.
세트내에 반환되는 각 캐릭터 라인은, 다음의 문법으로 받아들여지는 것이 아니면 안됩니다.
여기서,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 가 돌려주어졌을 경우, 그러한 주석은 요구되지 않고, 후속의 프로세서는 아마 그러한 처리를 의뢰받습니다. 프로세서는, 항상 같은 boolean 치를 돌려주는 일도, 선택된 조건에 근거해 결과를 바꿀 수도 있습니다.
프로세서가 「*」 을 지원하고 있어 루트 요소가 주석을 1 개도 가지지 않는 경우, 입력세트는 비웁니다. Processor 는 빈 상태(empty)의 주석 세트를 적절히 처리하지 않으면 안됩니다.
annotations - 처리가 요구된 주석형roundEnv - 현재 및 전회의 라운드에 대한 정보에 대한 환경
Iterable <? extends Completion > getCompletions(Element element,
AnnotationMirror annotation,
ExecutableElement member,
String userText)
int 멤버나, 정규 표현이나 URL 와 같은, 어느 기존의 문법에 따라 인식되어야 할 캐릭터 라인 멤버 등, 프로세서에 기존의 추가 타당성 제약을 가지는 주석 멤버에 대한 컴플리트를 제공하는 것에, 노력을 집중시켜야 합니다.
불완전한 프로그램의 모델화를 하고 있기 (위해)때문에, 몇개의 파라미터는, 부분적인 정보 밖에 가지지 않기도 하고,null 이거나 할 가능성이 있습니다. 적어도 element,userText 의 어느 쪽인지가,null 이외가 아니면 안됩니다. element 가 null 이외의 경우,annotation 와 member 는 null 에서도 괜찮습니다. 프로세서는, 일부의 파라미터가 null 에서도 NullPointerException 를 throw 할 수 없습니다. 지정된 정보에 근거해 제공해야 할 컴플리트를 프로세서가 1 개도 가지지 않는 경우, 빈 상태(empty)의 반복 가능 객체를 돌려줄 수가 있습니다. 또, 프로세서는, 빈 상태(empty)의 값캐릭터 라인이라고 컴플리트가 존재하지 않는 이유를 설명한 메세지를 포함한 단일의 컴플리트를 돌려줄 수도 있습니다.
컴플리트는 유익한 정보이며, 주석 프로세서에 의해 실행되는 추가 타당성 체크를 반영하는 경우가 있습니다. 예를 들어, 다음과 같은 단순한 주석이 있다고 합니다.
@MersennePrime {
int value();
}
메르센누 소수란, 2n - 1 의 형식의 소수를 가리킵니다. 이 주석형의 AnnotationMirror 가 지정되었을 경우,getCompletions 에 대하는 것 외의 인수를 검사하지 않는 채, 다음과 같이 int 범위에 있어서의 그러한 소수의 모든 것을 포함한 리스트를 돌려주어도 괜찮습니다.
컴플리트세트에 다음과 같이 소수의 값이 포함되어 있으면, 보다 유익하게 됩니다.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 가 사용 가능한 경우에는, 그 값을 체크하는 것으로, 메르센누 소수의 부분집합만이 유효한가 어떤가를 판단할 수 있습니다. 예를 들어, 사용자가 다음과 같이 입력했다고 합니다.
@MersennePrime(1
userText 의 값은 "1" 이 됩니다. 따라서, 가능한 컴플리트는 다음의 2 개의 소수만으로 됩니다.
return Arrays.asList(of("127", "M7"),
of("131071", "M17"));
유효한 컴플리트가 존재하지 않는 경우도 있습니다. 예를 들어, 9 로 시작되는 메르센누 소수는, 범위내에서는 존재하지 않습니다.
@MersennePrime(9
이 경우의 적절한 응답으로서는, 다음과 같이 빈 상태(empty)의 컴플리트 리스트를 돌려주는지,
혹은, 다음과 같이, 유용한 메세지를 포함한 단일의 빈 상태(empty) 컴플리트를 돌려줍니다.return Collections.emptyList();
return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
element - 주석을 붙일 수 있는 요소annotation - element 에 적용되는 (아마 부분적인) 주석member - 가능한 컴플리트를 돌려주는 대상이 되는 주석 멤버userText - 컴플리트의 대상이 되는 원시 코드 텍스트
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 전의 클래스 다음의 클래스 | 프레임 있어 프레임 없음 | |||||||||
| 개요: 상자 | 필드 | 생성자 | 메소드 | 상세: 필드 | 생성자 | 메소드 | |||||||||
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms . Documentation Redistribution Policy 도 참조해 주세요.