UrlEncodedQueryString CCC request

[Marc Hadley]

On Nov 1, 2007, at 5:45 AM, Michael McMahon wrote:
>
> 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.
>
Some comments interspersed below.

>
> 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
>>
I agree with the goal but we'd rather not be tied to jdk7. The  
current plan is to make the API available separately for jdk5 or  
later. Would we be able to bundle any jdk7 superclass to achieve that ?

>> 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.
>>
The builder is strictly that, a builder, so I'm not sure if it makes  
sense to add read capabilities to it. Would it make sense to add the  
read capabilities of UrlEncodedQueryString directly to URI ?

>> 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
>>
Matrix parameters aren't specific to JSR311, I believe that a number  
of Web APIs make use of them but I don't have an example at hand.

>> 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.
>>
That is a definite risk. Currently we are discussing more complex  
notations for representing things like default values, prefixes,  
suffixes etc. The simple {param_name} syntax is likely to survive  
though so its possible we could implement that initially and add full  
support in a subsequent release.

Regards,
Marc.

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

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.