Paul,
> [UriBuilder has] 4 methods associated with accessing URI templates of
a class or method, but it is simple to generalize by removing such methods
This seems a good starting point. If I may propose a logical progression:
1. We split JSR311's UriBuilder into a JSR311-specific version and a
generalized java.net version
2. We add further generalized methods into the java.net version to cover
the other URI segments (scheme, host, port, authority, user-info)
3. We would now have a class that looks not unlike what I was proposing
last year. The java.net team's objection to this class (which I agree is
valid) was that some methods (queryParam, matrixParam) are not strictly
part of the RFC 2396 URI spec. So we may split it again, into a 'strict
URI' part and a 'www-form-urlencoded query string' part (which I think
is essentially what queryParam and matrixParam are implying)
4. We agree that parsing and retrieving is also a useful feature and
include that (the class can still be called 'builder' - StringBuilder
has methods for retrieving, for example)
I think how we do the split in 3) is the most important decision. The
java.net team and I tried two ways - a generalized superclass and a
specialized subclass, and a standalone class - and preferred the latter,
hence where we are with UrlEncodedQueryString today.
What do you think?
Regards,
Richard.
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.
--
Richard Kennard | Principal | Kennard Consulting
0402 629 952
http://www.kennardconsulting.com
