UrlEncodedQueryString CCC request

[Michael McMahon]

Marc & Paul,

I wonder if you have an opinion on the points/questions raised below?
I'd like to get agreement on the general shape of the API before
anyone goes off and reworks the existing proposal.

Thanks
Michael.

Michael McMahon wrote:
> I agree with most of the suggestions below. The main things
> we want are:
>
> 1) alignment, ie. the JSR311 class extends the java.net class
>    although I would imagine that if JSR311 is finalised before jdk7
>    then it will not initially extend it. So, it should at least be 
> aligned
>    sufficiently so that it could extend the java.net class in the future
>
> 2) then we combine the building capabilities of UriBuilder (probably 
> use that name also)
>    with the retrieval/query manipulation capabilities of 
> UrlEncodedQueryString.
>    I think the method names from UrlEncodedQueryString will have to 
> change though
>   eg addParameter() would need to be addQueryParameter() etc.
>
> Some questions.
>
> 1) I'm not familiar with the notion of  "matrix" parameters. Google 
> seems to
>    only reveal one old w3c article about them. Are they more widely 
> used than this?
>    If the concept is more specific to JSR311, then I think I'd prefer 
> to leave them
>    out of the java.net. class
>
> 2) Initially I was sceptical about URI templates, and I do think that the
>   general class probably doesn't need any of the methods related to
>   reflection/annotation processing (of URI templates), but it does 
> look like a useful feature
>   and it's worth considering supporting the build() capability which 
> replaces
>   {} templates with specific instance values from the Map passed in.
>   The risk of course is that the specification for URI templates could 
> change
>   before it is standardised by the IETF.
>
> Thanks
> Michael.
>
> Marc Hadley wrote:
>> 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.
>>
>