Examples of javax.annotation.processing.Processor

javax.annotation.processing.Processor
The interface for an annotation processor.
Annotation processing happens in a sequence of {@linkplain javax.annotation.processing.RoundEnvironment rounds}. On each round, a processor may be asked to {@linkplain #process process} asubset of the annotations found on the source and class files produced by a prior round. The inputs to the first round of processing are the initial inputs to a run of the tool; these initial inputs can be regarded as the output of a virtual zeroth round of processing. If a processor was asked to process on a given round, it will be asked to process on subsequent rounds, including the last round, even if there are no annotations for it to process. The tool infrastructure may also ask a processor to process files generated implicitly by the tool's operation.
Each implementation of a {@code Processor} must provide apublic no-argument constructor to be used by tools to instantiate the processor. The tool infrastructure will interact with classes implementing this interface as follows:
1. If an existing {@code Processor} object is not being used, tocreate an instance of a processor the tool calls the no-arg constructor of the processor class.
2. Next, the tool calls the {@link #init init} method withan appropriate {@code ProcessingEnvironment}.
3. Afterwards, the tool calls {@link #getSupportedAnnotationTypes getSupportedAnnotationTypes}, {@link #getSupportedOptions getSupportedOptions}, and {@link #getSupportedSourceVersion getSupportedSourceVersion}. These methods are only called once per run, not on each round.
4. As appropriate, the tool calls the {@link #process process}method on the {@code Processor} object; a new {@code Processor}object is not created for each round.
If a processor object is created and used without the above protocol being followed, then the processor's behavior is not defined by this interface specification.
The tool uses a discovery process to find annotation processors and decide whether or not they should be run. By configuring the tool, the set of potential processors can be controlled. For example, for a {@link javax.tools.JavaCompiler JavaCompiler} the list of candidate processors to run can be{@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors set directly} or controlled by a {@linkplain javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}used for a {@linkplain java.util.ServiceLoader service-style}lookup. Other tool implementations may have different configuration mechanisms, such as command line options; for details, refer to the particular tool's documentation. Which processors the tool asks to {@linkplain #process run} is a functionof the types of the annotations {@linkplain AnnotatedConstruct present} on the {@linkplain RoundEnvironment#getRootElements root elements}, what {@linkplain #getSupportedAnnotationTypes annotation types a processorsupports}, and whether or not a processor {@linkplain #process claims the annotation types it processes}. A processor will be asked to process a subset of the annotation types it supports, possibly an empty set. For a given round, the tool computes the set of annotation types that are present on the elements enclosed within the root elements. If there is at least one annotation type present, then as processors claim annotation types, they are removed from the set of unmatched annotation types. When the set is empty or no more processors are available, the round has run to completion. If there are no annotation types present, annotation processing still occurs but only universal processors which support processing all annotation types, {@code "*"}, can claim the (empty) set of annotation types.
An annotation type is considered present if there is at least one annotation of that type present on an element enclosed within the root elements of a round. For this purpose, a type parameter is considered to be enclosed by its {@linkplain TypeParameterElement#getGenericElement genericelement}. Annotations on {@linkplain java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to annotations on elements, are ignored when computing whether or not an annotation type is present.
An annotation is present if it meets the definition of being present given in {@link AnnotatedConstruct}. In brief, an annotation is considered present for the purposes of discovery if it is directly present or present via inheritance. An annotation is not considered present by virtue of being wrapped by a container annotation. Operationally, this is equivalent to an annotation being present on an element if and only if it would be included in the results of {@link Elements#getAllAnnotationMirrors(Element)} called on that element. Sinceannotations inside container annotations are not considered present, to properly process {@linkplain java.lang.annotation.Repeatable repeatable annotation types}, processors are advised to include both the repeatable annotation type and its containing annotation type in the set of {@linkplain #getSupportedAnnotationTypes() supported annotation types} of aprocessor.
Note that if a processor supports {@code "*"} and returns {@code true}, all annotations are claimed. Therefore, a universal processor being used to, for example, implement additional validity checks should return {@code false} so as to not prevent other suchcheckers from being able to run.
If a processor throws an uncaught exception, the tool may cease other active annotation processors. If a processor raises an error, the current round will run to completion and the subsequent round will indicate an {@linkplain RoundEnvironment#errorRaised error was raised}. Since annotation processors are run in a cooperative environment, a processor should throw an uncaught exception only in situations where no error recovery or reporting is feasible.
The tool environment is not required to support annotation processors that access environmental resources, either {@linkplain RoundEnvironment per round} or {@linkplain ProcessingEnvironment cross-round}, in a multi-threaded fashion.
If the methods that return configuration information about the annotation processor return {@code null}, return other invalid input, or throw an exception, the tool infrastructure must treat this as an error condition.
To be robust when running in different tool implementations, an annotation processor should have the following properties:
1. The result of processing a given input is not a function of the presence or absence of other inputs (orthogonality).
2. Processing the same input produces the same output (consistency).
3. Processing input A followed by processing input B is equivalent to processing B then A (commutativity)
4. Processing an input does not rely on the presence of the output of other annotation processors (independence)
The {@link Filer} interface discusses restrictions on howprocessors can operate on files.
Note that implementors of this interface may find it convenient to extend {@link AbstractProcessor} rather than implementing thisinterface directly. @author Joseph D. Darcy @author Scott Seligman @author Peter von der Ahé @since 1.6

    }
    // Cast all the processors here, rather than failing later.
    // But don't call init() until the processor is actually needed.
    _setProcessors = new ArrayList<Processor>(processors.length);
    for (Object o : processors) {
      Processor p = (Processor)o;
      _setProcessors.add(p);
    }
    _setProcessorIter = _setProcessors.iterator();


    // processors set this way take precedence over anything on the command line

View Full Code Here

  @Override
  public ProcessorInfo discoverNextProcessor() {
    if (null != _setProcessors) {
      // If setProcessors() was called, use that list until it's empty and then stop.
      if (_setProcessorIter.hasNext()) {
        Processor p = _setProcessorIter.next();
        p.init(_processingEnv);
        ProcessorInfo pi = new ProcessorInfo(p);
        _processors.add(pi);
        if (_printProcessorDiscovery && null != _out) {
          _out.println("API specified processor: " + pi); //$NON-NLS-1$
        }
        return pi;
      }
      return null;
    }
    
    if (null != _commandLineProcessors) {
      // If there was a -processor option, iterate over processor names, 
      // creating and initializing processors, until no more names are found, then stop.
      if (_commandLineProcessorIter.hasNext()) {
        String proc = _commandLineProcessorIter.next();
        try {
          Class<?> clazz = _procLoader.loadClass(proc);
          Object o = clazz.newInstance();
          Processor p = (Processor) o;
          p.init(_processingEnv);
          ProcessorInfo pi = new ProcessorInfo(p);
          _processors.add(pi);
          if (_printProcessorDiscovery && null != _out) {
            _out.println("Command line specified processor: " + pi); //$NON-NLS-1$
          }
          return pi;
        } catch (Exception e) {
          // TODO: better error handling
          throw new AbortCompilation(null, e);
        }
      }
      return null;
    }
    
    // if no processors were explicitly specified with setProcessors() 
    // or the command line, search the processor path with ServiceLoader.
    if (null == _serviceLoader ) {
      _serviceLoader = ServiceLoader.load(Processor.class, _procLoader);
      _serviceLoaderIter = _serviceLoader.iterator();
    }
    try {
      if (_serviceLoaderIter.hasNext()) {
        Processor p = _serviceLoaderIter.next();
        p.init(_processingEnv);
        ProcessorInfo pi = new ProcessorInfo(p);
        _processors.add(pi);
        if (_printProcessorDiscovery && null != _out) {
          StringBuilder sb = new StringBuilder();
          sb.append("Discovered processor service "); //$NON-NLS-1$

View Full Code Here

    }
    // Cast all the processors here, rather than failing later.
    // But don't call init() until the processor is actually needed.
    _setProcessors = new ArrayList<Processor>(processors.length);
    for (Object o : processors) {
      Processor p = (Processor)o;
      _setProcessors.add(p);
    }
    _setProcessorIter = _setProcessors.iterator();


    // processors set this way take precedence over anything on the command line

View Full Code Here

TOP

Related Classes of javax.annotation.processing.Processor

org.eclipse.jdt.internal.compiler.apt.dispatch.BatchAnnotationProcessorManager

All source code are property of their respective owners. Java is a trademark of Sun Microsystems, Inc and owned by ORACLE Inc. Contact coftware#gmail.com.