OpenJDK 27 · jdk.javadoc.internal.doclets.toolkit.util.DocFile

Modifier and Type	Field and Description
protected final JavaFileManager.Location	location The location for this file.
protected final DocPath	path The path relative to the (output) location.
public static final String	PLATFORM_LINE_SEPARATOR The line separator for the current platform.
private static final Pattern	replacePtn

Access	Constructor and Description
protected	DocFile() Create a DocFile without a location or path
protected	DocFile(JavaFileManager.Location location, DocPath path) Create a DocFile for a given location and relative path.

Method Summary

Modifier and Type	Method and Description
public abstract boolean	canRead() Return true if the file can be read.
public abstract boolean	canWrite() Return true if the file can be written.
public void	copyFile(DocFile the file to be copied fromFile) Copy the contents of another file directly to this file.
public void	copyResource(DocPath the path of the resource resource, URL the URL of the resource url, boolean if false, the file is copied as a binary file; if true, the file is written line by line, using the platform line separator replaceNewLine) Copy the contents of a resource file to this file.
public void	copyResource(DocPath the path of the resource resource, URL the URL of the resource url, Resources if not `null`, substitute occurrences of `##REPLACE:key##` resources) Copy the contents of a resource file to this file.
public void	copyResource(DocPath the path of the resource resource, URL the URL of the resource url, UnaryOperator<String> the transforming function that is called for each line; may return `null` to remove a line. lineTransformer) Copy the contents of a resource file to this file while transforming and filtering its lines.
private void	copyResource(DocPath resource, URL url, boolean replaceNewLine, UnaryOperator<String> lineTransformer)
public static DocFile	createFileForDirectory(BaseConfiguration configuration, String file) Create a DocFile for a directory.
public static DocFile	createFileForInput(BaseConfiguration configuration, String file) Create a DocFile for a file that will be opened for reading.
public static DocFile	createFileForInput(BaseConfiguration configuration, Path file) Create a DocFile for a file that will be opened for reading.
public static DocFile	createFileForOutput(BaseConfiguration configuration, DocPath path) Create a DocFile for a file that will be opened for writing.
public abstract boolean	exists() Return true if the file exists.
public abstract FileObject	Returns: a file object getFileObject() Returns a file object for the file.
public abstract String	getName() Return the base name (last component) of the file name.
public abstract String	getPath() Return the file system path for this file.
public abstract boolean	isAbsolute() Return true if file has an absolute path name.
public abstract boolean	isDirectory() Return true if file identifies a directory.
public abstract boolean	isFile() Return true if file identifies a file.
public abstract boolean	isSameFile(DocFile other) Return true if this file is the same as another.
public static Iterable<DocFile>	list(BaseConfiguration the doclet configuration configuration, JavaFileManager.Location currently, only `StandardLocation#SOURCE_PATH` is supported. location, DocPath the subdirectory of the directories of the location for which to list files path) List the directories and files found in subdirectories along the elements of the given location.
public abstract Iterable<DocFile>	Returns: the contents of the directory list() If the file is a directory, list its contents.
private String	localize(String line, Resources resources)
public abstract boolean	mkdirs() Create the file as a directory, including any parent directories.
public abstract InputStream	Returns: an open input stream for the file openInputStream() Open an input stream for the file.
public abstract OutputStream	Returns: an open output stream for the file openOutputStream() Open an output stream for the file.
public abstract Writer	Returns: an open output stream for the file openWriter() Open an writer for the file, using the encoding (if any) given in the doclet configuration.
private static int	Returns: the number of bytes read, or -1 if at end of file read(DocFile the file for the stream inFile, InputStream the stream input, byte[] the buffer buf) Reads from an input stream opened from a given file into a given buffer.
private static int	Returns: the number of bytes read, or -1 if at end of file readResource(DocPath the resource for the stream docPath, InputStream the stream in, byte[] the buffer buf) Reads from an input stream opened from a given resource into a given buffer.
private static String	Returns: the line of text, or `null` if at end of stream readResourceLine(DocPath the resource for the stream docPath, BufferedReader the stream in) Reads a line of characters from an input stream opened from a given resource.
public abstract DocFile	resolve(DocPath p) Derive a new file by resolving a relative path against this file.
public abstract DocFile	resolve(String p) Derive a new file by resolving a relative path against this file.
public abstract DocFile	resolveAgainst(JavaFileManager.Location Currently, only `DocumentationTool.Location#DOCUMENTATION_OUTPUT` is supported. locn) Resolve a relative file against the given output location.
private static void	write(DocFile the file for the stream outFile, OutputStream the stream out, byte[] the buffer buf, int len) Writes to an output stream for a given file from a given buffer.
private static void	write(DocFile the file for the stream outFile, Writer the stream out, String the text to be written text) Writes text to an output stream for a given file from a given buffer.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

