Paul Sandoz wrote:
Hi Richard, Michael,
Some clarifications on UriBuilder, URI templates and URI processing in
JSR-311.
UriBuilder is primarily concerned about making easy to safely and
efficiently build URIs. It was designed to be general in nature rather
than scoped to a certain way in JSR-311.
What i said above is slightly misleading of me, i should have said it
was *mostly* designed to be general in nature as there are 4 methods
associated with accessing URI templates of a class or method, but it is
simple to generalize by removing such methods.
Paul.
If it is at all specific it is
focused on the use-cases for building and using URIs for RESTful Web
applications. For example, given an instance of a java.net.URI how can
one easily and safely append one or more path segments to the path
component of that instance, or add query parameters and values to the
query component of that instance, to create a new URI?
A UriBuilder can be created from an existing java.net.URI instance and
then the URI components can be replaced and/or augmented (but not
retrieved). URI templates are just one aspect of building URIs and a
UriBuilder can be used effectively without leveraging templates (many of
the examples provided in the Jersey, the RI, distribution do just that).
URI templates are specified in an internet draft [1], i don't know
when/if it will become an RFC. I would not go as far to say they are "ad
hoc", which my understanding implies a particular case, as URI templates
are fairly general and useful so i would not discount them too early in
the discussion process.
JSR-311 also provides access to the query parameters, path segments, and
matrix parameters of path segments present in a URI [2].
I understood the CCC request to consider alignment as something larger
in scope to improve both URI building and URI parsing/building of URI
components.
JSR-311 will have to provide it's own URI-based classes but it would be
good if we could align and improve the design in JSR-311 and JDK7.
Paul.
[1] http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-01.txt
[2] https://jsr311.dev.java.net/nonav/javadoc/javax/ws/rs/core/UriInfo.html
Richard Kennard wrote:
Michael (Paul? Marc?),
Looking at the JSR311 URIBuilder, and with respect to Mark
(Reinhold)'s concerns, I actually don't think there is much of an
overlap between them. Specifically:
1) javax.ws.rs.core.UriBuilder seems primarily concerned with building
URIs by leveraging UriTemplates
2) java.net.UrlEncodedQueryString seems primarily concerned with
modelling a query string
While 1) is useful for building URIs in a JSR311-specific way, 2) is
useful for parsing and retrieving and modifying query parameters (eg.
not solely a builder)
So while an implementation of JSR311 may want to use
java.net.UrlEncodedQueryString internally, I don't see how the two
classes could effectively merge, because UriBuilder isn't concerned
with parsing and retrieving and modifying, and UrlEncodedQueryString
isn't concerned with UriTemplates.
Regards,
Richard.
Michael McMahon wrote:
We have been asked by the CCC to go back and reconsider the design of
the proposed
UrlEncodedQueryString class/API and to consider aligning it with the
URIBuilder class
that has been proposed in JSR311. Also, the particular concern
expressed by the CCC
is that we possibly restricted the scope of the class too much.
What I think we would like to achieve (for Java SE) is a general
purpose URI builder that is not
specifically tied to any particular type of web application.
When Richard initially proposed the UrlEncodedQueryString, it was
more like a URIBuilder
but our concern (which I think is still valid) is that a Java SE
class for constructing URIs
must be solely based on defined standards (the URI rfcs), rather than
on ad-hoc (albeit commonly used)
conventions in the world of web applications. Specifically, I don't
think we can impose
any additional structure on URIs that is not explicitly specified in
the relevant URIs.
But if other people have a different view on this, I'm interested to
discuss it.
A reference for the JSR311 class is at
https://jsr311.dev.java.net/nonav/javadoc/index.html
and Paul Sandoz's blog entry talking about it is at
http://blogs.sun.com/sandoz/entry/building_uris
The javadoc for the proposed UrlEncodedQueryString is attached in a
zip file
Thanks,
Michael.
--
| ? + ? = To question
----------------\
Paul Sandoz
x38109
+33-4-76188109
