From 611ff4ec89c1b078134f8491c527104f4ab56440 Mon Sep 17 00:00:00 2001
From: Suresh Srinivas <suresh@apache.org>
Date: Fri, 12 Oct 2012 19:03:10 +0000
Subject: [PATCH] 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/CHANGES.txt                 |  2 ++
 .../java/org/apache/hadoop/fs/FileSystem.java | 29 +++++++++----------
 .../org/apache/hadoop/fs/GlobExpander.java    | 24 +++++++++++----
 3 files changed, 35 insertions(+), 20 deletions(-)

diff --git a/hadoop-common-project/hadoop-common/CHANGES.txt b/hadoop-common-project/hadoop-common/CHANGES.txt
index 23e070a01e7..2bc5970ac58 100644
--- a/hadoop-common-project/hadoop-common/CHANGES.txt
+++ b/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.
diff --git a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java
index e7808129832..a2bf0f2efee 100644
--- a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java
+++ b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java
@@ -1391,11 +1391,11 @@ public abstract class FileSystem extends Configured implements Closeable {
   }
 
   final private static PathFilter DEFAULT_FILTER = new PathFilter() {
-      @Override
-      public boolean accept(Path file) {
-        return true;
-      }     
-    };
+    @Override
+    public boolean accept(Path file) {
+      return true;
+    }
+  };
     
   /**
    * List the statuses of the files/directories in the given path if the path is
@@ -1559,17 +1559,16 @@ public abstract class FileSystem extends Configured implements Closeable {
   }
   
   /**
-   * Return an array of FileStatus objects whose path names match pathPattern
-   * and is accepted by the user-supplied path filter. 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. 
+   * Return an array of FileStatus objects whose path names match
+   * {@code pathPattern} and is accepted by the user-supplied path filter.
+   * Results are sorted by their path names.
    * 
-   * @param pathPattern
-   *          a regular expression specifying the path pattern
-   * @param filter
-   *          a user-supplied path filter
-   * @return an array of FileStatus objects
+   * @param pathPattern a regular expression specifying the path pattern
+   * @param filter a user-supplied path filter
+   * @return null if {@code pathPattern} has no glob and the path does not exist
+   *         an empty array if {@code pathPattern} has a glob and no path
+   *         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)
diff --git a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/GlobExpander.java b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/GlobExpander.java
index ef514ca2c4a..dff8b70ca95 100644
--- a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/GlobExpander.java
+++ b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/GlobExpander.java
@@ -39,12 +39,26 @@ class GlobExpander {
   }
   
   /**
-   * 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
-   * slash character ("/") in a curly bracket pair.
+   * 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 slash
+   * 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 
+   * @throws IOException
    */
   public static List<String> expand(String filePattern) throws IOException {
     List<String> fullyExpanded = new ArrayList<String>();
@@ -65,7 +79,7 @@ class GlobExpander {
   /**
    * 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 
    */