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.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 }