* * All user code that may potentially use the Hadoop Distributed - * File System should be written to use a FileSystem object. The - * Hadoop DFS is a multi-machine system that appears as a single - * disk. It's useful because of its fault tolerance and potentially - * very large capacity. - * + * File System should be written to use a FileSystem object or its + * successor, {@link FileContext}. + * *
* The local implementation is {@link LocalFileSystem} and distributed - * implementation is DistributedFileSystem. + * implementation is DistributedFileSystem. There are other implementations + * for object stores and (outside the Apache Hadoop codebase), + * third party filesystems. + *
+ * Notes + *
* This implementation throws an UnsupportedOperationException.
*
- * @return the protocol scheme for the FileSystem.
+ * @return the protocol scheme for this FileSystem.
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default).
*/
public String getScheme() {
- throw new UnsupportedOperationException("Not implemented by the " + getClass().getSimpleName() + " FileSystem implementation");
+ throw new UnsupportedOperationException("Not implemented by the "
+ + getClass().getSimpleName() + " FileSystem implementation");
}
- /** Returns a URI whose scheme and authority identify this FileSystem.*/
+ /**
+ * Returns a URI which identifies this FileSystem.
+ *
+ * @return the URI of this filesystem.
+ */
public abstract URI getUri();
-
+
/**
* Return a canonicalized form of this FileSystem's URI.
- *
+ *
* The default implementation simply calls {@link #canonicalizeUri(URI)}
* on the filesystem's own URI, so subclasses typically only need to
* implement that method.
@@ -251,16 +311,17 @@ public abstract class FileSystem extends Configured implements Closeable {
protected URI getCanonicalUri() {
return canonicalizeUri(getUri());
}
-
+
/**
* Canonicalize the given URI.
- *
- * This is filesystem-dependent, but may for example consist of
+ *
+ * This is implementation-dependent, and may for example consist of
* canonicalizing the hostname using DNS and adding the default
* port if not specified.
- *
+ *
* The default implementation simply fills in the default port if
- * not specified and if the filesystem has a default port.
+ * not specified and if {@link #getDefaultPort()} returns a
+ * default port.
*
* @return URI
* @see NetUtils#getCanonicalUri(URI, int)
@@ -278,12 +339,12 @@ public abstract class FileSystem extends Configured implements Closeable {
uri);
}
}
-
+
return uri;
}
-
+
/**
- * Get the default port for this file system.
+ * Get the default port for this FileSystem.
* @return the default port or 0 if there isn't one
*/
protected int getDefaultPort() {
@@ -296,25 +357,25 @@ public abstract class FileSystem extends Configured implements Closeable {
absOrFqPath.checkNotSchemeWithRelative();
absOrFqPath.checkNotRelative();
- // Uses the default file system if not fully qualified
+ // Uses the default FileSystem if not fully qualified
return get(absOrFqPath.toUri(), conf);
}
/**
- * Get a canonical service name for this file system. The token cache is
- * the only user of the canonical service name, and uses it to lookup this
- * filesystem's service tokens.
- * If file system provides a token of its own then it must have a canonical
- * name, otherwise canonical name can be null.
- *
- * Default Impl: If the file system has child file systems
- * (such as an embedded file system) then it is assumed that the fs has no
+ * Get a canonical service name for this FileSystem.
+ * The token cache is the only user of the canonical service name,
+ * and uses it to lookup this FileSystem's service tokens.
+ * If the file system provides a token of its own then it must have a canonical
+ * name, otherwise the canonical name can be null.
+ *
+ * Default implementation: If the FileSystem has child file systems
+ * (such as an embedded file system) then it is assumed that the FS has no
* tokens of its own and hence returns a null name; otherwise a service
* name is built using Uri and port.
- *
+ *
* @return a service string that uniquely identifies this file system, null
* if the filesystem does not implement tokens
- * @see SecurityUtil#buildDTServiceName(URI, int)
+ * @see SecurityUtil#buildDTServiceName(URI, int)
*/
@InterfaceAudience.LimitedPrivate({ "HDFS", "MapReduce" })
public String getCanonicalServiceName() {
@@ -323,28 +384,29 @@ public abstract class FileSystem extends Configured implements Closeable {
: null;
}
- /** @deprecated call #getUri() instead.*/
+ /** @deprecated call {@link #getUri()} instead.*/
@Deprecated
public String getName() { return getUri().toString(); }
- /** @deprecated call #get(URI,Configuration) instead. */
+ /** @deprecated call {@link #get(URI, Configuration)} instead. */
@Deprecated
public static FileSystem getNamed(String name, Configuration conf)
throws IOException {
return get(URI.create(fixName(name)), conf);
}
-
+
/** Update old-format filesystem names, for back-compatibility. This should
* eventually be replaced with a checkName() method that throws an exception
- * for old-format names. */
+ * for old-format names.
+ */
private static String fixName(String name) {
// convert old-format name to new-format name
if (name.equals("local")) { // "local" is now "file:///".
- LOG.warn("\"local\" is a deprecated filesystem name."
+ LOGGER.warn("\"local\" is a deprecated filesystem name."
+" Use \"file:///\" instead.");
name = "file:///";
} else if (name.indexOf('/')==-1) { // unqualified is "hdfs://"
- LOG.warn("\""+name+"\" is a deprecated filesystem name."
+ LOGGER.warn("\""+name+"\" is a deprecated filesystem name."
+" Use \"hdfs://"+name+"/\" instead.");
name = "hdfs://"+name;
}
@@ -352,19 +414,36 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * Get the local file system.
- * @param conf the configuration to configure the file system with
+ * Get the local FileSystem.
+ * @param conf the configuration to configure the FileSystem with
+ * if it is newly instantiated.
* @return a LocalFileSystem
+ * @throws IOException if somehow the local FS cannot be instantiated.
*/
public static LocalFileSystem getLocal(Configuration conf)
throws IOException {
return (LocalFileSystem)get(LocalFileSystem.NAME, conf);
}
- /** Returns the FileSystem for this URI's scheme and authority. The scheme
- * of the URI determines a configuration property name,
- * fs.scheme.class whose value names the FileSystem class.
- * The entire URI is passed to the FileSystem instance's initialize method.
+ /**
+ * Get a FileSystem for this URI's scheme and authority.
+ *
+ * if f == null : + * result = null + * elif f.getLen() <= start: + * result = [] + * else result = [ locations(FS, b) for b in blocks(FS, p, s, s+l)] + *+ * This call is most helpful with and distributed filesystem + * where the hostnames of machines that contain blocks of the given file + * can be determined. * - * The FileSystem will simply return an elt containing 'localhost'. + * The default implementation returns an array containing one element: + *
+ * BlockLocation( { "localhost:50010" }, { "localhost" }, 0, file.getLen())
+ * >
*
* @param file FilesStatus to get data from
* @param start offset into the given file
* @param len length for which to get locations for
+ * @throws IOException IO failure
*/
- public BlockLocation[] getFileBlockLocations(FileStatus file,
+ public BlockLocation[] getFileBlockLocations(FileStatus file,
long start, long len) throws IOException {
if (file == null) {
return null;
@@ -699,24 +817,28 @@ public abstract class FileSystem extends Configured implements Closeable {
return new BlockLocation[] {
new BlockLocation(name, host, 0, file.getLen()) };
}
-
/**
- * Return an array containing hostnames, offset and size of
- * portions of the given file. For a nonexistent
- * file or regions, null will be returned.
+ * Return an array containing hostnames, offset and size of
+ * portions of the given file. For a nonexistent
+ * file or regions, {@code null} is returned.
*
- * This call is most helpful with DFS, where it returns
- * hostnames of machines that contain the given file.
+ * This call is most helpful with location-aware distributed
+ * filesystems, where it returns hostnames of machines that
+ * contain the given file.
*
- * The FileSystem will simply return an elt containing 'localhost'.
+ * A FileSystem will normally return the equivalent result
+ * of passing the {@code FileStatus} of the path to
+ * {@link #getFileBlockLocations(FileStatus, long, long)}
*
* @param p path is used to identify an FS since an FS could have
* another FS that it could be delegating the call to
* @param start offset into the given file
* @param len length for which to get locations for
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException IO failure
*/
- public BlockLocation[] getFileBlockLocations(Path p,
+ public BlockLocation[] getFileBlockLocations(Path p,
long start, long len) throws IOException {
if (p == null) {
throw new NullPointerException();
@@ -724,46 +846,47 @@ public abstract class FileSystem extends Configured implements Closeable {
FileStatus file = getFileStatus(p);
return getFileBlockLocations(file, start, len);
}
-
+
/**
- * Return a set of server default configuration values
+ * Return a set of server default configuration values.
* @return server default configuration values
- * @throws IOException
+ * @throws IOException IO failure
* @deprecated use {@link #getServerDefaults(Path)} instead
*/
@Deprecated
public FsServerDefaults getServerDefaults() throws IOException {
- Configuration conf = getConf();
- // CRC32 is chosen as default as it is available in all
+ Configuration config = getConf();
+ // CRC32 is chosen as default as it is available in all
// releases that support checksum.
// The client trash configuration is ignored.
- return new FsServerDefaults(getDefaultBlockSize(),
- conf.getInt("io.bytes.per.checksum", 512),
- 64 * 1024,
+ return new FsServerDefaults(getDefaultBlockSize(),
+ config.getInt("io.bytes.per.checksum", 512),
+ 64 * 1024,
getDefaultReplication(),
- conf.getInt(IO_FILE_BUFFER_SIZE_KEY, IO_FILE_BUFFER_SIZE_DEFAULT),
+ config.getInt(IO_FILE_BUFFER_SIZE_KEY, IO_FILE_BUFFER_SIZE_DEFAULT),
false,
FS_TRASH_INTERVAL_DEFAULT,
DataChecksum.Type.CRC32);
}
/**
- * Return a set of server default configuration values
+ * Return a set of server default configuration values.
* @param p path is used to identify an FS since an FS could have
* another FS that it could be delegating the call to
* @return server default configuration values
- * @throws IOException
+ * @throws IOException IO failure
*/
public FsServerDefaults getServerDefaults(Path p) throws IOException {
return getServerDefaults();
}
/**
- * Return the fully-qualified path of path f resolving the path
- * through any symlinks or mount point
+ * Return the fully-qualified path of path, resolving the path
+ * through any symlinks or mount point.
* @param p path to be resolved
- * @return fully qualified path
- * @throws FileNotFoundException
+ * @return fully qualified path
+ * @throws FileNotFoundException if the path is not present
+ * @throws IOException for any other error
*/
public Path resolvePath(final Path p) throws IOException {
checkPath(p);
@@ -774,13 +897,15 @@ public abstract class FileSystem extends Configured implements Closeable {
* Opens an FSDataInputStream at the indicated Path.
* @param f the file name to open
* @param bufferSize the size of the buffer to be used.
+ * @throws IOException IO failure
*/
public abstract FSDataInputStream open(Path f, int bufferSize)
throws IOException;
-
+
/**
* Opens an FSDataInputStream at the indicated Path.
* @param f the file to open
+ * @throws IOException IO failure
*/
public FSDataInputStream open(Path f) throws IOException {
return open(f, getConf().getInt(IO_FILE_BUFFER_SIZE_KEY,
@@ -791,6 +916,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* Create an FSDataOutputStream at the indicated Path.
* Files are overwritten by default.
* @param f the file to create
+ * @throws IOException IO failure
*/
public FSDataOutputStream create(Path f) throws IOException {
return create(f, true);
@@ -801,10 +927,11 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param f the file to create
* @param overwrite if a file with this name already exists, then if true,
* the file will be overwritten, and if false an exception will be thrown.
+ * @throws IOException IO failure
*/
public FSDataOutputStream create(Path f, boolean overwrite)
throws IOException {
- return create(f, overwrite,
+ return create(f, overwrite,
getConf().getInt(IO_FILE_BUFFER_SIZE_KEY,
IO_FILE_BUFFER_SIZE_DEFAULT),
getDefaultReplication(f),
@@ -817,10 +944,11 @@ public abstract class FileSystem extends Configured implements Closeable {
* Files are overwritten by default.
* @param f the file to create
* @param progress to report progress
+ * @throws IOException IO failure
*/
- public FSDataOutputStream create(Path f, Progressable progress)
+ public FSDataOutputStream create(Path f, Progressable progress)
throws IOException {
- return create(f, true,
+ return create(f, true,
getConf().getInt(IO_FILE_BUFFER_SIZE_KEY,
IO_FILE_BUFFER_SIZE_DEFAULT),
getDefaultReplication(f),
@@ -832,10 +960,11 @@ public abstract class FileSystem extends Configured implements Closeable {
* Files are overwritten by default.
* @param f the file to create
* @param replication the replication factor
+ * @throws IOException IO failure
*/
public FSDataOutputStream create(Path f, short replication)
throws IOException {
- return create(f, true,
+ return create(f, true,
getConf().getInt(IO_FILE_BUFFER_SIZE_KEY,
IO_FILE_BUFFER_SIZE_DEFAULT),
replication,
@@ -849,65 +978,70 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param f the file to create
* @param replication the replication factor
* @param progress to report progress
+ * @throws IOException IO failure
*/
- public FSDataOutputStream create(Path f, short replication,
+ public FSDataOutputStream create(Path f, short replication,
Progressable progress) throws IOException {
- return create(f, true,
+ return create(f, true,
getConf().getInt(IO_FILE_BUFFER_SIZE_KEY,
IO_FILE_BUFFER_SIZE_DEFAULT),
replication, getDefaultBlockSize(f), progress);
}
-
+
/**
* Create an FSDataOutputStream at the indicated Path.
- * @param f the file name to create
- * @param overwrite if a file with this name already exists, then if true,
+ * @param f the file to create
+ * @param overwrite if a path with this name already exists, then if true,
* the file will be overwritten, and if false an error will be thrown.
* @param bufferSize the size of the buffer to be used.
+ * @throws IOException IO failure
*/
- public FSDataOutputStream create(Path f,
+ public FSDataOutputStream create(Path f,
boolean overwrite,
int bufferSize
) throws IOException {
- return create(f, overwrite, bufferSize,
+ return create(f, overwrite, bufferSize,
getDefaultReplication(f),
getDefaultBlockSize(f));
}
-
+
/**
- * Create an FSDataOutputStream at the indicated Path with write-progress
- * reporting.
+ * Create an {@link FSDataOutputStream} at the indicated Path
+ * with write-progress reporting.
+ *
+ * The frequency of callbacks is implementation-specific; it may be "none".
* @param f the path of the file to open
* @param overwrite if a file with this name already exists, then if true,
* the file will be overwritten, and if false an error will be thrown.
* @param bufferSize the size of the buffer to be used.
+ * @throws IOException IO failure
*/
- public FSDataOutputStream create(Path f,
+ public FSDataOutputStream create(Path f,
boolean overwrite,
int bufferSize,
Progressable progress
) throws IOException {
- return create(f, overwrite, bufferSize,
+ return create(f, overwrite, bufferSize,
getDefaultReplication(f),
getDefaultBlockSize(f), progress);
}
-
-
+
+
/**
* Create an FSDataOutputStream at the indicated Path.
* @param f the file name to open
* @param overwrite if a file with this name already exists, then if true,
* the file will be overwritten, and if false an error will be thrown.
* @param bufferSize the size of the buffer to be used.
- * @param replication required block replication for the file.
+ * @param replication required block replication for the file.
+ * @throws IOException IO failure
*/
- public FSDataOutputStream create(Path f,
- boolean overwrite,
- int bufferSize,
- short replication,
- long blockSize
- ) throws IOException {
+ public FSDataOutputStream create(Path f,
+ boolean overwrite,
+ int bufferSize,
+ short replication,
+ long blockSize) throws IOException {
return create(f, overwrite, bufferSize, replication, blockSize, null);
}
@@ -918,15 +1052,15 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param overwrite if a file with this name already exists, then if true,
* the file will be overwritten, and if false an error will be thrown.
* @param bufferSize the size of the buffer to be used.
- * @param replication required block replication for the file.
+ * @param replication required block replication for the file.
+ * @throws IOException IO failure
*/
public FSDataOutputStream create(Path f,
- boolean overwrite,
- int bufferSize,
- short replication,
- long blockSize,
- Progressable progress
- ) throws IOException {
+ boolean overwrite,
+ int bufferSize,
+ short replication,
+ long blockSize,
+ Progressable progress) throws IOException {
return this.create(f, FsPermission.getFileDefault().applyUMask(
FsPermission.getUMask(getConf())), overwrite, bufferSize,
replication, blockSize, progress);
@@ -943,7 +1077,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param replication required block replication for the file.
* @param blockSize block size
* @param progress the progress reporter
- * @throws IOException
+ * @throws IOException IO failure
* @see #setPermission(Path, FsPermission)
*/
public abstract FSDataOutputStream create(Path f,
@@ -953,7 +1087,7 @@ public abstract class FileSystem extends Configured implements Closeable {
short replication,
long blockSize,
Progressable progress) throws IOException;
-
+
/**
* Create an FSDataOutputStream at the indicated Path with write-progress
* reporting.
@@ -964,7 +1098,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param replication required block replication for the file.
* @param blockSize block size
* @param progress the progress reporter
- * @throws IOException
+ * @throws IOException IO failure
* @see #setPermission(Path, FsPermission)
*/
public FSDataOutputStream create(Path f,
@@ -977,10 +1111,10 @@ public abstract class FileSystem extends Configured implements Closeable {
return create(f, permission, flags, bufferSize, replication,
blockSize, progress, null);
}
-
+
/**
* Create an FSDataOutputStream at the indicated Path with a custom
- * checksum option
+ * checksum option.
* @param f the file name to open
* @param permission file permission
* @param flags {@link CreateFlag}s to use for this stream.
@@ -990,7 +1124,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param progress the progress reporter
* @param checksumOpt checksum parameter. If null, the values
* found in conf will be used.
- * @throws IOException
+ * @throws IOException IO failure
* @see #setPermission(Path, FsPermission)
*/
public FSDataOutputStream create(Path f,
@@ -1004,27 +1138,31 @@ public abstract class FileSystem extends Configured implements Closeable {
// Checksum options are ignored by default. The file systems that
// implement checksum need to override this method. The full
// support is currently only available in DFS.
- return create(f, permission, flags.contains(CreateFlag.OVERWRITE),
+ return create(f, permission, flags.contains(CreateFlag.OVERWRITE),
bufferSize, replication, blockSize, progress);
}
- /*.
+ /**
* This create has been added to support the FileContext that processes
- * the permission
- * with umask before calling this method.
+ * the permission with umask before calling this method.
* This a temporary method added to support the transition from FileSystem
* to FileContext for user applications.
+ * @throws IOException IO failure
*/
@Deprecated
protected FSDataOutputStream primitiveCreate(Path f,
- FsPermission absolutePermission, EnumSet* If OVERWRITE option is not passed as an argument, rename fails @@ -1269,12 +1423,17 @@ public abstract class FileSystem extends Configured implements Closeable { * implementation. Please refer to the file system documentation for * details. This default implementation is non atomic. *
- * This method is deprecated since it is a temporary method added to - * support the transition from FileSystem to FileContext for user + * This method is deprecated since it is a temporary method added to + * support the transition from FileSystem to FileContext for user * applications. - * + * * @param src path to be renamed * @param dst new path after rename + * @throws FileNotFoundException src path does not exist, or the parent + * path of dst does not exist. + * @throws FileAlreadyExistsException dest path exists and is a file + * @throws ParentNotDirectoryException if the parent path of dest is not + * a directory * @throws IOException on failure */ @Deprecated @@ -1339,10 +1498,10 @@ public abstract class FileSystem extends Configured implements Closeable { /** * Truncate the file in the indicated path to the indicated size. *
false if a background process of adjusting the length of
* the last block has been started, and clients should wait for it to
* complete before proceeding with further file updates.
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default).
*/
public boolean truncate(Path f, long newLength) throws IOException {
throw new UnsupportedOperationException("Not implemented by the " +
getClass().getSimpleName() + " FileSystem implementation");
}
-
+
/**
- * Delete a file
+ * Delete a file/directory.
* @deprecated Use {@link #delete(Path, boolean)} instead.
*/
@Deprecated
public boolean delete(Path f) throws IOException {
return delete(f, true);
}
-
+
/** Delete a file.
*
* @param f the path to delete.
- * @param recursive if path is a directory and set to
+ * @param recursive if path is a directory and set to
* true, the directory is deleted else throws an exception. In
- * case of a file the recursive can be set to either true or false.
- * @return true if delete is successful else false.
- * @throws IOException
+ * case of a file the recursive can be set to either true or false.
+ * @return true if delete is successful else false.
+ * @throws IOException IO failure
*/
public abstract boolean delete(Path f, boolean recursive) throws IOException;
/**
- * Mark a path to be deleted when FileSystem is closed.
- * When the JVM shuts down,
- * all FileSystem objects will be closed automatically.
- * Then,
- * the marked path will be deleted as a result of closing the FileSystem.
+ * Mark a path to be deleted when its FileSystem is closed.
+ * When the JVM shuts down cleanly, all cached FileSystem objects will be
+ * closed automatically —these the marked paths will be deleted as a result.
*
- * The path has to exist in the file system.
- *
+ * If a FileSystem instance is not cached, i.e. has been created with
+ * {@link #createFileSystem(URI, Configuration)}, then the paths will
+ * be deleted in when {@link #close()} is called on that instance.
+ *
+ * The path must exist in the filesystem at the time of the method call;
+ * it does not have to exist at the time of JVM shutdown.
+ *
+ * Notes
+ * results.
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException see specific implementation
*/
private void listStatus(ArrayList
* Does not guarantee to return the List of files/directories status in a
* sorted order.
- *
+ *
* @param f
* a path name
* @param filter
* the user-supplied path filter
* @return an array of FileStatus objects for the files under the given path
* after applying the filter
- * @throws FileNotFoundException when the path does not exist;
- * IOException see specific implementation
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException see specific implementation
*/
- public FileStatus[] listStatus(Path f, PathFilter filter)
+ public FileStatus[] listStatus(Path f, PathFilter filter)
throws FileNotFoundException, IOException {
- ArrayList
* Does not guarantee to return the List of files/directories status in a
* sorted order.
- *
+ *
* @param files
* a list of paths
* @return a list of statuses for the files under the given paths after
* applying the filter default Path filter
- * @throws FileNotFoundException when the path does not exist;
- * IOException see specific implementation
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException see specific implementation
*/
public FileStatus[] listStatus(Path[] files)
throws FileNotFoundException, IOException {
@@ -1671,15 +1872,15 @@ public abstract class FileSystem extends Configured implements Closeable {
*
* Does not guarantee to return the List of files/directories status in a
* sorted order.
- *
+ *
* @param files
* a list of paths
* @param filter
* the user-supplied path filter
* @return a list of statuses for the files under the given paths after
* applying the filter
- * @throws FileNotFoundException when the path does not exist;
- * IOException see specific implementation
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException see specific implementation
*/
public FileStatus[] listStatus(Path[] files, PathFilter filter)
throws FileNotFoundException, IOException {
@@ -1693,7 +1894,7 @@ public abstract class FileSystem extends Configured implements Closeable {
/**
* Return all the files that match filePattern and are not checksum
* files. Results are sorted by their names.
- *
+ *
*
* A filename pattern is composed of regular characters and
* special pattern matching characters, which are:
@@ -1733,7 +1934,7 @@ public abstract class FileSystem extends Configured implements Closeable {
*
*
*
+ * The default implementation calls {@link #getFileStatus(Path)}
* and checks the returned permissions against the requested permissions.
- * Note that the getFileStatus call will be subject to authorization checks.
+ *
+ * Note that the {@link #getFileStatus(Path)} call will be subject to
+ * authorization checks.
* Typically, this requires search (execute) permissions on each directory in
* the path's prefix, but this is implementation-defined. Any file system
* that provides a richer authorization model (such as ACLs) may override the
@@ -2303,11 +2539,12 @@ public abstract class FileSystem extends Configured implements Closeable {
*
* @param stat FileStatus to check
* @param mode type of access to check
+ * @throws AccessControlException if access is denied
* @throws IOException for any error
*/
@InterfaceAudience.Private
static void checkAccessPermissions(FileStatus stat, FsAction mode)
- throws IOException {
+ throws AccessControlException, IOException {
FsPermission perm = stat.getPermission();
UserGroupInformation ugi = UserGroupInformation.getCurrentUser();
String user = ugi.getShortUserName();
@@ -2330,7 +2567,7 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * See {@link FileContext#fixRelativePart}
+ * See {@link FileContext#fixRelativePart}.
*/
protected Path fixRelativePart(Path p) {
if (p.isUriPathAbsolute()) {
@@ -2341,12 +2578,12 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * See {@link FileContext#createSymlink(Path, Path, boolean)}
+ * See {@link FileContext#createSymlink(Path, Path, boolean)}.
*/
public void createSymlink(final Path target, final Path link,
final boolean createParent) throws AccessControlException,
FileAlreadyExistsException, FileNotFoundException,
- ParentNotDirectoryException, UnsupportedFileSystemException,
+ ParentNotDirectoryException, UnsupportedFileSystemException,
IOException {
// Supporting filesystems should override this method
throw new UnsupportedOperationException(
@@ -2354,7 +2591,9 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * See {@link FileContext#getFileLinkStatus(Path)}
+ * See {@link FileContext#getFileLinkStatus(Path)}.
+ * @throws FileNotFoundException when the path does not exist
+ * @throws IOException see specific implementation
*/
public FileStatus getFileLinkStatus(final Path f)
throws AccessControlException, FileNotFoundException,
@@ -2364,14 +2603,16 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * See {@link AbstractFileSystem#supportsSymlinks()}
+ * See {@link AbstractFileSystem#supportsSymlinks()}.
*/
public boolean supportsSymlinks() {
return false;
}
/**
- * See {@link FileContext#getLinkTarget(Path)}
+ * See {@link FileContext#getLinkTarget(Path)}.
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public Path getLinkTarget(Path f) throws IOException {
// Supporting filesystems should override this method
@@ -2380,7 +2621,9 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * See {@link AbstractFileSystem#getLinkTarget(Path)}
+ * See {@link AbstractFileSystem#getLinkTarget(Path)}.
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
protected Path resolveLink(Path f) throws IOException {
// Supporting filesystems should override this method
@@ -2389,12 +2632,13 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * Get the checksum of a file.
+ * Get the checksum of a file, if the FS supports checksums.
*
* @param f The file path
* @return The file checksum. The default return value is null,
* which indicates that no checksum algorithm is implemented
* in the corresponding FileSystem.
+ * @throws IOException IO failure
*/
public FileChecksum getFileChecksum(Path f) throws IOException {
return getFileChecksum(f, Long.MAX_VALUE);
@@ -2405,7 +2649,8 @@ public abstract class FileSystem extends Configured implements Closeable {
* specific length.
* @param f The file path
* @param length The length of the file range for checksum calculation
- * @return The file checksum.
+ * @return The file checksum or null if checksums are not supported.
+ * @throws IOException IO failure
*/
public FileChecksum getFileChecksum(Path f, final long length)
throws IOException {
@@ -2413,8 +2658,8 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * Set the verify checksum flag. This is only applicable if the
- * corresponding FileSystem supports checksum. By default doesn't do anything.
+ * Set the verify checksum flag. This is only applicable if the
+ * corresponding filesystem supports checksums. By default doesn't do anything.
* @param verifyChecksum Verify checksum flag
*/
public void setVerifyChecksum(boolean verifyChecksum) {
@@ -2422,9 +2667,9 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * Set the write checksum flag. This is only applicable if the
- * corresponding FileSystem supports checksum. By default doesn't do anything.
- * @param writeChecksum Write checsum flag
+ * Set the write checksum flag. This is only applicable if the
+ * corresponding filesystem supports checksums. By default doesn't do anything.
+ * @param writeChecksum Write checksum flag
*/
public void setWriteChecksum(boolean writeChecksum) {
//doesn't do anything
@@ -2432,9 +2677,9 @@ public abstract class FileSystem extends Configured implements Closeable {
/**
* Returns a status object describing the use and capacity of the
- * file system. If the file system has multiple partitions, the
+ * filesystem. If the filesystem has multiple partitions, the
* use and capacity of the root partition is reflected.
- *
+ *
* @return a FsStatus object
* @throws IOException
* see specific implementation
@@ -2445,11 +2690,11 @@ public abstract class FileSystem extends Configured implements Closeable {
/**
* Returns a status object describing the use and capacity of the
- * file system. If the file system has multiple partitions, the
+ * filesystem. If the filesystem has multiple partitions, the
* use and capacity of the partition pointed to by the specified
* path is reflected.
* @param p Path for which status should be obtained. null means
- * the default partition.
+ * the default partition.
* @return a FsStatus object
* @throws IOException
* see specific implementation
@@ -2462,6 +2707,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* Set permission of a path.
* @param p The path
* @param permission permission
+ * @throws IOException IO failure
*/
public void setPermission(Path p, FsPermission permission
) throws IOException {
@@ -2473,20 +2719,22 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param p The path
* @param username If it is null, the original username remains unchanged.
* @param groupname If it is null, the original groupname remains unchanged.
+ * @throws IOException IO failure
*/
public void setOwner(Path p, String username, String groupname
) throws IOException {
}
/**
- * Set access time of a file
+ * Set access time of a file.
* @param p The path
* @param mtime Set the modification time of this file.
- * The number of milliseconds since Jan 1, 1970.
+ * The number of milliseconds since Jan 1, 1970.
* A value of -1 means that this call should not set modification time.
* @param atime Set the access time of this file.
- * The number of milliseconds since Jan 1, 1970.
+ * The number of milliseconds since Jan 1, 1970.
* A value of -1 means that this call should not set access time.
+ * @throws IOException IO failure
*/
public void setTimes(Path p, long mtime, long atime
) throws IOException {
@@ -2496,47 +2744,56 @@ public abstract class FileSystem extends Configured implements Closeable {
* Create a snapshot with a default name.
* @param path The directory where snapshots will be taken.
* @return the snapshot path.
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
*/
public final Path createSnapshot(Path path) throws IOException {
return createSnapshot(path, null);
}
/**
- * Create a snapshot
+ * Create a snapshot.
* @param path The directory where snapshots will be taken.
* @param snapshotName The name of the snapshot
* @return the snapshot path.
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
*/
public Path createSnapshot(Path path, String snapshotName)
throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
+ " doesn't support createSnapshot");
}
-
+
/**
- * Rename a snapshot
+ * Rename a snapshot.
* @param path The directory path where the snapshot was taken
* @param snapshotOldName Old name of the snapshot
* @param snapshotNewName New name of the snapshot
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void renameSnapshot(Path path, String snapshotOldName,
String snapshotNewName) throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
+ " doesn't support renameSnapshot");
}
-
+
/**
- * Delete a snapshot of a directory
+ * Delete a snapshot of a directory.
* @param path The directory that the to-be-deleted snapshot belongs to
* @param snapshotName The name of the snapshot
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void deleteSnapshot(Path path, String snapshotName)
throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
+ " doesn't support deleteSnapshot");
}
-
+
/**
* Modifies ACL entries of files and directories. This method can add new ACL
* entries or modify the permissions on existing ACL entries. All existing
@@ -2546,6 +2803,8 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param path Path to modify
* @param aclSpec List
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to modify
* @param name xattr name.
* @param value xattr value.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void setXAttr(Path path, String name, byte[] value)
throws IOException {
@@ -2641,14 +2912,16 @@ public abstract class FileSystem extends Configured implements Closeable {
* Set an xattr of a file or directory.
* The name must be prefixed with the namespace followed by ".". For example,
* "user.attr".
- *
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to modify
* @param name xattr name.
* @param value xattr value.
* @param flag xattr set flag
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void setXAttr(Path path, String name, byte[] value,
EnumSet
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to get extended attribute
* @param name xattr name.
* @return byte[] xattr value.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public byte[] getXAttr(Path path, String name) throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
@@ -2677,12 +2952,14 @@ public abstract class FileSystem extends Configured implements Closeable {
* Get all of the xattr name/value pairs for a file or directory.
* Only those xattrs which the logged-in user has permissions to view
* are returned.
- *
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to get extended attributes
* @return Map describing the XAttrs of the file or directory
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public Map
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to get extended attributes
* @param names XAttr names.
* @return Map describing the XAttrs of the file or directory
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public Map
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to get extended attributes
* @return List
* Refer to the HDFS extended attributes user documentation for details.
*
* @param path Path to remove extended attribute
* @param name xattr name
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void removeXAttr(Path path, String name) throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
@@ -2746,7 +3029,9 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param policyName the name of the target storage policy. The list
* of supported Storage policies can be retrieved
* via {@link #getAllStoragePolicies}.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void setStoragePolicy(final Path src, final String policyName)
throws IOException {
@@ -2757,7 +3042,9 @@ public abstract class FileSystem extends Configured implements Closeable {
/**
* Unset the storage policy set for a given file or directory.
* @param src file or directory path.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public void unsetStoragePolicy(final Path src) throws IOException {
throw new UnsupportedOperationException(getClass().getSimpleName()
@@ -2769,7 +3056,9 @@ public abstract class FileSystem extends Configured implements Closeable {
*
* @param src file or directory path.
* @return storage policy for give file.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public BlockStoragePolicySpi getStoragePolicy(final Path src)
throws IOException {
@@ -2781,7 +3070,9 @@ public abstract class FileSystem extends Configured implements Closeable {
* Retrieve all the storage policies supported by this file system.
*
* @return all storage policies supported by this filesystem.
- * @throws IOException
+ * @throws IOException IO failure
+ * @throws UnsupportedOperationException if the operation is unsupported
+ * (default outcome).
*/
public Collection getAllStoragePolicies()
throws IOException {
@@ -2794,7 +3085,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* is deleted.
*
* @param path the trash root of the path to be determined.
- * @return the default implementation returns "/user/$USER/.Trash".
+ * @return the default implementation returns {@code /user/$USER/.Trash}
*/
public Path getTrashRoot(Path path) {
return this.makeQualified(new Path(getHomeDirectory().toUri().getPath(),
@@ -2807,7 +3098,7 @@ public abstract class FileSystem extends Configured implements Closeable {
* @param allUsers return trash roots for all users if true.
* @return all the trash root directories.
* Default FileSystem returns .Trash under users' home directories if
- * /user/$USER/.Trash exists.
+ * {@code /user/$USER/.Trash} exists.
*/
public Collectionf does not exist
@@ -1791,12 +1994,12 @@ public abstract class FileSystem extends Configured implements Closeable {
}
/**
- * Listing a directory
+ * List a directory.
* The returned results include its block location if it is a file
* The results are filtered by the given path filter
* @param f a path
* @param filter a path filter
- * @return an iterator that traverses statuses of the files/directories
+ * @return an iterator that traverses statuses of the files/directories
* in the given path
* @throws FileNotFoundException if f does not exist
* @throws IOException if any I/O error occurred
@@ -1874,14 +2077,17 @@ public abstract class FileSystem extends Configured implements Closeable {
/**
* Returns a remote iterator so that followup calls are made on demand
- * while consuming the entries. Each file system implementation should
+ * while consuming the entries. Each FileSystem implementation should
* override this method and provide a more efficient implementation, if
- * possible.
+ * possible.
+ *
* Does not guarantee to return the iterator that traverses statuses
* of the files in a sorted order.
*
* @param p target path
* @return remote iterator
+ * @throws FileNotFoundException if p does not exist
+ * @throws IOException if any I/O error occurred
*/
public RemoteIterator
+ * If the path is a directory,
* if recursive is false, returns files in the directory;
* if recursive is true, return files in the subtree rooted at the path.
* If the path is a file, return the file's status and block locations.
- *
+ *
* @param f is the path
* @param recursive if the subdirectories need to be traversed recursively
*
* @return an iterator that traverses statuses of the files
*
* @throws FileNotFoundException when the path does not exist;
- * IOException see specific implementation
+ * @throws IOException see specific implementation
*/
public RemoteIterator