AnnotationProcessor


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.deployment.annotation;
25  
26  import java.lang.annotation.Annotation  ;
27  import java.lang.annotation.ElementType  ;
28  import java.lang.reflect.AnnotatedElement  ;
29  import java.util.logging.Level  ;
30  
31  /**
32   * <p>
33   * The annotation processor is the core engine to process annotations.
34   * All the processing configuration (input classes, error handlers, etc...)
35   * is provided by the ProcessingContext which can be either created from the 
36   * createContext method or through another mean. Once the ProcessingContext has 
37   * been initialized, it is passed to the process(ProcessingContext ctx) method which
38   * triggers the annotation processing. 
39   * </p>
40   *
41   * <p>
42   * Each class accessible from the ProcessingContext.getInputScanner instance, will be 
43   * scanned for annotations. 
44   * Each annotation will then be processed by invoking the corresponding AnnotationHandler
45   * from its annotation type. 
46   * </p>
47   *
48   * <p>
49   * The AnnotationProcessor can be configured by using the pushAnnotationHandler and 
50   * popAnnotationHandler which allow new AnnotationHandler instances to be registered and 
51   * unregistered for a particular annotation type.
52   * </p>
53   *
54   * <p>
55   * Even without reconfiguring the AnnotationProcessor instance with the above 
56   * configuration methods, the AnnotationProcessor implementation cannot guarantee
57   * to be thread safe, therefore, it is encouraged the make instanciation cheap
58   * and users should not use the same instance concurrently.
59   * </p>
60   * 
61   * @author Jerome Dochez
62   */
63  public interface AnnotationProcessor {
64  
65      /**
66       * Creates a new empty ProcessingContext instance which can be configured
67       * before invoking the process() method.
68       * @return an empty ProcessingContext
69       */
70      public ProcessingContext createContext();
71          
72      /**
73       * Starts the annotation processing tool passing the processing context which 
74       * encapuslate all information necessary for the configuration of the tool. 
75       * @param ctx is the initialized processing context
76       * @return the result of the annoations processing
77       */
78      public ProcessingResult process(ProcessingContext ctx) throws AnnotationProcessorException;
79          
80      /**
81       * Process a set of classes from the parameter list rather than from the 
82       * processing context. This allow the annotation handlers to call be the
83       * annotation processing tool when classes need to be processed in a 
84       * particular context rather than when they are picked up by the scanner.
85       * 
86       * @param the processing context 
87       * @param the list of classes to process
88       * @return the processing result for such classes
89       * @throws AnnotationProcessorException if handlers fail to process 
90       * an annotation
91       */
92      public ProcessingResult process(ProcessingContext ctx, Class  [] classes) 
93          throws AnnotationProcessorException;
94      
95      /**
96       * Registers a new AnnotationHandler for a particular annotation type. New annotation handler
97       * are pushed on a List of annotation handlers for that particular annotation type, the last 
98       * annotation handler to be registered will be invoked first and so on.
99       * The annotation type handled by the AnnotationHandler instance is defined 
100      * by the getAnnotationType() method of the AnnotationHandler instance 
101      *
102      * @param type the annotation type
103      * @param handler the annotation handler instance
104      */
105     public void pushAnnotationHandler(AnnotationHandler handler);
106     
107     /**
108      * @return the top annotation handler for a particular annotation type
109      * @param type the annotation type
110      */
111     public AnnotationHandler getAnnotationHandler(Class  <? extends Annotation  > type);
112     
113     /**
114      * Unregisters the last annotation handler registered for an annotation type.
115      * @param type the annotation type.
116      */
117     public void popAnnotationHandler(Class  <? extends Annotation  > type);
118     
119     /**
120      * @return the most recent AnnotatedElement being processed which type is of the 
121      * given ElementType or null if there is no such element in the stack of 
122      * processed annotation elements.
123      */
124     public AnnotatedElement   getLastAnnotatedElement(ElementType   type);
125     
126     /**
127      * Log a message on the default logger
128      */
129     public void log(Level   level, AnnotationInfo locator, String   localizedMessage);
130 }
131
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags