Documentation Contents

Getting Started with the Annotation Processing Tool, apt

The following topics are covered

• The apt Tool Has Been Deprecated
• What is apt?
• Why Should I Use apt?
• How to use apt
• How the apt Tool Operates
• Declarations and Types
• FAQs
• See Also

The apt Tool Has Been Deprecated

The apt tool and its associated API contained in the package com.sun.mirror have been deprecated since JDK 7 and are planned to be removed in the next major JDK release. Use the options available in the javac tool and the APIs contained in the packages javax.annotation.processing and javax.lang.model to process annotations.

Summary of apt API Replacements

The following tables summarize apt API replacements:

What is apt?

Why Should I Use apt?

Compared to using a doclet to generate the derived files based on annotations, apt

• has a cleaner model of the declarations and current type structure of programs
• uses a more contemporary API design, such as returning generic collections instead of arrays and providing visitors to operate on declarations and types
• supports recursive processing of newly generated files and can automatically cause compilation of original and generated source files

How to use apt

Overview

Developing an Annotation Processor

• com.sun.mirror.apt: interfaces to interact with the tool
• com.sun.mirror.declaration: interfaces to model the source code declarations of fields, methods, classes, etc.
• com.sun.mirror.type: interfaces to model types found in the source code
• com.sun.mirror.util: various utilities for processing types and declarations, including visitors

A processor instance is returned by its corresponding factory -- an AnnotationProcessorFactory. The apt tool calls the factory's getProcessorFor method to get hold of the processor. During this call, the tool provides an AnnotationProcessorEnvironment. In the environment the processor will find everything it needs to get started, including references to the program structure on which it is operating, and the means to communicate and cooperate with the apt tool by creating new files and passing on warning and error messages.

There are two ways a factory can be found; the factory to use can be specified via the "-factory" command line option or the factory can be located during the apt discovery procedure. Using the "-factory" option is the simplest way to run a single known factory; this option may also be used when a factory needs more control over how it is run. To locate the factories on a particular path, the discovery procedure retrieves from jar files META-INF/services information in the format described below.

To create and use an annotation processor using the "-factory" option:

1. Write an AnnotationProcessorFactory that in turn can create an AnnotationProcessor for the annotation type(s) of interest.
2. Compile the processors and factories using javac with tools.jar on the classpath; tools.jar contains the com.sun.mirror.* interfaces.
3. Put the compiled class files, or jar files containing the class files, on the appropriate path when invoking apt

3. Create a UTF-8 encoded text file in META-INF/services named com.sun.mirror.apt.AnnotationProcessorFactory whose contents are a list of fully qualified names of the concrete factory classes, one per line. (This is the same format used by sun.misc.Service.)
4. Package the factory, processor, and META-INF/services information into a jar file
5. Place the jar file on the appropriate path when invoking apt. The appropriate path is discussed in the Discovery section.

A Simple Sample Annotation Processor

import com.sun.mirror.apt.*;
import com.sun.mirror.declaration.*;
import com.sun.mirror.type.*;
import com.sun.mirror.util.*;

import java.util.Collection;
import java.util.Set;
import java.util.Arrays;

import static java.util.Collections.*;
import static com.sun.mirror.util.DeclarationVisitors.*;

/*
 * This class is used to run an annotation processor that lists class
 * names.  The functionality of the processor is analogous to the
 * ListClass doclet in the Doclet Overview.
 */
public class ListClassApf implements AnnotationProcessorFactory {
    // Process any set of annotations
    private static final Collection<String> supportedAnnotations
        = unmodifiableCollection(Arrays.asList("*"));

    // No supported options
    private static final Collection<String> supportedOptions = emptySet();

    public Collection<String> supportedAnnotationTypes() {
        return supportedAnnotations;
    }

    public Collection<String> supportedOptions() {
        return supportedOptions;
    }

    public AnnotationProcessor getProcessorFor(
            Set<AnnotationTypeDeclaration> atds,
            AnnotationProcessorEnvironment env) {
        return new ListClassAp(env);
    }

    private static class ListClassAp implements AnnotationProcessor {
        private final AnnotationProcessorEnvironment env;
        ListClassAp(AnnotationProcessorEnvironment env) {
            this.env = env;
        }

        public void process() {
            for (TypeDeclaration typeDecl : env.getSpecifiedTypeDeclarations())
                typeDecl.accept(getDeclarationScanner(new ListClassVisitor(),
                                                      NO_OP));
        }

        private static class ListClassVisitor extends SimpleDeclarationVisitor {
            public void visitClassDeclaration(ClassDeclaration d) {
                System.out.println(d.getQualifiedName());
            }
        }
    }
}

A number of new language and library features are used in the sample processor. First, static imports are used so that the simple name of various utility methods can be used; for example
"unmodifiableCollection"
instead of
"Collections.unmodifiableCollection".
Second, generic collections are used throughout. The Arrays.asList method is now a var-args method so it can accept a comma separated list of strings and create a list with the desired elements. The Collections.emptySet method is a generic method and can be used to create a type-safe empty set. The for loop in the process method is an enhanced for loop that can iterate over collections.

