1 /*
2 * Copyright (c) 2004, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 }