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  * @deprecated All components of this API have been superseded by the
  52  * standardized annotation processing API.  The replacement for the
  53  * functionality of this interface is {@link
  54  * javax.annotation.processing.ProcessingEnvironment}.
  55  *
  56  * @author Joseph D. Darcy
  57  * @author Scott Seligman
  58  * @since 1.5
  59  */
  60 @Deprecated
  61 @SuppressWarnings("deprecation")
  62 public interface AnnotationProcessorEnvironment {
  63 
  64     /**
  65      * Returns the options passed to the annotation processing tool.
  66      * Options are returned in the form of a map from option name
  67      * (such as <tt>"-encoding"</tt>) to option value.
  68      * For an option with no value (such as <tt>"-help"</tt>), the
  69      * corresponding value in the map is <tt>null</tt>.
  70      *
  71      * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
  72      * Such options are unrecognized by the tool, but intended to be used by
  73      * some annotation processor.
  74      *
  75      * @return the options passed to the tool
  76      */
  77     Map<String,String> getOptions();
  78 
  79     /**
  80      * Returns the messager used to report errors, warnings, and other
  81      * notices.
  82      *
  83      * @return the messager
  84      */
  85     Messager getMessager();
  86 
  87     /**
  88      * Returns the filer used to create new source, class, or auxiliary
  89      * files.
  90      *
  91      * @return the filer
  92      */
  93     Filer getFiler();
  94 
  95 
  96     /**
  97      * Returns the declarations of the types specified when the
  98      * annotation processing tool was invoked.
  99      *
 100      * @return the types specified when the tool was invoked, or an
 101      * empty collection if there were none
 102      */
 103     Collection<TypeDeclaration> getSpecifiedTypeDeclarations();
 104 
 105     /**
 106      * Returns the declaration of a package given its fully qualified name.
 107      *
 108      * @param name  fully qualified package name, or "" for the unnamed package
 109      * @return the declaration of the named package, or null if it cannot
 110      * be found
 111      */
 112     PackageDeclaration getPackage(String name);
 113 
 114     /**
 115      * Returns the declaration of a type given its fully qualified name.
 116      *
 117      * @param name  fully qualified type name
 118      * @return the declaration of the named type, or null if it cannot be
 119      * found
 120      */
 121     TypeDeclaration getTypeDeclaration(String name);
 122 
 123     /**
 124      * A convenience method that returns the declarations of the types
 125      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
 126      * in this invocation of the annotation processing tool.
 127      *
 128      * @return the declarations of the types included in this invocation
 129      * of the tool, or an empty collection if there are none
 130      */
 131     Collection<TypeDeclaration> getTypeDeclarations();
 132 
 133     /**
 134      * Returns the declarations annotated with the given annotation type.
 135      * Only declarations of the types
 136      * {@linkplain AnnotationProcessorEnvironment <i>included</i>}
 137      * in this invocation of the annotation processing tool, or
 138      * declarations of members, parameters, or type parameters
 139      * declared within those, are returned.
 140      *
 141      * @param a  annotation type being requested
 142      * @return the declarations annotated with the given annotation type,
 143      * or an empty collection if there are none
 144      */
 145     Collection<Declaration> getDeclarationsAnnotatedWith(
 146                                                 AnnotationTypeDeclaration a);
 147 
 148     /**
 149      * Returns an implementation of some utility methods for
 150      * operating on declarations.
 151      *
 152      * @return declaration utilities
 153      */
 154     Declarations getDeclarationUtils();
 155 
 156     /**
 157      * Returns an implementation of some utility methods for
 158      * operating on types.
 159      *
 160      * @return type utilities
 161      */
 162     Types getTypeUtils();
 163 
 164     /**
 165      * Add a listener.  If the listener is currently registered to listen,
 166      * adding it again will have no effect.
 167      *
 168      * @param listener The listener to add.
 169      * @throws NullPointerException if the listener is null
 170      */
 171     void addListener(AnnotationProcessorListener listener);
 172 
 173 
 174     /**
 175      * Remove a listener.  If the listener is not currently listening,
 176      * the method call does nothing.
 177      *
 178      * @param listener The listener to remove.
 179      * @throws NullPointerException if the listener is null
 180      */
 181     void removeListener(AnnotationProcessorListener listener);
 182 }