UrlEncodedQueryString CCC request

[Richard Kennard]

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