Interface TextFile
-
- All Superinterfaces:
AutoCloseable
,Closeable
public interface TextFile extends Closeable
Represents some location containing character data. Despite the name, it's not necessarily backed by a file in the file-system: it may be eg an in-memory buffer, or a zip entry, ie it's an abstraction. Text files are the input which PMD and CPD process.Text files must provide read access, and may provide write access. This interface only provides block IO operations, while
TextDocument
adds logic about incremental edition (eg replacing a single region of text).
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description static TextFileBuilder
builderForCharSeq(CharSequence charseq, FileId fileId, LanguageVersion languageVersion)
Returns a read-only TextFile reading from a string.static TextFileBuilder
builderForPath(Path path, Charset charset, LanguageVersion languageVersion)
Returns a builder for a textfile that reads and write to the file.static TextFileBuilder
builderForReader(Reader reader, FileId fileId, LanguageVersion languageVersion)
Returns a read-only builder reading from a reader.void
close()
Release resources associated with this text file.boolean
equals(Object o)
Text file equality is implementation-defined.static TextFile
forCharSeq(CharSequence charseq, FileId fileId, LanguageVersion languageVersion)
Returns a read-only TextFile reading from a string.static TextFile
forPath(Path path, Charset charset, LanguageVersion languageVersion)
Returns an instance of this interface reading and writing to a file.static TextFile
forReader(Reader reader, FileId fileId, LanguageVersion languageVersion)
Returns a read-only instance of this interface reading from a reader.FileId
getFileId()
Returns an identifier for this file.@NonNull LanguageVersion
getLanguageVersion()
Returns the language version which should be used to process this file.default boolean
isReadOnly()
Returns true if this file cannot be written to.TextFileContent
readContents()
Reads the contents of the underlying character source.default void
writeContents(TextFileContent content)
Writes the given content to the underlying character store.
-
-
-
Method Detail
-
getLanguageVersion
@NonNull LanguageVersion getLanguageVersion()
Returns the language version which should be used to process this file. This is a property of the file, which allows sources for different language versions to be processed in the same PMD run. It also makes it so, that the file extension is not interpreted to find out the language version after the initial file collection phase.- Returns:
- A language version
-
getFileId
FileId getFileId()
Returns an identifier for this file. This should not be interpreted as aFile
, it may not be a file on this filesystem. Two distinct text files should have distinct path IDs, and from one analysis to the next, the path ID of logically identical files should be the same.
-
isReadOnly
default boolean isReadOnly()
Returns true if this file cannot be written to. In that case,writeContents(TextFileContent)
will throw an exception. In the general case, nothing prevents this method's result from changing from one invocation to another.
-
writeContents
default void writeContents(TextFileContent content) throws IOException
Writes the given content to the underlying character store.- Parameters:
content
- Content to write, with lines separated by the given line separator- Throws:
IOException
- If this instance is closedIOException
- If an error occursReadOnlyFileException
- If this text source is read-only
-
readContents
TextFileContent readContents() throws IOException
Reads the contents of the underlying character source.- Returns:
- The most up-to-date content
- Throws:
IOException
- If this instance is closedIOException
- If reading causes an IOException
-
close
void close() throws IOException
Release resources associated with this text file. Is a noop if it is called several times.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- If an IO exception occurs
-
equals
boolean equals(Object o)
Text file equality is implementation-defined. The only constraint is that equal text files should have equal path IDs (and the usual properties mandated byObject.equals(Object)
).
-
forPath
static TextFile forPath(Path path, Charset charset, LanguageVersion languageVersion)
Returns an instance of this interface reading and writing to a file. SeebuilderForPath
for more info.- Parameters:
path
- Path to the filecharset
- Encoding to uselanguageVersion
- Language version to use- Throws:
NullPointerException
- If any parameter is null
-
builderForPath
static TextFileBuilder builderForPath(Path path, Charset charset, LanguageVersion languageVersion)
Returns a builder for a textfile that reads and write to the file. The returned instance may be read-only. If the file is not a regular file (eg, a directory), or does not exist, thenreadContents()
will throw.The display name is by default the given path (without normalization), while the path id is the absolute path.
- Parameters:
path
- Path to the filecharset
- Encoding to uselanguageVersion
- Language version to use- Throws:
NullPointerException
- If any parameter is null
-
forCharSeq
static TextFile forCharSeq(CharSequence charseq, FileId fileId, LanguageVersion languageVersion)
Returns a read-only TextFile reading from a string. Note that this will normalize the text, in such a way thatreadContents()
may not produce exactly the same char sequence.- Parameters:
charseq
- Text of the filefileId
- File name to use as path idlanguageVersion
- Language version- Throws:
NullPointerException
- If any parameter is null
-
builderForCharSeq
static TextFileBuilder builderForCharSeq(CharSequence charseq, FileId fileId, LanguageVersion languageVersion)
Returns a read-only TextFile reading from a string. Note that this will normalize the text, in such a way thatreadContents()
may not produce exactly the same char sequence.- Parameters:
charseq
- Text of the filefileId
- File name to use as path idlanguageVersion
- Language version- Throws:
NullPointerException
- If any parameter is null
-
forReader
static TextFile forReader(Reader reader, FileId fileId, LanguageVersion languageVersion)
Returns a read-only instance of this interface reading from a reader. The reader is first read whenreadContents()
is first called, and is closed when that method exits. Note that this may only be called once, afterwards,readContents()
will throw anIOException
.- Parameters:
reader
- Text of the filefileId
- File name to use as path idlanguageVersion
- Language version- Throws:
NullPointerException
- If any parameter is null
-
builderForReader
static TextFileBuilder builderForReader(Reader reader, FileId fileId, LanguageVersion languageVersion)
Returns a read-only builder reading from a reader. The reader is first read whenreadContents()
is first called, and is closed when that method exits. Note that this may only be called once, afterwards,readContents()
will throw anIOException
.- Parameters:
reader
- Text of the filefileId
- File name to use as path idlanguageVersion
- Language version- Throws:
NullPointerException
- If any parameter is null
-
-