From 61c4e39067777633ea5d6d02f7493b4c459aef20 Mon Sep 17 00:00:00 2001
From: Dave Borowitz <dborowitz@google.com>
Date: Thu, 7 Jun 2012 12:08:48 -0700
Subject: [PATCH] Expand RegexPipeline documentation

Include some behaviors that were not clear to me until I had used it a
few times.

Warn about broken behavior for capture groups that do not match. It
would be nice to support these, but even for the cases where it's
clear what the behavior should be, it would be infeasible to
implement.

For example, consider the second group of the regex "(/a)/b(/c)?"
matched against the path "/a/b". We might want getServletPath() to
return "/a/b" and getPathInfo() to return null, but this is hard to
implement: there's no easy way to say "the substring up to the point
where (/c) would have matched if it were in the string even though
it's not." And even if we could, it's not clear there is even a right
answer in the general case.

Moreover, ideally we could warn about such broken patterns at servlet
initialization time, rather than at runtime, but even answering the
question of whether there are capture groups that might not match
requires more customized regular expression parsing than we want to
embark on. Hence, the best we can do is document how it fails.

Change-Id: I7bd5011f5bd387f9345a0e79b22a4d7ed918a190
---
 .../jgit/http/server/glue/RegexPipeline.java  | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/org.eclipse.jgit.http.server/src/org/eclipse/jgit/http/server/glue/RegexPipeline.java b/org.eclipse.jgit.http.server/src/org/eclipse/jgit/http/server/glue/RegexPipeline.java
index a4acd1550..384ff45a3 100644
--- a/org.eclipse.jgit.http.server/src/org/eclipse/jgit/http/server/glue/RegexPipeline.java
+++ b/org.eclipse.jgit.http.server/src/org/eclipse/jgit/http/server/glue/RegexPipeline.java
@@ -64,13 +64,20 @@ import javax.servlet.http.HttpServletResponse;
  * <p>
  * If there are capture groups in the regular expression, the matched ranges of
  * the capture groups are stored as an array of modified HttpServetRequests,
- * into the request attribute {@link MetaFilter#REGEX_GROUPS}.
+ * into the request attribute {@link MetaFilter#REGEX_GROUPS}. Using a capture
+ * group that may not capture, e.g. {@code "(/foo)?"}, will cause an error at
+ * request handling time.
  * <p>
- * Each servlet request has been altered to have its {@code getPathInfo()}
- * method return the matched text of the corresponding capture group. A
- * {@link RegexGroupFilter} can be applied in the pipeline to switch the current
- * HttpServletRequest to reference a different capture group before running
- * additional filters, or the final servlet.
+ * Each servlet request has been altered to have its {@code getServletPath()}
+ * method return the original path info up to the beginning of the corresponding
+ * capture group, and its {@code getPathInfo()} method return the matched text.
+ * A {@link RegexGroupFilter} can be applied in the pipeline to switch the
+ * current HttpServletRequest to reference a different capture group before
+ * running additional filters, or the final servlet.
+ * <p>
+ * Note that for {@code getPathInfo()} to start with a leading "/" as described
+ * in the servlet documentation, capture groups must actually capture the
+ * leading "/".
  * <p>
  * This class dispatches the remainder of the pipeline using the first capture
  * group as the current request, making {@code RegexGroupFilter} required only