UrlEncodedQueryString CCC request

[Paul Sandoz]

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. 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