Package net.sourceforge.pmd.lang.document

Interface FileId

All Superinterfaces:

Comparable<FileId>

public interface FileId
extends Comparable<FileId>

An identifier for a TextFile. This is not a path, but provides several methods to be rendered into path-like strings in different formats (for use mostly by Renderer instances). File IDs are used to identify files e.g. in RuleViolation, FileLocation, TextFile.

Note that the addressed file may not be an actual file on a file system. For instance, you can create file ids from strings (fromPathLikeString(String)), or use STDIN to address standard input. The rendering methods of this interface (like getAbsolutePath()) do not have to return actual paths for those exotic files, and operate on a best-effort basis.

Author:

Clément Fournier

Field Summary

Fields

Modifier and Type	Field	Description
static FileId	STDIN	The virtual file ID for standard input.
static FileId	UNKNOWN	The name used for an unknown file.

Method Summary

Modifier and Type	Method	Description
static FileId	asChildOf(FileId self, FileId parentFsPath)	Return a file ID whose methods behave the same as the first parameter, and whose getParentFsPath() returns the second parameter.
default int	compareTo(FileId o)
boolean	equals(Object o)	Two file IDs are equal if they have the same getUriString().
static FileId	fromAbsolutePath(String absPath, @Nullable FileId outer)	Return a file ID which interprets the first parameter as an absolute path.
static FileId	fromPath(Path path)	Return a file ID for the given path.
static FileId	fromPath(Path path, @Nullable FileId fsPath)	Return a new path id for the given path.
static FileId	fromPathLikeString(String str)	Return a path ID for the given string.
static FileId	fromURI(String uriStr)	Return a file ID for a URI.
String	getAbsolutePath()	Return an absolute path to this file in its containing file system.
String	getFileName()	Return the simple file name, like Path.getFileName().
String	getOriginalPath()	Return the path as it was input by the user.
@Nullable FileId	getParentFsPath()	If this file is in a nested filesystem (eg a zip file), return the file ID of the container in the outer file system.
String	getUriString()	Return a string that looks like a URI pointing to this file.
String	toString()	This method is intentionally only meant for debugging, and its output is unspecified.

Field Detail

UNKNOWN

static final FileId UNKNOWN

The name used for an unknown file. This is mostly only relevant for unit tests.

STDIN

static final FileId STDIN

The virtual file ID for standard input.

Method Detail

getFileName

String getFileName()

Return the simple file name, like Path.getFileName(). This includes the extension.

getOriginalPath

String getOriginalPath()

Return the path as it was input by the user. This may be a relative or absolute path.

getAbsolutePath

String getAbsolutePath()

Return an absolute path to this file in its containing file system. If the file is in a zip file, then this returns a path from the zip root, and does not include the path of the zip itself.

getUriString

String getUriString()

Return a string that looks like a URI pointing to this file.

getParentFsPath

@Nullable FileId getParentFsPath()

If this file is in a nested filesystem (eg a zip file), return the file ID of the container in the outer file system. Return null if this is in the root file system.

equals

boolean equals(Object o)

Two file IDs are equal if they have the same getUriString().

Overrides:

equals in class Object

Parameters:

o - Object

compareTo

default int compareTo(FileId o)

Specified by:

compareTo in interface Comparable<FileId>

toString

String toString()

This method is intentionally only meant for debugging, and its output is unspecified. Code that needs a string representation should use one of the named string conversion methods.

Overrides:

toString in class Object

fromPathLikeString

static FileId fromPathLikeString(String str)

Return a path ID for the given string. The string is interpreted as a file system path, so that getAbsolutePath() and getUriString() may work.

Parameters:

str - A string. Should be a valid file system path for the platform (see Paths.get(String, String...).

Returns:

A new file id

fromPath

static FileId fromPath(Path path,
                       @Nullable FileId fsPath)

Return a new path id for the given path.

Parameters:

path - The path

fsPath - The file id of the containing file system, if it is some Zip file.

Returns:

A new file id.

fromPath

static FileId fromPath(Path path)

Return a file ID for the given path. This uses fromPath(Path, FileId) and defaults the second parameter to null.

asChildOf

static FileId asChildOf(FileId self,
                        FileId parentFsPath)

Return a file ID whose methods behave the same as the first parameter, and whose getParentFsPath() returns the second parameter.

Parameters:

self - A file id

parentFsPath - Another file id for the parent.

fromAbsolutePath

static FileId fromAbsolutePath(String absPath,
                               @Nullable FileId outer)

Return a file ID which interprets the first parameter as an absolute path. The path must be a valid path for this system (Paths.get(String, String...) should not fail). The URI is rebuilt using the outer file ID if it is non-null.

Parameters:

absPath - Absolute path for the file

outer - File ID of the outer file system (Zip), if it exists

Returns:

A new file id

fromURI

static FileId fromURI(String uriStr)
               throws IllegalArgumentException

Return a file ID for a URI. The URI must have scheme file or jar and be a valid URI (see URI.create(String)). If the scheme is jar, then the getParentFsPath() is populated with the path of the jar.

Parameters:

uriStr - A uri string

Returns:

A new file id

Throws:

IllegalArgumentException