1/* 2 * Copyright (c) 1998, 2017, 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 26package jdk.javadoc.internal.doclets.toolkit.util; 27 28import java.io.BufferedReader; 29import java.io.IOException; 30import java.io.InputStream; 31import java.io.InputStreamReader; 32import java.io.OutputStream; 33import java.io.UnsupportedEncodingException; 34import java.io.Writer; 35 36import javax.tools.JavaFileManager.Location; 37import javax.tools.StandardLocation; 38 39import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration; 40 41/** 42 * Abstraction for handling files, which may be specified directly 43 * (e.g. via a path on the command line) or relative to a Location. 44 * 45 * <p><b>This is NOT part of any supported API. 46 * If you write code that depends on this, you do so at your own risk. 47 * This code and its internal interfaces are subject to change or 48 * deletion without notice.</b> 49 * 50 */ 51public abstract class DocFile { 52 53 /** Create a DocFile for a directory. */ 54 public static DocFile createFileForDirectory(BaseConfiguration configuration, String file) { 55 return DocFileFactory.getFactory(configuration).createFileForDirectory(file); 56 } 57 58 /** Create a DocFile for a file that will be opened for reading. */ 59 public static DocFile createFileForInput(BaseConfiguration configuration, String file) { 60 return DocFileFactory.getFactory(configuration).createFileForInput(file); 61 } 62 63 /** Create a DocFile for a file that will be opened for writing. */ 64 public static DocFile createFileForOutput(BaseConfiguration configuration, DocPath path) { 65 return DocFileFactory.getFactory(configuration).createFileForOutput(path); 66 } 67 68 /** 69 * The location for this file. Maybe null if the file was created without 70 * a location or path. 71 */ 72 protected final Location location; 73 74 /** 75 * The path relative to the (output) location. Maybe null if the file was 76 * created without a location or path. 77 */ 78 protected final DocPath path; 79 80 /** 81 * List the directories and files found in subdirectories along the 82 * elements of the given location. 83 * @param configuration the doclet configuration 84 * @param location currently, only {@link StandardLocation#SOURCE_PATH} is supported. 85 * @param path the subdirectory of the directories of the location for which to 86 * list files 87 */ 88 public static Iterable<DocFile> list(BaseConfiguration configuration, Location location, DocPath path) { 89 return DocFileFactory.getFactory(configuration).list(location, path); 90 } 91 92 /** Create a DocFile without a location or path */ 93 protected DocFile() { 94 this.location = null; 95 this.path = null; 96 } 97 98 /** Create a DocFile for a given location and relative path. */ 99 protected DocFile(Location location, DocPath path) { 100 this.location = location; 101 this.path = path; 102 } 103 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; 111 112 /** 113 * Open an output stream for the file. 114 * The file must have been created with a location of 115 * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} 116 * and a corresponding relative path. 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 121 */ 122 public abstract OutputStream openOutputStream() throws DocFileIOException, UnsupportedEncodingException; 123 124 /** 125 * Open an writer for the file, using the encoding (if any) given in the 126 * doclet configuration. 127 * The file must have been created with a location of 128 * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path. 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 133 */ 134 public abstract Writer openWriter() throws DocFileIOException, UnsupportedEncodingException; 135 136 /** 137 * Copy the contents of another file directly to this file. 138 * 139 * @param fromFile the file to be copied 140 * @throws DocFileIOException if there is a problem file copying the file 141 */ 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); 152 } 153 } catch (IOException e) { 154 throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); 155 } 156 } 157 158 /** 159 * Copy the contents of a resource file to this file. 160 * 161 * @param resource the path of the resource, relative to the package of this class 162 * @param overwrite whether or not to overwrite the file if it already exists 163 * @param replaceNewLine if false, the file is copied as a binary file; 164 * if true, the file is written line by line, using the platform line 165 * separator 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 169 */ 170 public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) 171 throws DocFileIOException, ResourceIOException { 172 if (exists() && !overwrite) 173 return; 174 175 try { 176 InputStream in = BaseConfiguration.class.getResourceAsStream(resource.getPath()); 177 if (in == null) 178 return; 179 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 } 193 } else { 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); 199 } 200 } catch (IOException e) { 201 throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); 202 } 203 } 204 } finally { 205 in.close(); 206 } 207 } catch (IOException e) { 208 throw new ResourceIOException(resource, e); 209 } 210 } 211 212 /** Return true if the file can be read. */ 213 public abstract boolean canRead(); 214 215 /** Return true if the file can be written. */ 216 public abstract boolean canWrite(); 217 218 /** Return true if the file exists. */ 219 public abstract boolean exists(); 220 221 /** Return the base name (last component) of the file name. */ 222 public abstract String getName(); 223 224 /** Return the file system path for this file. */ 225 public abstract String getPath(); 226 227 /** Return true if file has an absolute path name. */ 228 public abstract boolean isAbsolute(); 229 230 /** Return true if file identifies a directory. */ 231 public abstract boolean isDirectory(); 232 233 /** Return true if file identifies a file. */ 234 public abstract boolean isFile(); 235 236 /** Return true if this file is the same as another. */ 237 public abstract boolean isSameFile(DocFile other); 238 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; 245 246 /** Create the file as a directory, including any parent directories. */ 247 public abstract boolean mkdirs(); 248 249 /** 250 * Derive a new file by resolving a relative path against this file. 251 * The new file will inherit the configuration and location of this file 252 * If this file has a path set, the new file will have a corresponding 253 * new path. 254 */ 255 public abstract DocFile resolve(DocPath p); 256 257 /** 258 * Derive a new file by resolving a relative path against this file. 259 * The new file will inherit the configuration and location of this file 260 * If this file has a path set, the new file will have a corresponding 261 * new path. 262 */ 263 public abstract DocFile resolve(String p); 264 265 /** 266 * Resolve a relative file against the given output location. 267 * @param locn Currently, only 268 * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported. 269 */ 270 public abstract DocFile resolveAgainst(Location locn); 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 } 359} 360