[jax-rs-spec users] [jsr339-experts] Why this matching algorithm is bad for everybody

From: Bill Burke <>
Date: Thu, 23 May 2013 21:25:29 -0400

I'd like to document first why this matching algorithm is really poor,
and then why the poorness of this algorithm is bad for both us vendors
and our users.

***What's missing***
* Users could get 405 and 415 errors even if there is a locator that can
resolve the request
* Users may get default OPTIONS behavior even if there is a locator that
can resolve the request
* Users may get default HEAD behavior even if there is a locator that
can resolve the request
* Even weirder, for all of the above, it is possible for a locator to
resolve these issues if its @Path expression is modified to be more
* Users cannot override default OPTIONS behavior in a portable way: i.e.

public class DefaultOptions {
     public void options() {}
* Users cannot match across multiple resource classes without the same
exact regular expression in the root @Path

* We've done all this work in step 2 to sort expressions based on
literal characters and capture groups, only to lose this information in
Step 3(b). Ambiguous matches where you might not get the best possible
path match depending on the sort i.e.

GET /foo
Accept: text/plain

   public String get1() {}

   public String get2() {}

   public String get3() {}

The thing is, there's no performance reasons not to support these cases
as I've supported them in Resteasy for 4+ years. There's a lot of
optimizations you can do to make things efficient even in the most
complex hierarchies. The backward compatibility arguments you are
making are, IMO, pretty bogus too. JAX-RS 1.x has painted us in a
corner because the old spec leads made a huge mistake of putting
implementation details in the spec for perceived performance gains
instead of making a sensible more generic matching description.
Basically they designed a poor algorithm and now the new spec leads
refuse to fix it. Already, refactoring this code for Resteasy to match
this spec algorithm, two user reported matching problems have regressed.

***Why this is bad for both vendors and users***

The algorithm is non-intuitive. Many of the deficiencies I listed above
are not uncommon to run into. Without intimately knowing the spec
algorithm, you'd just expect these cases to just work. As a user, if
your code failed because of one of these deficiencies you're left to
walk through 2-3 pages of the specification to figure out why and then
figure out if it is the spec or the vendor implementation is the
culprit. We've just been arguing for days on whether the 2.0 algorithm
is backward compatibile or not. We've been exchanging emails to figure
out if esoteric match cases fit under the spec algorithm. In summary,
the algorithm has caused us, the experts, problems. How do you think
users will fare? They will be frustrated as hell.

For us vendors and open source projects, since these are non-rare cases,
we will get an email or support ticket asking why these edge matching
cases don't match. Lost productivity for our developers. Lost $$$ for
our companies for those being paid to resolve these user issues.

Bill Burke
JBoss, a division of Red Hat