location	back to summary
protected final JavaFileManager.Location location The location for this file. Maybe null if the file was created without a location or path.

path	back to summary
protected final DocPath path The path relative to the (output) location. Maybe null if the file was created without a location or path.

PLATFORM_LINE_SEPARATOR	back to summary
public static final String PLATFORM_LINE_SEPARATOR The line separator for the current platform. Use this when writing to external files.

replacePtn	back to summary
private static final Pattern replacePtn

DocFile	back to summary
protected DocFile() Create a DocFile without a location or path

DocFile	back to summary
protected DocFile(JavaFileManager.Location location, DocPath path) Create a DocFile for a given location and relative path.

Method Detail

canRead	back to summary
public abstract boolean canRead() Return true if the file can be read.

canWrite	back to summary
public abstract boolean canWrite() Return true if the file can be written.

copyFile	back to summary
public void copyFile(DocFile fromFile) throws DocFileIOException Copy the contents of another file directly to this file. Parameters fromFile:DocFile the file to be copied Exceptions DocFileIOException: if there is a problem file copying the file

copyFile

back to summary

public void copyFile(DocFile fromFile) throws DocFileIOException

Copy the contents of another file directly to this file.

Parameters

fromFile:DocFile: the file to be copied

Exceptions

DocFileIOException:: if there is a problem file copying the file

copyResource	back to summary
public void copyResource(DocPath resource, URL url, boolean replaceNewLine) throws DocFileIOException, ResourceIOException Copy the contents of a resource file to this file. Parameters resource:DocPath the path of the resource url:URL the URL of the resource replaceNewLine:boolean if false, the file is copied as a binary file; if true, the file is written line by line, using the platform line separator Exceptions DocFileIOException: if there is a problem while writing the copy ResourceIOException: if there is a problem while reading the resource

copyResource

back to summary

public void copyResource(DocPath resource, URL url, boolean replaceNewLine) throws DocFileIOException, ResourceIOException

Copy the contents of a resource file to this file.

Parameters

resource:DocPath: the path of the resource
url:URL: the URL of the resource
replaceNewLine:boolean: if false, the file is copied as a binary file; if true, the file is written line by line, using the platform line separator

Exceptions

DocFileIOException:: if there is a problem while writing the copy
ResourceIOException:: if there is a problem while reading the resource

copyResource back to summary

copyResource	back to summary
public void copyResource(DocPath resource, URL url, Resources resources) throws DocFileIOException, ResourceIOException Copy the contents of a resource file to this file. Parameters resource:DocPath the path of the resource url:URL the URL of the resource resources:Resources if not `null`, substitute occurrences of `##REPLACE:key##` Exceptions DocFileIOException: if there is a problem while writing the copy ResourceIOException: if there is a problem while reading the resource

public void copyResource(DocPath resource, URL url, Resources resources) throws DocFileIOException, ResourceIOException

Copy the contents of a resource file to this file.

Parameters

resource:DocPath: the path of the resource
url:URL: the URL of the resource
resources:Resources: if not null, substitute occurrences of ##REPLACE:key##

Exceptions

