HADOOP-8910. Add examples to GlobExpander#expand method. Contributed by Suresh Srinivas.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@1397691 13f79535-47bb-0310-9956-ffa450edef68

hadoop-common-project/hadoop-common/CHANGES.txt

@@ -122,6 +122,8 @@ Trunk (Unreleased)
     HADOOP-8864. Addendum to HADOOP-8840: Add a coloring case for +0 results
     too. (harsh)
 
+    HADOOP-8910. Add examples to GlobExpander#expand method. (suresh)
+
   BUG FIXES
 
     HADOOP-8177. MBeans shouldn't try to register when it fails to create MBeanName.

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java

@@ -1559,17 +1559,16 @@ public FileStatus[] globStatus(Path pathPattern) throws IOException {
   }
   
   /**
-   * Return an array of FileStatus objects whose path names match pathPattern
+   * Return an array of FileStatus objects whose path names match
-   * and is accepted by the user-supplied path filter. Results are sorted by
+   * {@code pathPattern} and is accepted by the user-supplied path filter.
-   * their path names.
+   * Results are sorted by their path names.
-   * Return null if pathPattern has no glob and the path does not exist.
-   * Return an empty array if pathPattern has a glob and no path matches it. 
    * 
-   * @param pathPattern
+   * @param pathPattern a regular expression specifying the path pattern
-   *          a regular expression specifying the path pattern
+   * @param filter a user-supplied path filter
-   * @param filter
+   * @return null if {@code pathPattern} has no glob and the path does not exist
-   *          a user-supplied path filter
+   *         an empty array if {@code pathPattern} has a glob and no path
-   * @return an array of FileStatus objects
+   *         matches it else an array of {@link FileStatus} objects matching the
+   *         pattern
    * @throws IOException if any I/O error occurs when fetching file status
    */
   public FileStatus[] globStatus(Path pathPattern, PathFilter filter)

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/GlobExpander.java

@@ -40,8 +40,22 @@ public StringWithOffset(String string, int offset) {
   
   /**
    * Expand globs in the given <code>filePattern</code> into a collection of
-   * file patterns so that in the expanded set no file pattern has a
+   * file patterns so that in the expanded set no file pattern has a slash
-   * slash character ("/") in a curly bracket pair.
+   * character ("/") in a curly bracket pair.
+   * <p>
+   * Some examples of how the filePattern is expanded:<br>
+   * <pre>
+   * <b>
+   * filePattern         - Expanded file pattern </b>
+   * {a/b}               - a/b
+   * /}{a/b}             - /}a/b
+   * p{a/b,c/d}s         - pa/bs, pc/ds
+   * {a/b,c/d,{e,f}}     - a/b, c/d, {e,f}
+   * {a/b,c/d}{e,f}      - a/b{e,f}, c/d{e,f}
+   * {a,b}/{b,{c/d,e/f}} - {a,b}/b, {a,b}/c/d, {a,b}/e/f
+   * {a,b}/{c/\d}        - {a,b}/c/d
+   * </pre>
+   * 
    * @param filePattern
    * @return expanded file patterns
    * @throws IOException
@@ -65,7 +79,7 @@ public static List<String> expand(String filePattern) throws IOException {
   /**
    * Expand the leftmost outer curly bracket pair containing a
    * slash character ("/") in <code>filePattern</code>.
-   * @param filePattern
+   * @param filePatternWithOffset
    * @return expanded file patterns
    * @throws IOException 
    */