001: /*
002: * @(#)Filer.java 1.1 04/01/26
003: *
004: * Copyright (c) 2004, Sun Microsystems, Inc.
005: * All rights reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions are met:
009: *
010: * * Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: * * Redistributions in binary form must reproduce the above copyright
013: * notice, this list of conditions and the following disclaimer in the
014: * documentation and/or other materials provided with the distribution.
015: * * Neither the name of the Sun Microsystems, Inc. nor the names of
016: * its contributors may be used to endorse or promote products derived from
017: * this software without specific prior written permission.
018: *
019: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
020: * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
021: * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
022: * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
023: * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
024: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
025: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
026: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
027: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
028: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
029: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030: */
031:
032: package com.sun.mirror.apt;
033:
034: import java.io.*;
035:
036: /**
037: * This interface supports the creation of new files by an
038: * annotation processor.
039: * Files created in this way will be known to the annotation processing
040: * tool implementing this interface, better enabling the tool to manage them.
041: * Four kinds of files are distinguished:
042: * source files, class files, other text files, and other binary files.
043: * The latter two are collectively referred to as <i>auxiliary</i> files.
044: *
045: * <p> There are two distinguished locations (subtrees within the
046: * file system) where newly created files are placed:
047: * one for new source files, and one for new class files.
048: * (These might be specified on a tool's command line, for example,
049: * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
050: * Auxiliary files may be created in either location.
051: *
052: * <p> During each run of an annotation processing tool, a file
053: * with a given pathname may be created only once. If that file already
054: * exists before the first attempt to create it, the old contents will
055: * be deleted. Any subsequent attempt to create the same file during
056: * a run will fail.
057: *
058: * @author Joseph D. Darcy
059: * @author Scott Seligman
060: * @version 1.1 04/01/26
061: * @since 1.5
062: */
063:
064: public interface Filer {
065:
066: /**
067: * Creates a new source file and returns a writer for it.
068: * The file's name and path (relative to the root of all newly created
069: * source files) is based on the type to be declared in that file.
070: * If more than one type is being declared, the name of the principal
071: * top-level type (the public one, for example) should be used.
072: *
073: * <p> The {@linkplain java.nio.charset.Charset charset} used to
074: * encode the file is determined by the implementation.
075: * An annotation processing tool may have an <tt>-encoding</tt>
076: * flag or the like for specifying this. It will typically use
077: * the platform's default encoding if none is specified.
078: *
079: * @param name canonical (fully qualified) name of the principal type
080: * being declared in this file
081: * @return a writer for the new file
082: * @throws IOException if the file cannot be created
083: */
084: PrintWriter createSourceFile(String name) throws IOException;
085:
086: /**
087: * Creates a new class file, and returns a stream for writing to it.
088: * The file's name and path (relative to the root of all newly created
089: * class files) is based on the name of the type being written.
090: *
091: * @param name canonical (fully qualified) name of the type being written
092: * @return a stream for writing to the new file
093: * @throws IOException if the file cannot be created
094: */
095: OutputStream createClassFile(String name) throws IOException;
096:
097: /**
098: * Creates a new text file, and returns a writer for it.
099: * The file is located along with either the
100: * newly created source or newly created binary files. It may be
101: * named relative to some package (as are source and binary files),
102: * and from there by an arbitrary pathname. In a loose sense, the
103: * pathname of the new file will be the concatenation of
104: * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
105: *
106: * <p> A {@linkplain java.nio.charset.Charset charset} for
107: * encoding the file may be provided. If none is given, the
108: * charset used to encode source files
109: * (see {@link #createSourceFile(String)}) will be used.
110: *
111: * @param loc location of the new file
112: * @param pkg package relative to which the file should be named,
113: * or the empty string if none
114: * @param relPath final pathname components of the file
115: * @param charsetName the name of the charset to use, or null if none
116: * is being explicitly specified
117: * @return a writer for the new file
118: * @throws IOException if the file cannot be created
119: */
120: PrintWriter createTextFile(Location loc, String pkg, File relPath,
121: String charsetName) throws IOException;
122:
123: /**
124: * Creates a new binary file, and returns a stream for writing to it.
125: * The file is located along with either the
126: * newly created source or newly created binary files. It may be
127: * named relative to some package (as are source and binary files),
128: * and from there by an arbitrary pathname. In a loose sense, the
129: * pathname of the new file will be the concatenation of
130: * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
131: *
132: * @param loc location of the new file
133: * @param pkg package relative to which the file should be named,
134: * or the empty string if none
135: * @param relPath final pathname components of the file
136: * @return a stream for writing to the new file
137: * @throws IOException if the file cannot be created
138: */
139: OutputStream createBinaryFile(Location loc, String pkg, File relPath)
140: throws IOException;
141:
142: /**
143: * Locations (subtrees within the file system) where new files are created.
144: */
145: enum Location {
146: /** The location of new source files. */
147: SOURCE_TREE,
148: /** The location of new class files. */
149: CLASS_TREE
150: }
151: }
|