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  * @author Joseph D. Darcy
  55  * @author Scott Seligman
  56  * @since 1.5
  57  */
  58 
  59 public interface Filer {
  60 
  61     /**
  62      * Creates a new source file and returns a writer for it.
  63      * The file's name and path (relative to the root of all newly created
  64      * source files) is based on the type to be declared in that file.
  65      * If more than one type is being declared, the name of the principal
  66      * top-level type (the public one, for example) should be used.
  67      *
  68      * <p> The {@linkplain java.nio.charset.Charset charset} used to
  69      * encode the file is determined by the implementation.
  70      * An annotation processing tool may have an <tt>-encoding</tt>
  71      * flag or the like for specifying this.  It will typically use
  72      * the platform's default encoding if none is specified.
  73      *
  74      * @param name  canonical (fully qualified) name of the principal type
  75      *          being declared in this file
  76      * @return a writer for the new file
  77      * @throws IOException if the file cannot be created
  78      */
  79     PrintWriter createSourceFile(String name) throws IOException;
  80 
  81     /**
  82      * Creates a new class file, and returns a stream for writing to it.
  83      * The file's name and path (relative to the root of all newly created
  84      * class files) is based on the name of the type being written.
  85      *
  86      * @param name canonical (fully qualified) name of the type being written
  87      * @return a stream for writing to the new file
  88      * @throws IOException if the file cannot be created
  89      */
  90     OutputStream createClassFile(String name) throws IOException;
  91 
  92     /**
  93      * Creates a new text file, and returns a writer for it.
  94      * The file is located along with either the
  95      * newly created source or newly created binary files.  It may be
  96      * named relative to some package (as are source and binary files),
  97      * and from there by an arbitrary pathname.  In a loose sense, the
  98      * pathname of the new file will be the concatenation of
  99      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
 100      *
 101      * <p> A {@linkplain java.nio.charset.Charset charset} for
 102      * encoding the file may be provided.  If none is given, the
 103      * charset used to encode source files
 104      * (see {@link #createSourceFile(String)}) will be used.
 105      *
 106      * @param loc location of the new file
 107      * @param pkg package relative to which the file should be named,
 108      *          or the empty string if none
 109      * @param relPath final pathname components of the file
 110      * @param charsetName the name of the charset to use, or null if none
 111      *          is being explicitly specified
 112      * @return a writer for the new file
 113      * @throws IOException if the file cannot be created
 114      */
 115     PrintWriter createTextFile(Location loc,
 116                                String pkg,
 117                                File relPath,
 118                                String charsetName) throws IOException;
 119 
 120     /**
 121      * Creates a new binary file, and returns a stream for writing to it.
 122      * The file is located along with either the
 123      * newly created source or newly created binary files.  It may be
 124      * named relative to some package (as are source and binary files),
 125      * and from there by an arbitrary pathname.  In a loose sense, the
 126      * pathname of the new file will be the concatenation of
 127      * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
 128      *
 129      * @param loc location of the new file
 130      * @param pkg package relative to which the file should be named,
 131      *          or the empty string if none
 132      * @param relPath final pathname components of the file
 133      * @return a stream for writing to the new file
 134      * @throws IOException if the file cannot be created
 135      */
 136     OutputStream createBinaryFile(Location loc,
 137                                   String pkg,
 138                                   File relPath) throws IOException;
 139 
 140 
 141     /**
 142      * Locations (subtrees within the file system) where new files are created.
 143      */
 144     enum Location {
 145         /** The location of new source files. */
 146         SOURCE_TREE,
 147         /** The location of new class files. */
 148         CLASS_TREE
 149     }
 150 }