Request for comments: Bug 6306820

[Alan Bateman]

Richard Kennard wrote:
> :
> An alternative approach would be to expose a COPY of the internal Map, 
> let the user modify it, and then introduce a setParameterMap method to 
> re-set it. However, the problem there is that, internally, it is 
> important the Map is a LinkedHashMap - so that it maintains the 
> ordering of parameters. At the moment, however, getParameterMap simply 
> returns a Map (eg. it doesn't worry the user with what sort of Map).
>
> However, setParameterMap would not have this luxury: it would have to 
> be setParameterMap( LinkedHashMap ).
>
> So I guess it comes down to what seems less messy? Exposing the 
> internal Map, or exposing the fact that it is a LinkedHashMap?
>
Yes, a copy is important as you don't want to hand out a reference to 
the LinkedHashMap used in the representation (this would create too many 
problems and probably prevent you from changing the internal 
representation in the future). In the spec you can say that the 
iteration order of the returned map corresponds to the parameter 
ordering.  For ease-of-use the returned map can be modifiable.  To allow 
construction of a UrlQueryString then you can include a create method 
that takes a Map as a parameter. The parameter need not be a 
LinkedHashMap. In the spec for this method you can make it clear that 
the ordering of parameters depends on the map iteration order. If 
someone invokes toMap (or whatever you call it) and then creates a new 
UrlQueryString then it do what you expect as the iteration order of the 
exported map is predictable.

-Alan.