Path (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.fs, class: Path

Package org.apache.hadoop.fs

# Class Path

java.lang.Object
org.apache.hadoop.fs.Path

All Implemented Interfaces:
  `ObjectInputValidation`, `Serializable`, `Comparable<Path>`

@Stringable @Public @Stable public class Path extends Object implements Comparable<Path>, Serializable, ObjectInputValidation
Names a file or directory in a `FileSystem`. Path strings use slash as the directory separator.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CUR_DIR`
  The current directory, ".".
  `static final String`
  `SEPARATOR`
  The directory separator, a slash.
  `static final char`
  `SEPARATOR_CHAR`
  The directory separator, a slash, as a character.
  `static final boolean`
  `WINDOWS`
  Whether the current host is a Windows machine.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Path(String pathString)`
  Construct a path from a String.
  `Path(String parent, String child)`
  Create a new Path based on the child path resolved against the parent path.
  `Path(String scheme, String authority, String path)`
  Construct a Path from components.
  `Path(String parent, Path child)`
  Create a new Path based on the child path resolved against the parent path.
  `Path(URI aUri)`
  Construct a path from a URI
  `Path(Path parent, String child)`
  Create a new Path based on the child path resolved against the parent path.
  `Path(Path parent, Path child)`
  Create a new Path based on the child path resolved against the parent path.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `compareTo(Path o)`
  `int`
  `depth()`
  Returns the number of elements in this path.
  `boolean`
  `equals(Object o)`
  `FileSystem`
  `getFileSystem(Configuration conf)`
  Return the FileSystem that owns this Path.
  `String`
  `getName()`
  Returns the final component of this path.
  `Optional<Path>`
  `getOptionalParentPath()`
  Returns the parent of a path as `Optional` or `Optional.empty()` i.e an empty Optional if at root.
  `Path`
  `getParent()`
  Returns the parent of a path or null if at root.
  `static Path`
  `getPathWithoutSchemeAndAuthority(Path path)`
  Return a version of the given Path without the scheme information.
  `int`
  `hashCode()`
  `boolean`
  `isAbsolute()`
  Returns true if the path component (i.e. directory) of this URI is absolute.
  `boolean`
  `isAbsoluteAndSchemeAuthorityNull()`
  Returns true if the path component (i.e. directory) of this URI is absolute and the scheme is null, and the authority is null.
  `boolean`
  `isRoot()`
  Returns true if and only if this path represents the root of a file system.
  `boolean`
  `isUriPathAbsolute()`
  Returns true if the path component (i.e. directory) of this URI is absolute.
  `static boolean`
  `isWindowsAbsolutePath(String pathString, boolean slashed)`
  Determine whether a given path string represents an absolute path on Windows. e.g.
  `Path`
  `makeQualified(URI defaultUri, Path workingDir)`
  Returns a qualified path object.
  `Path`
  `makeQualified(FileSystem fs)`
  Deprecated.
  use `makeQualified(URI, Path)`
  `static Path`
  `mergePaths(Path path1, Path path2)`
  Merge 2 paths such that the second path is appended relative to the first.
  `Path`
  `suffix(String suffix)`
  Adds a suffix to the final name in the path.
  `String`
  `toString()`
  `URI`
  `toUri()`
  Convert this Path to a URI.
  `void`
  `validateObject()`
  Validate the contents of a deserialized Path, so as to defend against malicious object streams.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### SEPARATOR

    public static final String SEPARATOR
    The directory separator, a slash.
    See Also:
      - Constant Field Values

  - ### SEPARATOR_CHAR

    public static final char SEPARATOR_CHAR
    The directory separator, a slash, as a character.
    See Also:
      - Constant Field Values

  - ### CUR_DIR

    public static final String CUR_DIR
    The current directory, ".".
    See Also:
      - Constant Field Values

  - ### WINDOWS

    public static final boolean WINDOWS
    Whether the current host is a Windows machine.

- ## Constructor Details

  - ### Path

    public Path(String parent, String child)
    Create a new Path based on the child path resolved against the parent path.
    Parameters:
      `parent` - the parent path
      `child` - the child path

  - ### Path

    public Path(Path parent, String child)
    Create a new Path based on the child path resolved against the parent path.
    Parameters:
      `parent` - the parent path
      `child` - the child path

  - ### Path

    public Path(String parent, Path child)
    Create a new Path based on the child path resolved against the parent path.
    Parameters:
      `parent` - the parent path
      `child` - the child path

  - ### Path

    public Path(Path parent, Path child)
    Create a new Path based on the child path resolved against the parent path.
    Parameters:
      `parent` - the parent path
      `child` - the child path

  - ### Path

    public Path(String pathString) throws IllegalArgumentException
    Construct a path from a String. Path strings are URIs, but with unescaped elements and some additional normalization.
    Parameters:
      `pathString` - the path string
    Throws:
      `IllegalArgumentException`

  - ### Path

    public Path(URI aUri)
    Construct a path from a URI
    Parameters:
      `aUri` - the source URI

  - ### Path

    public Path(String scheme, String authority, String path)
    Construct a Path from components.
    Parameters:
      `scheme` - the scheme
      `authority` - the authority
      `path` - the path

- ## Method Details

  - ### getPathWithoutSchemeAndAuthority

    public static Path getPathWithoutSchemeAndAuthority(Path path)
    Return a version of the given Path without the scheme information.
    Parameters:
      `path` - the source Path
    Returns:
      a copy of this Path without the scheme information

  - ### mergePaths

    public static Path mergePaths(Path path1, Path path2)
    Merge 2 paths such that the second path is appended relative to the first. The returned path has the scheme and authority of the first path. On Windows, the drive specification in the second path is discarded.
    Parameters:
      `path1` - the first path
      `path2` - the second path, to be appended relative to path1
    Returns:
      the merged path

  - ### isWindowsAbsolutePath

    public static boolean isWindowsAbsolutePath(String pathString, boolean slashed)
    Determine whether a given path string represents an absolute path on Windows. e.g. "C:/a/b" is an absolute path. "C:a/b" is not.
    Parameters:
      `pathString` - the path string to evaluate
      `slashed` - true if the given path is prefixed with "/"
    Returns:
      true if the supplied path looks like an absolute path with a Windows drive-specifier

  - ### toUri

    public URI toUri()
    Convert this Path to a URI.
    Returns:
      this Path as a URI

  - ### getFileSystem

    public FileSystem getFileSystem(Configuration conf) throws IOException
    Return the FileSystem that owns this Path.
    Parameters:
      `conf` - the configuration to use when resolving the FileSystem
    Returns:
      the FileSystem that owns this Path
    Throws:
      `IOException` - thrown if there's an issue resolving the FileSystem

  - ### isAbsoluteAndSchemeAuthorityNull

    public boolean isAbsoluteAndSchemeAuthorityNull()
    Returns true if the path component (i.e. directory) of this URI is absolute and the scheme is null, and the authority is null.
    Returns:
      whether the path is absolute and the URI has no scheme nor authority parts

  - ### isUriPathAbsolute

    public boolean isUriPathAbsolute()
    Returns true if the path component (i.e. directory) of this URI is absolute.
    Returns:
      whether this URI's path is absolute

  - ### isAbsolute

    public boolean isAbsolute()
    Returns true if the path component (i.e. directory) of this URI is absolute. This method is a wrapper for `isUriPathAbsolute()`.
    Returns:
      whether this URI's path is absolute

  - ### isRoot

    public boolean isRoot()
    Returns true if and only if this path represents the root of a file system.
    Returns:
      true if and only if this path represents the root of a file system

  - ### getName

    public String getName()
    Returns the final component of this path.
    Returns:
      the final component of this path

  - ### getParent

    public Path getParent()
    Returns the parent of a path or null if at root. Better alternative is `getOptionalParentPath()` to handle nullable value for root path.
    Returns:
      the parent of a path or null if at root

  - ### getOptionalParentPath

    public Optional<Path> getOptionalParentPath()
    Returns the parent of a path as `Optional` or `Optional.empty()` i.e an empty Optional if at root.
    Returns:
      Parent of path wrappen in `Optional`. `Optional.empty()` i.e an empty Optional if at root.

  - ### suffix

    public Path suffix(String suffix)
    Adds a suffix to the final name in the path.
    Parameters:
      `suffix` - the suffix to add
    Returns:
      a new path with the suffix added

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### compareTo

    public int compareTo(Path o)
    Specified by:
      `compareTo` in interface `Comparable<Path>`

  - ### depth

    public int depth()
    Returns the number of elements in this path.
    Returns:
      the number of elements in this path

  - ### makeQualified

    @Deprecated public Path makeQualified(FileSystem fs)
    Deprecated.
    use `makeQualified(URI, Path)`
    Returns a qualified path object for the `FileSystem`'s working directory.
    Parameters:
      `fs` - the target FileSystem
    Returns:
      a qualified path object for the FileSystem's working directory

  - ### makeQualified

    @LimitedPrivate({"HDFS","MapReduce"}) public Path makeQualified(URI defaultUri, Path workingDir)
    Returns a qualified path object.
    Parameters:
      `defaultUri` - if this path is missing the scheme or authority components, borrow them from this URI
      `workingDir` - if this path isn't absolute, treat it as relative to this working directory
    Returns:
      this path if it contains a scheme and authority and is absolute, or a new path that includes a path and authority and is fully qualified

  - ### validateObject

    public void validateObject() throws InvalidObjectException
    Validate the contents of a deserialized Path, so as to defend against malicious object streams.
    Specified by:
      `validateObject` in interface `ObjectInputValidation`
    Throws:
      `InvalidObjectException` - if there's no URI