Thu, 15 Nov 2012 19:54:20 -0800
8002079: update DocFile to use a JavaFileManager
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1998, 2012, 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 */
26 package com.sun.tools.doclets.internal.toolkit.util;
28 import java.io.FileNotFoundException;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.io.OutputStream;
32 import java.io.UnsupportedEncodingException;
33 import java.io.Writer;
35 import javax.tools.JavaFileManager.Location;
36 import javax.tools.StandardLocation;
38 import com.sun.tools.doclets.internal.toolkit.Configuration;
39 import java.io.BufferedReader;
40 import java.io.BufferedWriter;
41 import java.io.InputStreamReader;
42 import java.io.OutputStreamWriter;
44 /**
45 * Abstraction for handling files, which may be specified directly
46 * (e.g. via a path on the command line) or relative to a Location.
47 *
48 * <p><b>This is NOT part of any supported API.
49 * If you write code that depends on this, you do so at your own risk.
50 * This code and its internal interfaces are subject to change or
51 * deletion without notice.</b>
52 *
53 * @since 8
54 */
55 public abstract class DocFile {
57 /** Create a DocFile for a directory. */
58 public static DocFile createFileForDirectory(Configuration configuration, String file) {
59 return DocFileFactory.getFactory(configuration).createFileForDirectory(file);
60 }
62 /** Create a DocFile for a file that will be opened for reading. */
63 public static DocFile createFileForInput(Configuration configuration, String file) {
64 return DocFileFactory.getFactory(configuration).createFileForInput(file);
65 }
67 /** Create a DocFile for a file that will be opened for writing. */
68 public static DocFile createFileForOutput(Configuration configuration, DocPath path) {
69 return DocFileFactory.getFactory(configuration).createFileForOutput(path);
70 }
72 private final Configuration configuration;
74 /**
75 * The location for this file. Maybe null if the file was created without
76 * a location or path.
77 */
78 protected final Location location;
80 /**
81 * The path relative to the (output) location. Maybe null if the file was
82 * created without a location or path.
83 */
84 protected final DocPath path;
86 /**
87 * List the directories and files found in subdirectories along the
88 * elements of the given location.
89 * @param configuration the doclet configuration
90 * @param location currently, only {@link StandardLocation#SOURCE_PATH} is supported.
91 * @param path the subdirectory of the directories of the location for which to
92 * list files
93 */
94 public static Iterable<DocFile> list(Configuration configuration, Location location, DocPath path) {
95 return DocFileFactory.getFactory(configuration).list(location, path);
96 }
98 /** Create a DocFile without a location or path */
99 protected DocFile(Configuration configuration) {
100 this.configuration = configuration;
101 this.location = null;
102 this.path = null;
103 }
105 /** Create a DocFile for a given location and relative path. */
106 protected DocFile(Configuration configuration, Location location, DocPath path) {
107 this.configuration = configuration;
108 this.location = location;
109 this.path = path;
110 }
112 /** Open an input stream for the file. */
113 public abstract InputStream openInputStream() throws IOException;
115 /**
116 * Open an output stream for the file.
117 * The file must have been created with a location of
118 * {@link StandardLocation#CLASS_OUTPUT} and a corresponding relative path.
119 */
120 public abstract OutputStream openOutputStream() throws IOException, UnsupportedEncodingException;
122 /**
123 * Open an writer for the file, using the encoding (if any) given in the
124 * doclet configuration.
125 * The file must have been created with a location of
126 * {@link StandardLocation#CLASS_OUTPUT} and a corresponding relative path.
127 */
128 public abstract Writer openWriter() throws IOException, UnsupportedEncodingException;
130 /**
131 * Copy the contents of another file directly to this file.
132 */
133 public void copyFile(DocFile fromFile) throws IOException {
134 InputStream input = fromFile.openInputStream();
135 OutputStream output = openOutputStream();
136 try {
137 byte[] bytearr = new byte[1024];
138 int len;
139 while ((len = input.read(bytearr)) != -1) {
140 output.write(bytearr, 0, len);
141 }
142 } catch (FileNotFoundException exc) {
143 } catch (SecurityException exc) {
144 } finally {
145 input.close();
146 output.close();
147 }
148 }
150 /**
151 * Copy the contents of a resource file to this file.
152 * @param resource the path of the resource, relative to the package of this class
153 * @param overwrite whether or not to overwrite the file if it already exists
154 * @param replaceNewLine if false, the file is copied as a binary file;
155 * if true, the file is written line by line, using the platform line
156 * separator
157 */
158 public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) {
159 if (exists() && !overwrite)
160 return;
162 try {
163 InputStream in = Configuration.class.getResourceAsStream(resource.getPath());
164 if (in == null)
165 return;
167 OutputStream out = openOutputStream();
168 try {
169 if (!replaceNewLine) {
170 byte[] buf = new byte[2048];
171 int n;
172 while((n = in.read(buf))>0) out.write(buf,0,n);
173 } else {
174 BufferedReader reader = new BufferedReader(new InputStreamReader(in));
175 BufferedWriter writer;
176 if (configuration.docencoding == null) {
177 writer = new BufferedWriter(new OutputStreamWriter(out));
178 } else {
179 writer = new BufferedWriter(new OutputStreamWriter(out,
180 configuration.docencoding));
181 }
182 try {
183 String line;
184 while ((line = reader.readLine()) != null) {
185 writer.write(line);
186 writer.write(DocletConstants.NL);
187 }
188 } finally {
189 reader.close();
190 writer.close();
191 }
192 }
193 } finally {
194 in.close();
195 out.close();
196 }
197 } catch (IOException e) {
198 e.printStackTrace(System.err);
199 throw new DocletAbortException();
200 }
201 }
203 /** Return true if the file can be read. */
204 public abstract boolean canRead();
206 /** Return true if the file can be written. */
207 public abstract boolean canWrite();
209 /** Return true if the file exists. */
210 public abstract boolean exists();
212 /** Return the base name (last component) of the file name. */
213 public abstract String getName();
215 /** Return the file system path for this file. */
216 public abstract String getPath();
218 /** Return true if file has an absolute path name. */
219 public abstract boolean isAbsolute();
221 /** Return true if file identifies a directory. */
222 public abstract boolean isDirectory();
224 /** Return true if file identifies a file. */
225 public abstract boolean isFile();
227 /** Return true if this file is the same as another. */
228 public abstract boolean isSameFile(DocFile other);
230 /** If the file is a directory, list its contents. */
231 public abstract Iterable<DocFile> list() throws IOException;
233 /** Create the file as a directory, including any parent directories. */
234 public abstract boolean mkdirs();
236 /**
237 * Derive a new file by resolving a relative path against this file.
238 * The new file will inherit the configuration and location of this file
239 * If this file has a path set, the new file will have a corresponding
240 * new path.
241 */
242 public abstract DocFile resolve(DocPath p);
244 /**
245 * Derive a new file by resolving a relative path against this file.
246 * The new file will inherit the configuration and location of this file
247 * If this file has a path set, the new file will have a corresponding
248 * new path.
249 */
250 public abstract DocFile resolve(String p);
252 /**
253 * Resolve a relative file against the given output location.
254 * @param locn Currently, only SOURCE_OUTPUT is supported.
255 */
256 public abstract DocFile resolveAgainst(StandardLocation locn);
257 }