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.io.*;

    30 

    31 

    32 /**

    33  * This interface supports the creation of new files by an

    34  * annotation processor.

    35  * Files created in this way will be known to the annotation processing

    36  * tool implementing this interface, better enabling the tool to manage them.

    37  * Four kinds of files are distinguished:

    38  * source files, class files, other text files, and other binary files.

    39  * The latter two are collectively referred to as <i>auxiliary</i> files.

    40  *

    41  * <p> There are two distinguished locations (subtrees within the

    42  * file system) where newly created files are placed:

    43  * one for new source files, and one for new class files.

    44  * (These might be specified on a tool's command line, for example,

    45  * using flags such as <tt>-s</tt> and <tt>-d</tt>.)

    46  * Auxiliary files may be created in either location.

    47  *

    48  * <p> During each run of an annotation processing tool, a file

    49  * with a given pathname may be created only once.  If that file already

    50  * exists before the first attempt to create it, the old contents will

    51  * be deleted.  Any subsequent attempt to create the same file during

    52  * a run will fail.

    53  *

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

    55  * standardized annotation processing API.  The replacement for the

    56  * functionality of this interface is {@link

    57  * javax.annotation.processing.Filer}.

    58  *

    59  * @author Joseph D. Darcy

    60  * @author Scott Seligman

    61  * @since 1.5

    62  */

    63 @Deprecated

    64 @SuppressWarnings("deprecation")

    65 public interface Filer {

    66 

    67     /**

    68      * Creates a new source file and returns a writer for it.

    69      * The file's name and path (relative to the root of all newly created

    70      * source files) is based on the type to be declared in that file.

    71      * If more than one type is being declared, the name of the principal

    72      * top-level type (the public one, for example) should be used.

    73      *

    74      * <p> The {@linkplain java.nio.charset.Charset charset} used to

    75      * encode the file is determined by the implementation.

    76      * An annotation processing tool may have an <tt>-encoding</tt>

    77      * flag or the like for specifying this.  It will typically use

    78      * the platform's default encoding if none is specified.

    79      *

    80      * @param name  canonical (fully qualified) name of the principal type

    81      *          being declared in this file

    82      * @return a writer for the new file

    83      * @throws IOException if the file cannot be created

    84      */

    85     PrintWriter createSourceFile(String name) throws IOException;

    86 

    87     /**

    88      * Creates a new class file, and returns a stream for writing to it.

    89      * The file's name and path (relative to the root of all newly created

    90      * class files) is based on the name of the type being written.

    91      *

    92      * @param name canonical (fully qualified) name of the type being written

    93      * @return a stream for writing to the new file

    94      * @throws IOException if the file cannot be created

    95      */

    96     OutputStream createClassFile(String name) throws IOException;

    97 

    98     /**

    99      * Creates a new text file, and returns a writer for it.

   100      * The file is located along with either the

   101      * newly created source or newly created binary files.  It may be

   102      * named relative to some package (as are source and binary files),

   103      * and from there by an arbitrary pathname.  In a loose sense, the

   104      * pathname of the new file will be the concatenation of

   105      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.

   106      *

   107      * <p> A {@linkplain java.nio.charset.Charset charset} for

   108      * encoding the file may be provided.  If none is given, the

   109      * charset used to encode source files

   110      * (see {@link #createSourceFile(String)}) will be used.

   111      *

   112      * @param loc location of the new file

   113      * @param pkg package relative to which the file should be named,

   114      *          or the empty string if none

   115      * @param relPath final pathname components of the file

   116      * @param charsetName the name of the charset to use, or null if none

   117      *          is being explicitly specified

   118      * @return a writer for the new file

   119      * @throws IOException if the file cannot be created

   120      */

   121     PrintWriter createTextFile(Location loc,

   122                                String pkg,

   123                                File relPath,

   124                                String charsetName) throws IOException;

   125 

   126     /**

   127      * Creates a new binary file, and returns a stream for writing to it.

   128      * The file is located along with either the

   129      * newly created source or newly created binary files.  It may be

   130      * named relative to some package (as are source and binary files),

   131      * and from there by an arbitrary pathname.  In a loose sense, the

   132      * pathname of the new file will be the concatenation of

   133      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.

   134      *

   135      * @param loc location of the new file

   136      * @param pkg package relative to which the file should be named,

   137      *          or the empty string if none

   138      * @param relPath final pathname components of the file

   139      * @return a stream for writing to the new file

   140      * @throws IOException if the file cannot be created

   141      */

   142     OutputStream createBinaryFile(Location loc,

   143                                   String pkg,

   144                                   File relPath) throws IOException;

   145 

   146 

   147     /**

   148      * Locations (subtrees within the file system) where new files are created.

   149      *

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

   151      * the standardized annotation processing API.  The replacement

   152      * for the functionality of this enum is {@link

   153      * javax.tools.StandardLocation}.

   154      */

   155     @Deprecated

   156     enum Location {

   157         /** The location of new source files. */

   158         SOURCE_TREE,

   159         /** The location of new class files. */

   160         CLASS_TREE

   161     }

   162 }