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).

    This interface is meant to replace DataSource and SourceCode.CodeLoader. "DataSource" is not an appropriate name for a file which can be written to, also, the "data" it provides is text, not bytes.

    • Field Detail

      • UNKNOWN_FILENAME

        static final String UNKNOWN_FILENAME
        The name used for a file that has no name. This is mostly only relevant for unit tests.
        See Also:
        Constant Field Values

    • 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 several 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

      • getPathId

        String getPathId()
        Returns an identifier for the path of this file. This should not be interpreted as a File, it may not be a file on this filesystem. The only requirement for this method, is that two distinct text files should have distinct path IDs, and that from one analysis to the next, the path ID of logically identical files be the same.

        Basically this may be implemented as a URL, or a file path. It is used to index violation caches.

      • getDisplayName

        @NonNull String getDisplayName()
        Returns a display name for the file. This name is used for reporting and should not be interpreted. It may be relative to a directory or so, it may also not be normalized. Use getPathId() when you want an identifier.

      • 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,
                           String pathId,
                           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
        pathId - File name to use as path id
        languageVersion - Language version
        Throws:
        NullPointerException - If any parameter is null

      • builderForCharSeq

        static TextFileBuilder builderForCharSeq​(CharSequence charseq,
                                         String pathId,
                                         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
        pathId - File name to use as path id
        languageVersion - Language version
        Throws:
        NullPointerException - If any parameter is null

      • forReader

        static TextFile forReader​(Reader reader,
                          String pathId,
                          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
        pathId - File name to use as path id
        languageVersion - Language version
        Throws:
        NullPointerException - If any parameter is null

      • builderForReader

        static TextFileBuilder builderForReader​(Reader reader,
                                        String pathId,
                                        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
        pathId - File name to use as path id
        languageVersion - Language version
        Throws:
        NullPointerException - If any parameter is null