HADOOP-9277. Improve javadoc for FileContext. Contributed by Andrew Wang.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1443710 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Suresh Srinivas 2013-02-07 20:38:29 +00:00
parent 362da383fd
commit c3d09010c7
2 changed files with 55 additions and 63 deletions

View File

@ -149,6 +149,8 @@ Trunk (Unreleased)
HADOOP-8924. Add maven plugin alternative to shell script to save
package-info.java. (Chris Nauroth via suresh)
HADOOP-9277. Improve javadoc for FileContext. (Andrew Wang via suresh)
BUG FIXES
HADOOP-8419. Fixed GzipCode NPE reset for IBM JDK. (Yu Li via eyang)

View File

@ -57,70 +57,60 @@ import org.apache.hadoop.security.token.Token;
import org.apache.hadoop.util.ShutdownHookManager;
/**
* The FileContext class provides an interface to the application writer for
* using the Hadoop file system.
* It provides a set of methods for the usual operation: create, open,
* list, etc
* The FileContext class provides an interface for users of the Hadoop
* file system. It exposes a number of file system operations, e.g. create,
* open, list.
*
* <p>
* <b> *** Path Names *** </b>
* <p>
* <h2>Path Names</h2>
*
* The Hadoop file system supports a URI name space and URI names.
* It offers a forest of file systems that can be referenced using fully
* qualified URIs.
* Two common Hadoop file systems implementations are
* The Hadoop file system supports a URI namespace and URI names. This enables
* multiple types of file systems to be referenced using fully-qualified URIs.
* Two common Hadoop file system implementations are
* <ul>
* <li> the local file system: file:///path
* <li> the hdfs file system hdfs://nnAddress:nnPort/path
* <li>the local file system: file:///path
* <li>the HDFS file system: hdfs://nnAddress:nnPort/path
* </ul>
*
* While URI names are very flexible, it requires knowing the name or address
* of the server. For convenience one often wants to access the default system
* in one's environment without knowing its name/address. This has an
* additional benefit that it allows one to change one's default fs
* (e.g. admin moves application from cluster1 to cluster2).
* The Hadoop file system also supports additional naming schemes besides URIs.
* Hadoop has the concept of a <i>default file system</i>, which implies a
* default URI scheme and authority. This enables <i>slash-relative names</i>
* relative to the default FS, which are more convenient for users and
* application writers. The default FS is typically set by the user's
* environment, though it can also be manually specified.
* <p>
*
* To facilitate this, Hadoop supports a notion of a default file system.
* The user can set his default file system, although this is
* typically set up for you in your environment via your default config.
* A default file system implies a default scheme and authority; slash-relative
* names (such as /for/bar) are resolved relative to that default FS.
* Similarly a user can also have working-directory-relative names (i.e. names
* not starting with a slash). While the working directory is generally in the
* same default FS, the wd can be in a different FS.
* Hadoop also supports <i>working-directory-relative</i> names, which are paths
* relative to the current working directory (similar to Unix). The working
* directory can be in a different file system than the default FS.
* <p>
* Hence Hadoop path names can be one of:
* <ul>
* <li> fully qualified URI: scheme://authority/path
* <li> slash relative names: /path relative to the default file system
* <li> wd-relative names: path relative to the working dir
* </ul>
* Thus, Hadoop path names can be specified as one of the following:
* <ul>
* <li>a fully-qualified URI: scheme://authority/path (e.g.
* hdfs://nnAddress:nnPort/foo/bar)
* <li>a slash-relative name: path relative to the default file system (e.g.
* /foo/bar)
* <li>a working-directory-relative name: path relative to the working dir (e.g.
* foo/bar)
* </ul>
* Relative paths with scheme (scheme:foo/bar) are illegal.
*
* <p>
* <b>****The Role of the FileContext and configuration defaults****</b>
* <p>
* The FileContext provides file namespace context for resolving file names;
* it also contains the umask for permissions, In that sense it is like the
* per-process file-related state in Unix system.
* These two properties
* <ul>
* <li> default file system i.e your slash)
* <li> umask
* </ul>
* in general, are obtained from the default configuration file
* in your environment, (@see {@link Configuration}).
*
* No other configuration parameters are obtained from the default config as
* far as the file context layer is concerned. All file system instances
* (i.e. deployments of file systems) have default properties; we call these
* server side (SS) defaults. Operation like create allow one to select many
* properties: either pass them in as explicit parameters or use
* the SS properties.
* <p>
* The file system related SS defaults are
* <h2>Role of FileContext and Configuration Defaults</h2>
*
* The FileContext is the analogue of per-process file-related state in Unix. It
* contains two properties:
*
* <ul>
* <li>the default file system (for resolving slash-relative names)
* <li>the umask (for file permissions)
* </ul>
* In general, these properties are obtained from the default configuration file
* in the user's environment (see {@link Configuration}).
*
* Further file system properties are specified on the server-side. File system
* operations default to using these server-side defaults unless otherwise
* specified.
* <p>
* The file system related server-side defaults are:
* <ul>
* <li> the home directory (default is "/user/userName")
* <li> the initial wd (only for local fs)
@ -131,34 +121,34 @@ import org.apache.hadoop.util.ShutdownHookManager;
* <li> checksum option. (checksumType and bytesPerChecksum)
* </ul>
*
* <p>
* <b> *** Usage Model for the FileContext class *** </b>
* <p>
* <h2>Example Usage</h2>
*
* Example 1: use the default config read from the $HADOOP_CONFIG/core.xml.
* Unspecified values come from core-defaults.xml in the release jar.
* <ul>
* <li> myFContext = FileContext.getFileContext(); // uses the default config
* // which has your default FS
* <li> myFContext.create(path, ...);
* <li> myFContext.setWorkingDir(path)
* <li> myFContext.setWorkingDir(path);
* <li> myFContext.open (path, ...);
* <li>...
* </ul>
* Example 2: Get a FileContext with a specific URI as the default FS
* <ul>
* <li> myFContext = FileContext.getFileContext(URI)
* <li> myFContext = FileContext.getFileContext(URI);
* <li> myFContext.create(path, ...);
* ...
* </ul>
* <li>...
* </ul>
* Example 3: FileContext with local file system as the default
* <ul>
* <li> myFContext = FileContext.getLocalFSFileContext()
* <li> myFContext = FileContext.getLocalFSFileContext();
* <li> myFContext.create(path, ...);
* <li> ...
* </ul>
* Example 4: Use a specific config, ignoring $HADOOP_CONFIG
* Generally you should not need use a config unless you are doing
* <ul>
* <li> configX = someConfigSomeOnePassedToYou.
* <li> configX = someConfigSomeOnePassedToYou;
* <li> myFContext = getFileContext(configX); // configX is not changed,
* // is passed down
* <li> myFContext.create(path, ...);