Request for comments: Bug 6306820

[Alan Bateman]

Richard Kennard wrote:
> Alan,
>
> Great to hear from you again!
>
> I am not at all opposed to making the changes you suggest. However, 
> permit me to explain why it is the way it is first, and then you can 
> counter my points :)
>
> If I understand you correctly, what you are suggesting is a more 
> 'functional' (as opposed to OO) approach to the design. That is, have 
> a bunch of static methods that operate on a Map<String, List<String>>, 
> and let the user worry about passing that Map around. I would have the 
> following concerns to this approach:
It's good to see you are persevering with this one. I just mention the 
suggestion of a utility class as another approach to examine given that 
many of the operations are map-like. As it stands it looks like you are 
trying to support a dual API anyway in that you define the 
getParameterMap method. On that method, I see it returns a reference to 
the internal map - did you mean to do that? For several reasons this 
could be problematic and dangerous.

A few other observations from my initial glance at the javadoc:

- The methods that do not otherwise have a value to return could return 
the URLEncodedQueryString instead of void so as to allow for method 
chaining. If you make the method names relatively short (like "add" and 
"append") then it might be easier to chain several invocations on the 
same line.

- I think I missed the point as to why it is necessary to make it 
Serializable. Could the serialized form is the query String or the URI? 
If you do make it Serializable then there are a issues in the 
implementation that will to be examined closely.

- Should the spec say anything about character encoding? I believe you 
are using UTF-8 and maybe the spec should reference URLEncoder/URLDecoder.

- Since the class is mutable you probably need something in the 
top-level spec to explain that it is not thread safe, etc.

- Is the ParameterSeparator enum needed? I assume almost all cases are 
"&" and it should be rare for anything else (in that case perhaps have 
the user can specify the separator as a String - just a suggestion).

- Do getQuery() and toString return the same string?

>
>
> 3. To add a method to java.net.URI that accepts a Map and turns it 
> into a 'www-form-urlencoded' query string would be to incorporate 
> details from the HTML spec into the URI class. At present, the URI 
> class is only concerned with the RFC 2396 URI spec - not anything HTML 
> specific. I thought you'd prefer it to stay that way? Indeed, that was 
> one of your objections to some of my earlier designs, many months ago.
I'm not suggesting adding any methods to URI that take the Map but 
rather that it may be useful to look into new static factory methods to 
construct URIs from other URIs and components. The piece-wise 
constructors and resolve methods don't cover the cases where you need to 
clone a URI and replace one or more components - this approach might be 
more broadly useful that the "apply" methods that you have suggested.

-Alan.