1 /*
   2  * Copyright 2004 Sun Microsystems, Inc.  All Rights Reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package com.sun.mirror.apt;
  27 
  28 
  29 import java.util.Collection;
  30 import java.util.Map;
  31 
  32 import com.sun.mirror.declaration.*;
  33 import com.sun.mirror.util.*;
  34 
  35 
  36 /**
  37  * The environment encapsulating the state needed by an annotation processor.
  38  * An annotation processing tool makes this environment available
  39  * to all annotation processors.
  40  *
  41  * <p> When an annotation processing tool is invoked, it is given a
  42  * set of type declarations on which to operate.  These
  43  * are refered to as the <i>specified</i> types.
  44  * The type declarations said to be <i>included</i> in this invocation
  45  * consist of the specified types and any types nested within them.
  46  *
  47  * <p> {@link DeclarationFilter}
  48  * provides a simple way to select just the items of interest
  49  * when a method returns a collection of declarations.
  50  *
  51  * @author Joseph D. Darcy
  52  * @author Scott Seligman
  53  * @since 1.5
  54  */
  55 
  56 public interface AnnotationProcessorEnvironment {
  57 
  58     /**
  59      * Returns the options passed to the annotation processing tool.
  60      * Options are returned in the form of a map from option name
  61      * (such as <tt>"-encoding"</tt>) to option value.
  62      * For an option with no value (such as <tt>"-help"</tt>), the
  63      * corresponding value in the map is <tt>null</tt>.
  64      *
  65      * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
  66      * Such options are unrecognized by the tool, but intended to be used by
  67      * some annotation processor.
  68      *
  69      * @return the options passed to the tool
  70      */
  71     Map<String,String> getOptions();
  72 
  73     /**
  74      * Returns the messager used to report errors, warnings, and other
  75      * notices.
  76      *
  77      * @return the messager
  78      */
  79     Messager getMessager();
  80 
  81     /**
  82      * Returns the filer used to create new source, class, or auxiliary
  83      * files.
  84      *
  85      * @return the filer
  86      */
  87     Filer getFiler();
  88 
  89 
  90 
  91     /**
  92      * Returns the declarations of the types specified when the
  93      * annotation processing tool was invoked.
  94      *
  95      * @return the types specified when the tool was invoked, or an
  96      * empty collection if there were none
  97      */
  98     Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
  99 
 100     /**
 101      * Returns the declaration of a package given its fully qualified name.
 102      *
 103      * @param name  fully qualified package name, or "" for the unnamed package
 104      * @return the declaration of the named package, or null if it cannot
 105      * be found
 106      */
 107     PackageDeclaration getPackage(String name);
 108 
 109     /**
 110      * Returns the declaration of a type given its fully qualified name.
 111      *
 112      * @param name  fully qualified type name
 113      * @return the declaration of the named type, or null if it cannot be
 114      * found
 115      */
 116     TypeDeclaration getTypeDeclaration(String name);
 117 
 118     /**
 119      * A convenience method that returns the declarations of the types
 120      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
 121      * in this invocation of the annotation processing tool.
 122      *
 123      * @return the declarations of the types included in this invocation
 124      * of the tool, or an empty collection if there are none
 125      */
 126     Collection<TypeDeclaration> getTypeDeclarations();
 127 
 128     /**
 129      * Returns the declarations annotated with the given annotation type.
 130      * Only declarations of the types
 131      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
 132      * in this invocation of the annotation processing tool, or
 133      * declarations of members, parameters, or type parameters
 134      * declared within those, are returned.
 135      *
 136      * @param a  annotation type being requested
 137      * @return the declarations annotated with the given annotation type,
 138      * or an empty collection if there are none
 139      */
 140     Collection<Declaration> getDeclarationsAnnotatedWith(
 141                                                 AnnotationTypeDeclaration a);
 142 
 143     /**
 144      * Returns an implementation of some utility methods for
 145      * operating on declarations.
 146      *
 147      * @return declaration utilities
 148      */
 149     Declarations getDeclarationUtils();
 150 
 151     /**
 152      * Returns an implementation of some utility methods for
 153      * operating on types.
 154      *
 155      * @return type utilities
 156      */
 157     Types getTypeUtils();
 158 
 159     /**
 160      * Add a listener.  If the listener is currently registered to listen,
 161      * adding it again will have no effect.
 162      *
 163      * @param listener The listener to add.
 164      * @throws NullPointerException if the listener is null
 165      */
 166     void addListener(AnnotationProcessorListener listener);
 167 
 168 
 169     /**
 170      * Remove a listener.  If the listener is not currently listening,
 171      * the method call does nothing.
 172      *
 173      * @param listener The listener to remove.
 174      * @throws NullPointerException if the listener is null
 175      */
 176     void removeListener(AnnotationProcessorListener listener);
 177 }