1 /*

     2  * Copyright (c) 2004, Oracle and/or its affiliates. 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.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * 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 }