DocFileIOException:: if there is a problem while writing the copy
ResourceIOException:: if there is a problem while reading the resource

copyResource back to summary

copyResource	back to summary
public void copyResource(DocPath resource, URL url, UnaryOperator<String> lineTransformer) throws DocFileIOException, ResourceIOException Copy the contents of a resource file to this file while transforming and filtering its lines. Parameters resource:DocPath the path of the resource url:URL the URL of the resource lineTransformer:UnaryOperator<String> the transforming function that is called for each line; may return `null` to remove a line. Exceptions DocFileIOException: if there is a problem while writing the copy ResourceIOException: if there is a problem while reading the resource

public void copyResource(DocPath resource, URL url, UnaryOperator<String> lineTransformer) throws DocFileIOException, ResourceIOException

Copy the contents of a resource file to this file while transforming and filtering its lines.

Parameters

resource:DocPath: the path of the resource
url:URL: the URL of the resource
lineTransformer:UnaryOperator<String>: the transforming function that is called for each line; may return null to remove a line.

Exceptions

DocFileIOException:: if there is a problem while writing the copy
ResourceIOException:: if there is a problem while reading the resource

copyResource	back to summary
private void copyResource(DocPath resource, URL url, boolean replaceNewLine, UnaryOperator<String> lineTransformer) throws ResourceIOException, DocFileIOException

createFileForDirectory	back to summary
public static DocFile createFileForDirectory(BaseConfiguration configuration, String file) Create a DocFile for a directory.

createFileForInput	back to summary
public static DocFile createFileForInput(BaseConfiguration configuration, String file) Create a DocFile for a file that will be opened for reading.

createFileForInput	back to summary
public static DocFile createFileForInput(BaseConfiguration configuration, Path file) Create a DocFile for a file that will be opened for reading.

createFileForOutput	back to summary
public static DocFile createFileForOutput(BaseConfiguration configuration, DocPath path) Create a DocFile for a file that will be opened for writing.

exists	back to summary
public abstract boolean exists() Return true if the file exists.

getFileObject	back to summary
public abstract FileObject getFileObject() Returns a file object for the file. Returns:FileObject a file object

getFileObject

back to summary

public abstract FileObject getFileObject()

Returns a file object for the file.

Returns:FileObject: a file object

getName	back to summary
public abstract String getName() Return the base name (last component) of the file name.

getPath	back to summary
public abstract String getPath() Return the file system path for this file.

isAbsolute	back to summary
public abstract boolean isAbsolute() Return true if file has an absolute path name.

isDirectory	back to summary
public abstract boolean isDirectory() Return true if file identifies a directory.

isFile	back to summary
public abstract boolean isFile() Return true if file identifies a file.

isSameFile	back to summary
public abstract boolean isSameFile(DocFile other) Return true if this file is the same as another.

list back to summary

list	back to summary
public static Iterable<DocFile> list(BaseConfiguration configuration, JavaFileManager.Location location, DocPath path) List the directories and files found in subdirectories along the elements of the given location. Parameters configuration:BaseConfiguration the doclet configuration location:JavaFileManager.Location currently, only `StandardLocation#SOURCE_PATH` is supported. path:DocPath the subdirectory of the directories of the location for which to list files

public static Iterable<DocFile> list(BaseConfiguration configuration, JavaFileManager.Location location, DocPath path)

List the directories and files found in subdirectories along the elements of the given location.

Parameters

configuration:BaseConfiguration: the doclet configuration
location:JavaFileManager.Location: currently, only StandardLocation#SOURCE_PATH is supported.
path:DocPath: the subdirectory of the directories of the location for which to list files

list	back to summary
public abstract Iterable<DocFile> list() throws DocFileIOException If the file is a directory, list its contents. Returns:Iterable<DocFile> the contents of the directory Exceptions DocFileIOException: if there is a problem while listing the directory

list

back to summary

public abstract Iterable<DocFile> list() throws DocFileIOException

If the file is a directory, list its contents.

