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: import java.io.*;
029:
030: /**
031: * This interface supports the creation of new files by an
032: * annotation processor.
033: * Files created in this way will be known to the annotation processing
034: * tool implementing this interface, better enabling the tool to manage them.
035: * Four kinds of files are distinguished:
036: * source files, class files, other text files, and other binary files.
037: * The latter two are collectively referred to as <i>auxiliary</i> files.
038: *
039: * <p> There are two distinguished locations (subtrees within the
040: * file system) where newly created files are placed:
041: * one for new source files, and one for new class files.
042: * (These might be specified on a tool's command line, for example,
043: * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
044: * Auxiliary files may be created in either location.
045: *
046: * <p> During each run of an annotation processing tool, a file
047: * with a given pathname may be created only once. If that file already
048: * exists before the first attempt to create it, the old contents will
049: * be deleted. Any subsequent attempt to create the same file during
050: * a run will fail.
051: *
052: * @author Joseph D. Darcy
053: * @author Scott Seligman
054: * @version 1.8 07/05/05
055: * @since 1.5
056: */
057:
058: public interface Filer {
059:
060: /**
061: * Creates a new source file and returns a writer for it.
062: * The file's name and path (relative to the root of all newly created
063: * source files) is based on the type to be declared in that file.
064: * If more than one type is being declared, the name of the principal
065: * top-level type (the public one, for example) should be used.
066: *
067: * <p> The {@linkplain java.nio.charset.Charset charset} used to
068: * encode the file is determined by the implementation.
069: * An annotation processing tool may have an <tt>-encoding</tt>
070: * flag or the like for specifying this. It will typically use
071: * the platform's default encoding if none is specified.
072: *
073: * @param name canonical (fully qualified) name of the principal type
074: * being declared in this file
075: * @return a writer for the new file
076: * @throws IOException if the file cannot be created
077: */
078: PrintWriter createSourceFile(String name) throws IOException;
079:
080: /**
081: * Creates a new class file, and returns a stream for writing to it.
082: * The file's name and path (relative to the root of all newly created
083: * class files) is based on the name of the type being written.
084: *
085: * @param name canonical (fully qualified) name of the type being written
086: * @return a stream for writing to the new file
087: * @throws IOException if the file cannot be created
088: */
089: OutputStream createClassFile(String name) throws IOException;
090:
091: /**
092: * Creates a new text file, and returns a writer for it.
093: * The file is located along with either the
094: * newly created source or newly created binary files. It may be
095: * named relative to some package (as are source and binary files),
096: * and from there by an arbitrary pathname. In a loose sense, the
097: * pathname of the new file will be the concatenation of
098: * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
099: *
100: * <p> A {@linkplain java.nio.charset.Charset charset} for
101: * encoding the file may be provided. If none is given, the
102: * charset used to encode source files
103: * (see {@link #createSourceFile(String)}) will be used.
104: *
105: * @param loc location of the new file
106: * @param pkg package relative to which the file should be named,
107: * or the empty string if none
108: * @param relPath final pathname components of the file
109: * @param charsetName the name of the charset to use, or null if none
110: * is being explicitly specified
111: * @return a writer for the new file
112: * @throws IOException if the file cannot be created
113: */
114: PrintWriter createTextFile(Location loc, String pkg, File relPath,
115: String charsetName) throws IOException;
116:
117: /**
118: * Creates a new binary file, and returns a stream for writing to it.
119: * The file is located along with either the
120: * newly created source or newly created binary files. It may be
121: * named relative to some package (as are source and binary files),
122: * and from there by an arbitrary pathname. In a loose sense, the
123: * pathname of the new file will be the concatenation of
124: * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
125: *
126: * @param loc location of the new file
127: * @param pkg package relative to which the file should be named,
128: * or the empty string if none
129: * @param relPath final pathname components of the file
130: * @return a stream for writing to the new file
131: * @throws IOException if the file cannot be created
132: */
133: OutputStream createBinaryFile(Location loc, String pkg, File relPath)
134: throws IOException;
135:
136: /**
137: * Locations (subtrees within the file system) where new files are created.
138: */
139: enum Location {
140: /** The location of new source files. */
141: SOURCE_TREE,
142: /** The location of new class files. */
143: CLASS_TREE
144: }
145: }
|