Specifying the Annotations to Process

*

Process all annotations. This also processes an empty list of annotations; in other words, a factory that processes * could be asked to provide a non-trivial processor even if no annotations are present. This capability allows the com.sun.mirror APIs to be used to write general source code processing tools.

foo.bar.Baz

Process an annotation whose canonical name is "foo.bar.Baz".

foo.bar.*

Process annotations whose canonical names start with "foo.bar.".

The apt tool presents the factory with a set of annotations for the factory to process. Based on the set of annotations and the annotation processor environment, the factory returns a single annotation processor. What if the factory wants to return multiple annotation processors? The factory can use com.sun.mirror.apt.AnnotationProcessors.getCompositeAnnotationProcessor to combine and sequence the operation of multiple annotation processors.

Specifying the Command Line Options to Recognize

The apt Command Line

The apt specific options are:

-s dir

Specify the directory root under which processor-generated source files will be placed; files are placed in subdirectories based on package namespace

-nocompile

Do not compile source files to class files.

-print

Print out textual representation of specified types; perform no annotation processing or compilation.

-A[key[=val]]

Options to pass to annotation processors -- these are not interpreted by apt directly, but are made available for use by individual processors

-factorypath path

Specify where to find annotation processor factories; if this option is used, the classpath is not searched for factories.

-factory classname

Name of AnnotationProcessorFactory to use; bypasses default discovery process

-d dir

Specify where to place processor and javac generated class files

-cp path or -classpath path

Specify where to find user class files and annotation processor factories. If -factorypath is given, the classpath is not searched for factories.

-XListAnnotationTypes

List found annotation types

-XListDeclarations

List specified and included declarations

-XPrintAptRounds

Print information about initial and recursive apt rounds

-XPrintFactoryInfo

Print information about which annotations a factory is asked to process

How the apt Tool Operates

Discovery

If a factory class is used by more than one round of annotation processing, the factory class is loaded once and the factory's getProcessorFor method will be called once per round. This allows a factory to store static state across rounds.

If the -factory option is used, the named factory is the only one queried.

Rounds of apt Processing

Listeners

Return Code

Declarations and Types

The mirror API represents source code constructs principally through the Declaration interface and its hierarchy of subinterfaces, in the package com.sun.mirror.declaration. A Declaration represents a program element such as a package, class, or method, and typically corresponds one-to-one with a particular fragment of source code. Declarations are the structures that may be annotated.

Types are represented by the TypeMirror interface and its hierarchy of subinterfaces in the package com.sun.mirror.type. Types include primitive types, class and interface types, array types, type variables, and wildcard types.

The API is careful to distinguish between declarations and types. This is most significant for generic types, where a single declaration can define a whole family of types. For example, the declaration of the class java.util.Set corresponds to

• the parameterized type java.util.Set<String>
• the parameterized type java.util.Set<Number>
• the parameterized type java.util.Set<T> for some type T other than String or Number
• the raw type java.util.Set.

TypeMirrors are used to model the return types, parameter types, etc., in source code. A TypeMirror for a reference type provides a mapping from a type to corresponding declaration; for example from the type mirror for java.util.Set<String> to the declaration for java.util.Set.

FAQs

• Do you know about the Debian Advanced Packaging Tool?
  Yes.
• How does an annotation processor compare to a doclet?
  The two entities certainly have some similarities; both use build-time reflective APIs to process source code. However, the mirror APIs used in annotation processors better model the current type system of the Java programming language. Also, by default the annotation processor(s) to run are determined by the annotations present in the source code rather than only on a mechanism analogous to the -doclet option. In other words, instead of running a single fixed doclet, apt dynamically chooses potentially multiple processors to run.
• How can I process annotations on local variables?
  Annotations on local variables are invisible since the declaration hierarchy does not model program structure inside a method or constructor.
• Why are there separate factory and processor interfaces in com.sun.mirror.apt?
  It would be possible to combine determining how to process and controlling when to process; however, we choose to distinguish and separate the two steps with factory and processor interfaces.
• What is a mirror?
  Somewhere you find a reflection. In reflective programming, a mirror design maintains a consistent separation between the objects being represented and the objects doing the representing.
• Why were the annotations a factory supports and the options a factory supports returned by methods instead of being encoded as annotations on the factory class?
  Implementing an interface is the usual mechanism to indicate a class has a desired capability, such as providing an indication of what annotations it processes. There is no language mechanism to require a class be annotated with a particular annotation type. Therefore, while it would have been technically possible to encode such information in annotations, doing so would have lacked the type safety of just having methods in an interface.
• I'm not familiar with visitors, do I have to use them?
  The visitor pattern is one of the standard patterns in the "Gang of Four" Design Patterns book. The pattern provides a powerful mechanism to invoke a type-dependent operation without explicitly testing for the type. However, using visitors is not mandatory.

See Also

• apt Tool Reference Page
• Mirror API Specification

---

Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

Contact Us