Returns:Iterable<DocFile>

the contents of the directory

Exceptions

DocFileIOException:: if there is a problem while listing the directory

localize	back to summary
private String localize(String line, Resources resources)

mkdirs	back to summary
public abstract boolean mkdirs() Create the file as a directory, including any parent directories.

openInputStream	back to summary
public abstract InputStream openInputStream() throws DocFileIOException Open an input stream for the file. Returns:InputStream an open input stream for the file Exceptions DocFileIOException: if there is a problem opening the stream

openInputStream

back to summary

public abstract InputStream openInputStream() throws DocFileIOException

Open an input stream for the file.

Returns:InputStream

an open input stream for the file

Exceptions

DocFileIOException:: if there is a problem opening the stream

openOutputStream back to summary

openOutputStream	back to summary
public abstract OutputStream openOutputStream() throws DocFileIOException, UnsupportedEncodingException Open an output stream for the file. The file must have been created with a location of `DocumentationTool.Location#DOCUMENTATION_OUTPUT` and a corresponding relative path. Returns:OutputStream an open output stream for the file Exceptions DocFileIOException: if there is a problem opening the stream UnsupportedEncodingException: if the configured encoding is not supported

public abstract OutputStream openOutputStream() throws DocFileIOException, UnsupportedEncodingException

Open an output stream for the file. The file must have been created with a location of DocumentationTool.Location#DOCUMENTATION_OUTPUT and a corresponding relative path.

Returns:OutputStream

an open output stream for the file

Exceptions

DocFileIOException:: if there is a problem opening the stream
UnsupportedEncodingException:: if the configured encoding is not supported

openWriter back to summary

openWriter	back to summary
public abstract Writer openWriter() throws DocFileIOException, UnsupportedEncodingException Open an writer for the file, using the encoding (if any) given in the doclet configuration. The file must have been created with a location of `DocumentationTool.Location#DOCUMENTATION_OUTPUT` and a corresponding relative path. Returns:Writer an open output stream for the file Exceptions DocFileIOException: if there is a problem opening the stream UnsupportedEncodingException: if the configured encoding is not supported

public abstract Writer openWriter() throws DocFileIOException, UnsupportedEncodingException

Open an writer for the file, using the encoding (if any) given in the doclet configuration. The file must have been created with a location of DocumentationTool.Location#DOCUMENTATION_OUTPUT and a corresponding relative path.

Returns:Writer

an open output stream for the file

Exceptions

DocFileIOException:: if there is a problem opening the stream
UnsupportedEncodingException:: if the configured encoding is not supported

read back to summary

read	back to summary
private static int read(DocFile inFile, InputStream input, byte[] buf) throws DocFileIOException Reads from an input stream opened from a given file into a given buffer. If an `IOException` occurs, it is wrapped in a `DocFileIOException`. Parameters inFile:DocFile the file for the stream input:InputStream the stream buf:byte[] the buffer Returns:int the number of bytes read, or -1 if at end of file Exceptions DocFileIOException: if an exception occurred while reading the stream

private static int read(DocFile inFile, InputStream input, byte[] buf) throws DocFileIOException

Reads from an input stream opened from a given file into a given buffer. If an IOException occurs, it is wrapped in a DocFileIOException.

Parameters

inFile:DocFile: the file for the stream
input:InputStream: the stream
buf:byte[]: the buffer

Returns:int

the number of bytes read, or -1 if at end of file

Exceptions

DocFileIOException:: if an exception occurred while reading the stream

readResource back to summary

readResource	back to summary
private static int readResource(DocPath docPath, InputStream in, byte[] buf) throws ResourceIOException Reads from an input stream opened from a given resource into a given buffer. If an `IOException` occurs, it is wrapped in a `ResourceIOException`. Parameters docPath:DocPath the resource for the stream in:InputStream the stream buf:byte[] the buffer Returns:int the number of bytes read, or -1 if at end of file Exceptions ResourceIOException: if an exception occurred while reading the stream

