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.Set;

    31 

    32 import com.sun.mirror.declaration.AnnotationTypeDeclaration;

    33 

    34 

    35 /**

    36  * A factory for creating annotation processors.

    37  * Each factory is responsible for creating processors for one or more

    38  * annotation types.

    39  * The factory is said to <i>support</i> these types.

    40  *

    41  * <p> Each implementation of an <tt>AnnotationProcessorFactory</tt>

    42  * must provide a public no-argument constructor to be used by tools to

    43  * instantiate the factory.

    44  *

    45  * @deprecated All components of this API have been superseded by the

    46  * standardized annotation processing API.  The replacement for the

    47  * functionality of this interface is {@link

    48  * javax.annotation.processing.Processor}.

    49  *

    50  * @author Joseph D. Darcy

    51  * @author Scott Seligman

    52  * @since 1.5

    53  */

    54 @Deprecated

    55 @SuppressWarnings("deprecation")

    56 public interface AnnotationProcessorFactory {

    57 

    58     /**

    59      * Returns the options recognized by this factory or by any of the

    60      * processors it may create.

    61      * Only {@linkplain AnnotationProcessorEnvironment#getOptions()

    62      * processor-specific} options are included, each of which begins

    63      * with <tt>"-A"</tt>.  For example, if this factory recognizes

    64      * options such as <tt>-Adebug -Aloglevel=3</tt>, it will

    65      * return the strings <tt>"-Adebug"</tt> and <tt>"-Aloglevel"</tt>.

    66      *

    67      * <p> A tool might use this information to determine if any

    68      * options provided by a user are unrecognized by any processor,

    69      * in which case it may wish to report an error.

    70      *

    71      * @return the options recognized by this factory or by any of the

    72      * processors it may create, or an empty collection if none

    73      */

    74     Collection<String> supportedOptions();

    75 

    76     /**

    77      * Returns the names of the annotation types supported by this factory.

    78      * An element of the result may be the canonical (fully qualified) name

    79      * of a supported annotation type.  Alternately it may be of the form

    80      * <tt>"<i>name</i>.*"</tt>

    81      * representing the set of all annotation types

    82      * with canonical names beginning with <tt>"<i>name</i>."</tt>

    83      * Finally, <tt>"*"</tt> by itself represents the set of all

    84      * annotation types.

    85      *

    86      * @return the names of the annotation types supported by this factory

    87      */

    88     Collection<String> supportedAnnotationTypes();

    89 

    90     /**

    91      * Returns an annotation processor for a set of annotation

    92      * types. The set will be empty if the factory supports

    93      * &quot;<tt>*</tt>&quot; and the specified type declarations have

    94      * no annotations.  Note that the set of annotation types may be

    95      * empty for other reasons, such as giving the factory an

    96      * opportunity to register a listener.  An

    97      * <tt>AnnotationProcessorFactory</tt> must gracefully handle an

    98      * empty set of annotations; an appropriate response to an empty

    99      * set will often be returning {@link AnnotationProcessors#NO_OP}.

   100      *

   101      * @param atds type declarations of the annotation types to be processed

   102      * @param env  environment to use during processing

   103      * @return an annotation processor for the given annotation types,

   104      *          or <tt>null</tt> if the types are not supported or the

   105      *          processor cannot be created

   106      */

   107     AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> atds,

   108                                         AnnotationProcessorEnvironment env);

   109 }