UrlEncodedQueryString CCC request

[Marc Hadley]

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.