private static int readResource(DocPath docPath, InputStream in, byte[] buf) throws ResourceIOException

Reads from an input stream opened from a given resource into a given buffer. If an IOException occurs, it is wrapped in a ResourceIOException.

Parameters

docPath:DocPath: the resource for the stream
in:InputStream: the stream
buf:byte[]: the buffer

Returns:int

the number of bytes read, or -1 if at end of file

Exceptions

ResourceIOException:: if an exception occurred while reading the stream

readResourceLine back to summary

readResourceLine	back to summary
private static String readResourceLine(DocPath docPath, BufferedReader in) throws ResourceIOException Reads a line of characters from an input stream opened from a given resource. If an `IOException` occurs, it is wrapped in a `ResourceIOException`. Parameters docPath:DocPath the resource for the stream in:BufferedReader the stream Returns:String the line of text, or `null` if at end of stream Exceptions ResourceIOException: if an exception occurred while reading the stream

private static String readResourceLine(DocPath docPath, BufferedReader in) throws ResourceIOException

Reads a line of characters from an input stream opened from a given resource. If an IOException occurs, it is wrapped in a ResourceIOException.

Parameters

docPath:DocPath: the resource for the stream
in:BufferedReader: the stream

Returns:String

the line of text, or null if at end of stream

Exceptions

ResourceIOException:: if an exception occurred while reading the stream

resolve	back to summary
public abstract DocFile resolve(DocPath p) Derive a new file by resolving a relative path against this file. The new file will inherit the configuration and location of this file If this file has a path set, the new file will have a corresponding new path.

resolve	back to summary
public abstract DocFile resolve(String p) Derive a new file by resolving a relative path against this file. The new file will inherit the configuration and location of this file If this file has a path set, the new file will have a corresponding new path.

resolveAgainst back to summary

resolveAgainst	back to summary
public abstract DocFile resolveAgainst(JavaFileManager.Location locn) Resolve a relative file against the given output location. Parameters locn:JavaFileManager.Location Currently, only `DocumentationTool.Location#DOCUMENTATION_OUTPUT` is supported.

public abstract DocFile resolveAgainst(JavaFileManager.Location locn)

Resolve a relative file against the given output location.

Parameters

locn:JavaFileManager.Location: Currently, only DocumentationTool.Location#DOCUMENTATION_OUTPUT is supported.

write back to summary

write	back to summary
private static void write(DocFile outFile, OutputStream out, byte[] buf, int len) throws DocFileIOException Writes to an output stream for a given file from a given buffer. If an `IOException` occurs, it is wrapped in a `DocFileIOException`. Parameters outFile:DocFile the file for the stream out:OutputStream the stream buf:byte[] the buffer Exceptions DocFileIOException: if an exception occurred while writing the stream

private static void write(DocFile outFile, OutputStream out, byte[] buf, int len) throws DocFileIOException

Writes to an output stream for a given file from a given buffer. If an IOException occurs, it is wrapped in a DocFileIOException.

Parameters

outFile:DocFile: the file for the stream
out:OutputStream: the stream
buf:byte[]: the buffer

Exceptions

DocFileIOException:: if an exception occurred while writing the stream

write back to summary

write	back to summary
private static void write(DocFile outFile, Writer out, String text) throws DocFileIOException Writes text to an output stream for a given file from a given buffer. If an `IOException` occurs, it is wrapped in a `DocFileIOException`. Parameters outFile:DocFile the file for the stream out:Writer the stream text:String the text to be written Exceptions DocFileIOException: if an exception occurred while writing the stream

private static void write(DocFile outFile, Writer out, String text) throws DocFileIOException

Writes text to an output stream for a given file from a given buffer. If an IOException occurs, it is wrapped in a DocFileIOException.

Parameters

outFile:DocFile: the file for the stream
out:Writer: the stream
text:String: the text to be written

Exceptions

DocFileIOException:: if an exception occurred while writing the stream

public abstract Class DocFile

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail