RegexPathSpec documentation and MatchedPath improvements

[joakime]

Added javadoc, and improved RegexMatchedPath behavior with more unit tests.

Signed-off-by: Joakim Erdfelt joakim.erdfelt@gmail.com

[gregw]

I think you have well captured the current behaviour, but I think we should consider changing it a little as per my comment.

[gregw]

I think the logic is getting a bit complex and a bit burried. I've made a suggestion for how the description should be, but I think the following algorithm should be used as it is a bit more efficient with less name lookups:

switch(matcher.groupCount())
{
    case 0: match=path; info=null; 
    break;

    case 1:
      if ("name".equals(group(1).name)
          match=group; info=path.substring(group.end);
      else
          match=path.substring(0,group.start); info=group; 
      break;

    default:
      if (group("name").exists)
      {   
          match=group("name");
              info=group("info");
          else
              info=path.substring(group("name").end);
      }
      else if (group("info").exists)
          match=path.substring(0,group.start); info=group; break;
      else
          match=path; info=null; 
    break;
}

[joakime]

@gregw I implemented your algorithm, but it makes quite the mess. (lots of test failures)
Take a look at the test case examples.

https://github.com/eclipse/jetty.project/blob/52de789437b5415ad7a1c594207e2d6d4c60fb05/jetty-http/src/test/java/org/eclipse/jetty/http/pathmap/RegexPathSpecTest.java#L90-L126

The test argument order is ...
String regex, String input, String expectedPathMatch, String expectedPathInfo

Do you think these are sane expectations?
If so, then we need to fix the algorithm, or reintroduce the check on PREFIX_GLOB.

[gregw]

I think this is good enough for now, but with TODOs for future optimizations.

[gregw]

Ultimately this lookup makes me itch! If they are not using the named group, then an exception is created and ignored for every lookup attempt.

For now, can we add a TODO that when we scan the pattern, we should look for the presence of "" and only do this lookup if we have seen it in the pattern.

[gregw]

Two exceptions may be created and ignored here. So again, I think we need a TODO to optimise that away in future.

[joakime]

Once the javadoc issues on PR #8173 are green and merged, this should build green, then I can merge this one.