langtools/src/share/classes/com/sun/mirror/apt/Filer.java
changeset 11914 d1311b0c757f
parent 11913 be61e1597cc6
parent 11872 c51754cddc03
child 11915 33f703959597
child 11986 6f383069eb6d
equal deleted inserted replaced
11913:be61e1597cc6 11914:d1311b0c757f
     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 }