Java Reference
In-Depth Information
Let's look at a list of sorted URI matching expressions and explain why one would match
over another:
1 /customers/{id}/{name}/address
2 /customers/{id : .+}/address
3 /customers/{id}/address
4 /customers/{id : .+}
Expressions 1-3 come first because they all have more literal characters than expression 4.
Although expressions 1-3 all have the same number of literal characters, expression 1 comes
first because sorting rule #2 is triggered. It has more template expressions than either pattern
2 or 3. Expressions 2 and 3 have the same number of literal characters and same number of
template expressions. Expression 2 is sorted ahead of 3 because it triggers sorting rule #3; it
has a template pattern that is a regular expression.
These sorting rules are not perfect. It is still possible to have ambiguities, but the rules cover
90% of use cases. If your application has URI matching ambiguities, your application design
is probably too complicated and you need to revisit and refactor your URI scheme.
Encoding
The URI specification only allows certain characters within a URI string. It also reserves cer-
tain characters for its own specific use. In other words, you cannot use these characters as
part of your URI segments. This is the set of allowable and reserved characters:
▪ The US-ASCII alphabetic characters a-z and A-Z are allowable.
▪ The decimal digit characters 0-9 are allowable.
▪ All these other characters are allowable:
_-!.~'()*
.
▪ These characters are allowed but are reserved for URI syntax:
,;:$&+=?/\[]@
.
All other characters must be encoded using the “%” character followed by a two-digit hexa-
decimal number. This hexadecimal number corresponds to the equivalent hexadecimal char-
acter in the ASCII table. So, the string
bill&burke
would be encoded as
bill%26burke
.
When creating
@Path
expressions, you may encode its string, but you do not have to. If a
character in your
@Path
pattern is an illegal character, the JAX-RS provider will automatic-
ally encode the pattern before trying to match and dispatch incoming HTTP requests. If you
do have an encoding within your
@Path
expression, the JAX-RS provider will leave it alone
and treat it as an encoding when doing its request dispatching. For example:
@Path
(
"/customers"
public
public class
class
CustomerResource
CustomerResource
{
@GET
