Package net.sourceforge.pmd.lang.document

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 Details

    • 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 a File, 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 closed
      IOException - If an error occurs
      ReadOnlyFileException - 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 closed
      IOException - 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 interface AutoCloseable
      Specified by:
      close in interface Closeable
      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 by Object.equals(Object)).
      Overrides:
      equals in class Object

    • forPath

      static TextFile forPath(Path path, Charset charset, LanguageVersion languageVersion)
      Returns an instance of this interface reading and writing to a file. See builderForPath for more info.
      Parameters:
      path - Path to the file
      charset - Encoding to use
      languageVersion - 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, then readContents() 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 file
      charset - Encoding to use
      languageVersion - 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 that readContents() may not produce exactly the same char sequence.
      Parameters:
      charseq - Text of the file
      fileId - File name to use as path id
      languageVersion - 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 that readContents() may not produce exactly the same char sequence.
      Parameters:
      charseq - Text of the file
      fileId - File name to use as path id
      languageVersion - 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 when readContents() is first called, and is closed when that method exits. Note that this may only be called once, afterwards, readContents() will throw an IOException.
      Parameters:
      reader - Text of the file
      fileId - File name to use as path id
      languageVersion - 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 when readContents() is first called, and is closed when that method exits. Note that this may only be called once, afterwards, readContents() will throw an IOException.
      Parameters:
      reader - Text of the file
      fileId - File name to use as path id
      languageVersion - Language version
      Throws:
      NullPointerException - If any parameter is null