On Oct 12, 2007, at 6:31 PM, Richard Kennard wrote:
> [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)
The JSR 311 UriBuilder has methods for scheme, host, port and
userInfo. We did have authority too but removed it since its a
composite of some of the others.
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?
I think it would make sense for the JSR 311 class to extend a
generalized java.net class since we'd want to add support for URI
templates. That support is pervasive so its not just a case of adding
new methods, we'd want to override existing ones to allow URI
templates to be used within their values.
Regards,
Marc.
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
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.
