From 6fefb8f4a486b1d8071a7071e9e96f0c6299752d Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Tue, 21 Jun 2016 20:16:22 +0900 Subject: [PATCH] HADOOP-13296. Cleanup javadoc for Path. Contributed by Daniel Templeton. (cherry picked from commit e15cd43369eb6d478844f25897e4a86065c62168) (cherry picked from commit 65b4f2682e4b1803a4fd7348bd518b8723724686) --- .../main/java/org/apache/hadoop/fs/Path.java | 181 ++++++++++++++---- 1 file changed, 142 insertions(+), 39 deletions(-) diff --git a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Path.java b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Path.java index a38a46c422e..f18a675d1e7 100644 --- a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Path.java +++ b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Path.java @@ -30,7 +30,8 @@ import org.apache.hadoop.classification.InterfaceStability; import org.apache.hadoop.conf.Configuration; -/** Names a file or directory in a {@link FileSystem}. +/** + * Names a file or directory in a {@link FileSystem}. * Path strings use slash as the directory separator. */ @Stringable @@ -38,26 +39,37 @@ @InterfaceStability.Stable public class Path implements Comparable { - /** The directory separator, a slash. */ + /** + * The directory separator, a slash. + */ public static final String SEPARATOR = "/"; + + /** + * The directory separator, a slash, as a character. + */ public static final char SEPARATOR_CHAR = '/'; + /** + * The current directory, ".". + */ public static final String CUR_DIR = "."; - public static final boolean WINDOWS - = System.getProperty("os.name").startsWith("Windows"); + /** + * Whether the current host is a Windows machine. + */ + public static final boolean WINDOWS = + System.getProperty("os.name").startsWith("Windows"); /** * Pre-compiled regular expressions to detect path formats. */ - private static final Pattern hasUriScheme = - Pattern.compile("^[a-zA-Z][a-zA-Z0-9+-.]+:"); - private static final Pattern hasDriveLetterSpecifier = + private static final Pattern HAS_DRIVE_LETTER_SPECIFIER = Pattern.compile("^/?[a-zA-Z]:"); - private URI uri; // a hierarchical uri + private URI uri; // a hierarchical uri /** + * Test whether this Path uses a scheme and is relative. * Pathnames with scheme and relative path are illegal. */ void checkNotSchemeWithRelative() { @@ -73,6 +85,12 @@ void checkNotRelative() { } } + /** + * Return a version of the given Path without the scheme information. + * + * @param path the source Path + * @return a copy of this Path without the scheme information + */ public static Path getPathWithoutSchemeAndAuthority(Path path) { // This code depends on Path.toString() to remove the leading slash before // the drive specification on Windows. @@ -82,22 +100,42 @@ public static Path getPathWithoutSchemeAndAuthority(Path path) { return newPath; } - /** Resolve a child path against a parent path. */ + /** + * Create a new Path based on the child path resolved against the parent path. + * + * @param parent the parent path + * @param child the child path + */ public Path(String parent, String child) { this(new Path(parent), new Path(child)); } - /** Resolve a child path against a parent path. */ + /** + * Create a new Path based on the child path resolved against the parent path. + * + * @param parent the parent path + * @param child the child path + */ public Path(Path parent, String child) { this(parent, new Path(child)); } - /** Resolve a child path against a parent path. */ + /** + * Create a new Path based on the child path resolved against the parent path. + * + * @param parent the parent path + * @param child the child path + */ public Path(String parent, Path child) { this(new Path(parent), child); } - /** Resolve a child path against a parent path. */ + /** + * Create a new Path based on the child path resolved against the parent path. + * + * @param parent the parent path + * @param child the child path + */ public Path(Path parent, Path child) { // Add a slash to parent's path so resolution is compatible with URI's URI parentUri = parent.uri; @@ -127,8 +165,12 @@ private void checkPathArg( String path ) throws IllegalArgumentException { } } - /** Construct a path from a String. Path strings are URIs, but with - * unescaped elements and some additional normalization. */ + /** + * Construct a path from a String. Path strings are URIs, but with + * unescaped elements and some additional normalization. + * + * @param pathString the path string + */ public Path(String pathString) throws IllegalArgumentException { checkPathArg( pathString ); @@ -172,12 +214,20 @@ public Path(String pathString) throws IllegalArgumentException { /** * Construct a path from a URI + * + * @param aUri the source URI */ public Path(URI aUri) { uri = aUri.normalize(); } - /** Construct a Path from components. */ + /** + * Construct a Path from components. + * + * @param scheme the scheme + * @param authority the authority + * @param path the path + */ public Path(String scheme, String authority, String path) { checkPathArg( path ); @@ -210,9 +260,9 @@ private void initialize(String scheme, String authority, String path, * The returned path has the scheme and authority of the first path. On * Windows, the drive specification in the second path is discarded. * - * @param path1 Path first path - * @param path2 Path second path, to be appended relative to path1 - * @return Path merged path + * @param path1 the first path + * @param path2 the second path, to be appended relative to path1 + * @return the merged path */ public static Path mergePaths(Path path1, Path path2) { String path2Str = path2.toUri().getPath(); @@ -228,10 +278,11 @@ public static Path mergePaths(Path path1, Path path2) { /** * Normalize a path string to use non-duplicated forward slashes as * the path separator and remove any trailing path separators. - * @param scheme Supplies the URI scheme. Used to deduce whether we - * should replace backslashes or not. - * @param path Supplies the scheme-specific part - * @return Normalized path string. + * + * @param scheme the URI scheme. Used to deduce whether we + * should replace backslashes or not + * @param path the scheme-specific part + * @return the normalized path string */ private static String normalizePath(String scheme, String path) { // Remove double forward slashes. @@ -257,7 +308,7 @@ private static String normalizePath(String scheme, String path) { } private static boolean hasWindowsDrive(String path) { - return (WINDOWS && hasDriveLetterSpecifier.matcher(path).find()); + return (WINDOWS && HAS_DRIVE_LETTER_SPECIFIER.matcher(path).find()); } private static int startPositionWithoutWindowsDrive(String path) { @@ -272,10 +323,10 @@ private static int startPositionWithoutWindowsDrive(String path) { * 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. * - * @param pathString Supplies the path string to evaluate. - * @param slashed true if the given path is prefixed with "/". + * @param pathString the path string to evaluate + * @param slashed true if the given path is prefixed with "/" * @return true if the supplied path looks like an absolute path with a Windows - * drive-specifier. + * drive-specifier */ public static boolean isWindowsAbsolutePath(final String pathString, final boolean slashed) { @@ -286,17 +337,32 @@ public static boolean isWindowsAbsolutePath(final String pathString, (pathString.charAt(start) == '\\')); } - /** Convert this to a URI. */ + /** + * Convert this Path to a URI. + * + * @return this Path as a URI + */ public URI toUri() { return uri; } - /** Return the FileSystem that owns this Path. */ + /** + * Return the FileSystem that owns this Path. + * + * @param conf the configuration to use when resolving the FileSystem + * @return the FileSystem that owns this Path + * @throws java.io.IOException thrown if there's an issue resolving the + * FileSystem + */ public FileSystem getFileSystem(Configuration conf) throws IOException { return FileSystem.get(this.toUri(), conf); } /** - * Is an absolute path (ie a slash relative path part) - * AND a scheme is null AND authority is null. + * Returns true if the path component (i.e. directory) of this URI is + * absolute and the scheme is null, and the authority + * is null. + * + * @return whether the path is absolute and the URI has no scheme nor + * authority parts */ public boolean isAbsoluteAndSchemeAuthorityNull() { return (isUriPathAbsolute() && @@ -304,33 +370,50 @@ public boolean isAbsoluteAndSchemeAuthorityNull() { } /** - * True if the path component (i.e. directory) of this URI is absolute. + * Returns true if the path component (i.e. directory) of this URI is + * absolute. + * + * @return whether this URI's path is absolute */ public boolean isUriPathAbsolute() { int start = startPositionWithoutWindowsDrive(uri.getPath()); return uri.getPath().startsWith(SEPARATOR, start); } - /** True if the path is not a relative path and starts with root. */ + /** + * Returns true if the path component (i.e. directory) of this URI is + * absolute. This method is a wrapper for {@link #isUriPathAbsolute()}. + * + * @return whether this URI's path is absolute + */ public boolean isAbsolute() { return isUriPathAbsolute(); } /** + * Returns true if and only if this path represents the root of a file system. + * * @return true if and only if this path represents the root of a file system */ public boolean isRoot() { return getParent() == null; } - /** Returns the final component of this path.*/ + /** + * Returns the final component of this path. + * + * @return the final component of this path + */ public String getName() { String path = uri.getPath(); int slash = path.lastIndexOf(SEPARATOR); return path.substring(slash+1); } - /** Returns the parent of a path or null if at root. */ + /** + * Returns the parent of a path or null if at root. + * @return the parent of a path or null if at root + */ public Path getParent() { String path = uri.getPath(); int lastSlash = path.lastIndexOf('/'); @@ -348,7 +431,12 @@ public Path getParent() { return new Path(uri.getScheme(), uri.getAuthority(), parent); } - /** Adds a suffix to the final name in the path.*/ + /** + * Adds a suffix to the final name in the path. + * + * @param suffix the suffix to add + * @return a new path with the suffix added + */ public Path suffix(String suffix) { return new Path(getParent(), getName()+suffix); } @@ -402,7 +490,10 @@ public int compareTo(Object o) { return this.uri.compareTo(that.uri); } - /** Return the number of elements in this path. */ + /** + * Returns the number of elements in this path. + * @return the number of elements in this path + */ public int depth() { String path = uri.getPath(); int depth = 0; @@ -415,16 +506,28 @@ public int depth() { } /** - * Returns a qualified path object. + * Returns a qualified path object for the {@link FileSystem}'s working + * directory. * - * Deprecated - use {@link #makeQualified(URI, Path)} + * @param fs the target FileSystem + * @return a qualified path object for the FileSystem's working directory + * @deprecated use {@link #makeQualified(URI, Path)} */ @Deprecated public Path makeQualified(FileSystem fs) { return makeQualified(fs.getUri(), fs.getWorkingDirectory()); } - /** Returns a qualified path object. */ + /** + * Returns a qualified path object. + * + * @param defaultUri if this path is missing the scheme or authority + * components, borrow them from this URI + * @param workingDir if this path isn't absolute, treat it as relative to this + * working directory + * @return 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 + */ @InterfaceAudience.LimitedPrivate({"HDFS", "MapReduce"}) public Path makeQualified(URI defaultUri, Path workingDir ) { Path path = this;