001 /*
002 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package com.sun.mirror.apt;
027
028
029 import java.io.*;
030
031
032 /**
033 * This interface supports the creation of new files by an
034 * annotation processor.
035 * Files created in this way will be known to the annotation processing
036 * tool implementing this interface, better enabling the tool to manage them.
037 * Four kinds of files are distinguished:
038 * source files, class files, other text files, and other binary files.
039 * The latter two are collectively referred to as <i>auxiliary</i> files.
040 *
041 * <p> There are two distinguished locations (subtrees within the
042 * file system) where newly created files are placed:
043 * one for new source files, and one for new class files.
044 * (These might be specified on a tool's command line, for example,
045 * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
046 * Auxiliary files may be created in either location.
047 *
048 * <p> During each run of an annotation processing tool, a file
049 * with a given pathname may be created only once. If that file already
050 * exists before the first attempt to create it, the old contents will
051 * be deleted. Any subsequent attempt to create the same file during
052 * a run will fail.
053 *
054 * @author Joseph D. Darcy
055 * @author Scott Seligman
056 * @since 1.5
057 */
058
059 public interface Filer {
060
061 /**
062 * Creates a new source file and returns a writer for it.
063 * The file's name and path (relative to the root of all newly created
064 * source files) is based on the type to be declared in that file.
065 * If more than one type is being declared, the name of the principal
066 * top-level type (the public one, for example) should be used.
067 *
068 * <p> The {@linkplain java.nio.charset.Charset charset} used to
069 * encode the file is determined by the implementation.
070 * An annotation processing tool may have an <tt>-encoding</tt>
071 * flag or the like for specifying this. It will typically use
072 * the platform's default encoding if none is specified.
073 *
074 * @param name canonical (fully qualified) name of the principal type
075 * being declared in this file
076 * @return a writer for the new file
077 * @throws IOException if the file cannot be created
078 */
079 PrintWriter createSourceFile(String name) throws IOException;
080
081 /**
082 * Creates a new class file, and returns a stream for writing to it.
083 * The file's name and path (relative to the root of all newly created
084 * class files) is based on the name of the type being written.
085 *
086 * @param name canonical (fully qualified) name of the type being written
087 * @return a stream for writing to the new file
088 * @throws IOException if the file cannot be created
089 */
090 OutputStream createClassFile(String name) throws IOException;
091
092 /**
093 * Creates a new text file, and returns a writer for it.
094 * The file is located along with either the
095 * newly created source or newly created binary files. It may be
096 * named relative to some package (as are source and binary files),
097 * and from there by an arbitrary pathname. In a loose sense, the
098 * pathname of the new file will be the concatenation of
099 * <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 }