author | ksrini |
Mon, 05 Jun 2017 13:45:34 -0700 | |
changeset 45417 | f7479ee8de69 |
parent 40587 | 1c355ea550ed |
permissions | -rw-r--r-- |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
1 |
/* |
45417 | 2 |
* Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
4 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
7 |
* published by the Free Software Foundation. Oracle designates this |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
9 |
* by Oracle in the LICENSE file that accompanied this code. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
10 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
15 |
* accompanied this code). |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
16 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
20 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
22 |
* or visit www.oracle.com if you need additional information or have any |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
23 |
* questions. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
24 |
*/ |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
25 |
|
35426
374342e56a56
8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
25874
diff
changeset
|
26 |
package jdk.javadoc.internal.doclets.toolkit.util; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
27 |
|
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
28 |
import java.io.BufferedReader; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
29 |
import java.io.IOException; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
30 |
import java.io.InputStream; |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
31 |
import java.io.InputStreamReader; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
32 |
import java.io.OutputStream; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
33 |
import java.io.UnsupportedEncodingException; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
34 |
import java.io.Writer; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
35 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
36 |
import javax.tools.JavaFileManager.Location; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
37 |
import javax.tools.StandardLocation; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
38 |
|
45417 | 39 |
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
40 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
41 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
42 |
* Abstraction for handling files, which may be specified directly |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
43 |
* (e.g. via a path on the command line) or relative to a Location. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
44 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
45 |
* <p><b>This is NOT part of any supported API. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
46 |
* If you write code that depends on this, you do so at your own risk. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
47 |
* This code and its internal interfaces are subject to change or |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
48 |
* deletion without notice.</b> |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
49 |
* |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
50 |
*/ |
14544 | 51 |
public abstract class DocFile { |
52 |
||
53 |
/** Create a DocFile for a directory. */ |
|
45417 | 54 |
public static DocFile createFileForDirectory(BaseConfiguration configuration, String file) { |
14544 | 55 |
return DocFileFactory.getFactory(configuration).createFileForDirectory(file); |
56 |
} |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
57 |
|
14544 | 58 |
/** Create a DocFile for a file that will be opened for reading. */ |
45417 | 59 |
public static DocFile createFileForInput(BaseConfiguration configuration, String file) { |
14544 | 60 |
return DocFileFactory.getFactory(configuration).createFileForInput(file); |
61 |
} |
|
62 |
||
63 |
/** Create a DocFile for a file that will be opened for writing. */ |
|
45417 | 64 |
public static DocFile createFileForOutput(BaseConfiguration configuration, DocPath path) { |
14544 | 65 |
return DocFileFactory.getFactory(configuration).createFileForOutput(path); |
66 |
} |
|
67 |
||
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
68 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
69 |
* The location for this file. Maybe null if the file was created without |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
70 |
* a location or path. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
71 |
*/ |
14544 | 72 |
protected final Location location; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
73 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
74 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
75 |
* The path relative to the (output) location. Maybe null if the file was |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
76 |
* created without a location or path. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
77 |
*/ |
14544 | 78 |
protected final DocPath path; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
79 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
80 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
81 |
* List the directories and files found in subdirectories along the |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
82 |
* elements of the given location. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
83 |
* @param configuration the doclet configuration |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
84 |
* @param location currently, only {@link StandardLocation#SOURCE_PATH} is supported. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
85 |
* @param path the subdirectory of the directories of the location for which to |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
86 |
* list files |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
87 |
*/ |
45417 | 88 |
public static Iterable<DocFile> list(BaseConfiguration configuration, Location location, DocPath path) { |
14544 | 89 |
return DocFileFactory.getFactory(configuration).list(location, path); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
90 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
91 |
|
14544 | 92 |
/** Create a DocFile without a location or path */ |
40587 | 93 |
protected DocFile() { |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
94 |
this.location = null; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
95 |
this.path = null; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
96 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
97 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
98 |
/** Create a DocFile for a given location and relative path. */ |
40587 | 99 |
protected DocFile(Location location, DocPath path) { |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
100 |
this.location = location; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
101 |
this.path = path; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
102 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
103 |
|
40587 | 104 |
/** |
105 |
* Open an input stream for the file. |
|
106 |
* |
|
107 |
* @return an open input stream for the file |
|
108 |
* @throws DocFileIOException if there is a problem opening the stream |
|
109 |
*/ |
|
110 |
public abstract InputStream openInputStream() throws DocFileIOException; |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
111 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
112 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
113 |
* Open an output stream for the file. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
114 |
* The file must have been created with a location of |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
115 |
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
116 |
* and a corresponding relative path. |
40587 | 117 |
* |
118 |
* @return an open output stream for the file |
|
119 |
* @throws DocFileIOException if there is a problem opening the stream |
|
120 |
* @throws UnsupportedEncodingException if the configured encoding is not supported |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
121 |
*/ |
40587 | 122 |
public abstract OutputStream openOutputStream() throws DocFileIOException, UnsupportedEncodingException; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
123 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
124 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
125 |
* Open an writer for the file, using the encoding (if any) given in the |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
126 |
* doclet configuration. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
127 |
* The file must have been created with a location of |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
128 |
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path. |
40587 | 129 |
* |
130 |
* @return an open output stream for the file |
|
131 |
* @throws DocFileIOException if there is a problem opening the stream |
|
132 |
* @throws UnsupportedEncodingException if the configured encoding is not supported |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
133 |
*/ |
40587 | 134 |
public abstract Writer openWriter() throws DocFileIOException, UnsupportedEncodingException; |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
135 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
136 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
137 |
* Copy the contents of another file directly to this file. |
40587 | 138 |
* |
139 |
* @param fromFile the file to be copied |
|
140 |
* @throws DocFileIOException if there is a problem file copying the file |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
141 |
*/ |
40587 | 142 |
public void copyFile(DocFile fromFile) throws DocFileIOException { |
143 |
try (OutputStream output = openOutputStream()) { |
|
144 |
try (InputStream input = fromFile.openInputStream()) { |
|
145 |
byte[] bytearr = new byte[1024]; |
|
146 |
int len; |
|
147 |
while ((len = read(fromFile, input, bytearr)) != -1) { |
|
148 |
write(this, output, bytearr, len); |
|
149 |
} |
|
150 |
} catch (IOException e) { |
|
151 |
throw new DocFileIOException(fromFile, DocFileIOException.Mode.READ, e); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
152 |
} |
40587 | 153 |
} catch (IOException e) { |
154 |
throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
155 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
156 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
157 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
158 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
159 |
* Copy the contents of a resource file to this file. |
40587 | 160 |
* |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
161 |
* @param resource the path of the resource, relative to the package of this class |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
162 |
* @param overwrite whether or not to overwrite the file if it already exists |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
163 |
* @param replaceNewLine if false, the file is copied as a binary file; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
164 |
* if true, the file is written line by line, using the platform line |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
165 |
* separator |
40587 | 166 |
* |
167 |
* @throws DocFileIOException if there is a problem while writing the copy |
|
168 |
* @throws ResourceIOException if there is a problem while reading the resource |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
169 |
*/ |
40587 | 170 |
public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) |
171 |
throws DocFileIOException, ResourceIOException { |
|
14544 | 172 |
if (exists() && !overwrite) |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
173 |
return; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
174 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
175 |
try { |
45417 | 176 |
InputStream in = BaseConfiguration.class.getResourceAsStream(resource.getPath()); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
177 |
if (in == null) |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
178 |
return; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
179 |
|
40587 | 180 |
try { |
181 |
if (replaceNewLine) { |
|
182 |
try (BufferedReader reader = new BufferedReader(new InputStreamReader(in))) { |
|
183 |
try (Writer writer = openWriter()) { |
|
184 |
String line; |
|
185 |
while ((line = readResourceLine(resource, reader)) != null) { |
|
186 |
write(this, writer, line); |
|
187 |
write(this, writer, DocletConstants.NL); |
|
188 |
} |
|
189 |
} catch (IOException e) { |
|
190 |
throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); |
|
191 |
} |
|
192 |
} |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
193 |
} else { |
40587 | 194 |
try (OutputStream out = openOutputStream()) { |
195 |
byte[] buf = new byte[2048]; |
|
196 |
int n; |
|
197 |
while ((n = readResource(resource, in, buf)) > 0) { |
|
198 |
write(this, out, buf, n); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
199 |
} |
40587 | 200 |
} catch (IOException e) { |
201 |
throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
202 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
203 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
204 |
} finally { |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
205 |
in.close(); |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
206 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
207 |
} catch (IOException e) { |
40587 | 208 |
throw new ResourceIOException(resource, e); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
209 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
210 |
} |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
211 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
212 |
/** Return true if the file can be read. */ |
14544 | 213 |
public abstract boolean canRead(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
214 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
215 |
/** Return true if the file can be written. */ |
14544 | 216 |
public abstract boolean canWrite(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
217 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
218 |
/** Return true if the file exists. */ |
14544 | 219 |
public abstract boolean exists(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
220 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
221 |
/** Return the base name (last component) of the file name. */ |
14544 | 222 |
public abstract String getName(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
223 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
224 |
/** Return the file system path for this file. */ |
14544 | 225 |
public abstract String getPath(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
226 |
|
14544 | 227 |
/** Return true if file has an absolute path name. */ |
228 |
public abstract boolean isAbsolute(); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
229 |
|
14544 | 230 |
/** Return true if file identifies a directory. */ |
231 |
public abstract boolean isDirectory(); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
232 |
|
14544 | 233 |
/** Return true if file identifies a file. */ |
234 |
public abstract boolean isFile(); |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
235 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
236 |
/** Return true if this file is the same as another. */ |
14544 | 237 |
public abstract boolean isSameFile(DocFile other); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
238 |
|
40587 | 239 |
/** If the file is a directory, list its contents. |
240 |
* |
|
241 |
* @return the contents of the directory |
|
242 |
* @throws DocFileIOException if there is a problem while listing the directory |
|
243 |
*/ |
|
244 |
public abstract Iterable<DocFile> list() throws DocFileIOException; |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
245 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
246 |
/** Create the file as a directory, including any parent directories. */ |
14544 | 247 |
public abstract boolean mkdirs(); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
248 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
249 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
250 |
* Derive a new file by resolving a relative path against this file. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
251 |
* The new file will inherit the configuration and location of this file |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
252 |
* If this file has a path set, the new file will have a corresponding |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
253 |
* new path. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
254 |
*/ |
14544 | 255 |
public abstract DocFile resolve(DocPath p); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
256 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
257 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
258 |
* Derive a new file by resolving a relative path against this file. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
259 |
* The new file will inherit the configuration and location of this file |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
260 |
* If this file has a path set, the new file will have a corresponding |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
261 |
* new path. |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
262 |
*/ |
14544 | 263 |
public abstract DocFile resolve(String p); |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
264 |
|
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
265 |
/** |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
266 |
* Resolve a relative file against the given output location. |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
267 |
* @param locn Currently, only |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
268 |
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported. |
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
269 |
*/ |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14544
diff
changeset
|
270 |
public abstract DocFile resolveAgainst(Location locn); |
40587 | 271 |
|
272 |
||
273 |
/** |
|
274 |
* Reads from an input stream opened from a given file into a given buffer. |
|
275 |
* If an IOException occurs, it is wrapped in a DocFileIOException. |
|
276 |
* |
|
277 |
* @param inFile the file for the stream |
|
278 |
* @param input the stream |
|
279 |
* @param buf the buffer |
|
280 |
* @return the number of bytes read, or -1 if at end of file |
|
281 |
* @throws DocFileIOException if an exception occurred while reading the stream |
|
282 |
*/ |
|
283 |
private static int read(DocFile inFile, InputStream input, byte[] buf) throws DocFileIOException { |
|
284 |
try { |
|
285 |
return input.read(buf); |
|
286 |
} catch (IOException e) { |
|
287 |
throw new DocFileIOException(inFile, DocFileIOException.Mode.READ, e); |
|
288 |
} |
|
289 |
} |
|
290 |
||
291 |
/** |
|
292 |
* Writes to an output stream for a given file from a given buffer. |
|
293 |
* If an IOException occurs, it is wrapped in a DocFileIOException. |
|
294 |
* |
|
295 |
* @param outFile the file for the stream |
|
296 |
* @param out the stream |
|
297 |
* @param buf the buffer |
|
298 |
* @throws DocFileIOException if an exception occurred while writing the stream |
|
299 |
*/ |
|
300 |
private static void write(DocFile outFile, OutputStream out, byte[] buf, int len) throws DocFileIOException { |
|
301 |
try { |
|
302 |
out.write(buf, 0, len); |
|
303 |
} catch (IOException e) { |
|
304 |
throw new DocFileIOException(outFile, DocFileIOException.Mode.WRITE, e); |
|
305 |
} |
|
306 |
} |
|
307 |
||
308 |
/** |
|
309 |
* Writes text to an output stream for a given file from a given buffer. |
|
310 |
* If an IOException occurs, it is wrapped in a DocFileIOException. |
|
311 |
* |
|
312 |
* @param outFile the file for the stream |
|
313 |
* @param out the stream |
|
314 |
* @param text the text to be written |
|
315 |
* @throws DocFileIOException if an exception occurred while writing the stream |
|
316 |
*/ |
|
317 |
private static void write(DocFile outFile, Writer out, String text) throws DocFileIOException { |
|
318 |
try { |
|
319 |
out.write(text); |
|
320 |
} catch (IOException e) { |
|
321 |
throw new DocFileIOException(outFile, DocFileIOException.Mode.WRITE, e); |
|
322 |
} |
|
323 |
} |
|
324 |
||
325 |
/** |
|
326 |
* Reads from an input stream opened from a given resource into a given buffer. |
|
327 |
* If an IOException occurs, it is wrapped in a ResourceIOException. |
|
328 |
* |
|
329 |
* @param resource the resource for the stream |
|
330 |
* @param in the stream |
|
331 |
* @param buf the buffer |
|
332 |
* @return the number of bytes read, or -1 if at end of file |
|
333 |
* @throws ResourceIOException if an exception occurred while reading the stream |
|
334 |
*/ |
|
335 |
private static int readResource(DocPath resource, InputStream in, byte[] buf) throws ResourceIOException { |
|
336 |
try { |
|
337 |
return in.read(buf); |
|
338 |
} catch (IOException e) { |
|
339 |
throw new ResourceIOException(resource, e); |
|
340 |
} |
|
341 |
} |
|
342 |
||
343 |
/** |
|
344 |
* Reads a line of characters from an input stream opened from a given resource. |
|
345 |
* If an IOException occurs, it is wrapped in a ResourceIOException. |
|
346 |
* |
|
347 |
* @param resource the resource for the stream |
|
348 |
* @param in the stream |
|
349 |
* @return the line of text, or {@code null} if at end of stream |
|
350 |
* @throws ResourceIOException if an exception occurred while reading the stream |
|
351 |
*/ |
|
352 |
private static String readResourceLine(DocPath docPath, BufferedReader in) throws ResourceIOException { |
|
353 |
try { |
|
354 |
return in.readLine(); |
|
355 |
} catch (IOException e) { |
|
356 |
throw new ResourceIOException(docPath, e); |
|
357 |
} |
|
358 |
} |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
diff
changeset
|
359 |
} |