Javatize Parameter API
Description
Environment
Activity
CodeHaus Comment From: desruisseaux - Time: Wed, 12 Aug 2009 02:52:41 -0500
---------------------
<p>If <tt>ParameterValueGroup</tt> or <tt>ParameterDescriptorGroup</tt> extend <tt>Collection</tt>, we would have a clash in the semantic of <tt>equals(Object)</tt> and <tt>hashCode()</tt> methods. <tt>ParameterDescriptorGroup</tt> for instance is an <tt>IdentifiedObject</tt> and as such contains metadata (especially an identifier applicable to the group as a whole) in addition of the parameter elements. We would expect a <tt>ParameterDescriptorGroup.equals(Object)</tt> method to take those metadata in account. But the <tt>equals(Object)</tt> method is also strictly defined in the <tt>Collection</tt> contract, and this definition do not leave any room for anything inherited from <tt>IdentifiedObject</tt>.</p>
<p>A similar argument apply to <tt>ParameterValueGroup</tt>, which inherit a descriptor association.</p>
<p>In addition, if <tt>ParameterDescriptorGroup</tt> extend <tt>Collection</tt>, it would be more work for implementor since their implementation could extends some kind of <tt>AbstractDescriptor</tt>, or extend <tt>AbstractCollection</tt>, but can not extend both.</p>
<p>A composition approach like what GeoAPI does today as the following advantages:</p>
<ul>
<li>Has all the benefit enumerated in the JIRA task (user can still use <tt>add(ParameterValue)</tt> on the collection).</li>
<li>Easier for implementors since they can leverage both their <tt>AbstractDescriptor</tt> and <tt>AbstractCollection</tt>.</li>
<li>Avoid the clash in semantic of <tt>equals(Object)</tt> and <tt>hashCode()</tt> methods.</li>
<li>Implementors can still implement <tt>Collection</tt> directly and have the <tt>values()</tt> method to returns <tt>this</tt> if they wish.</li>
</ul>
<p>Considering the above, should we close this issue as "will not fix", or should we take some other action?</p>
Improve intergration of the parameter package with java Collections API.
After much heated email discussion the best I have been able to come
up with as follows:
ParameterValueGroup implemented as a Collection<GeneralParameterValue> with extra methods in agreement with the specification
* ParameterDescriptorGroup implemented as Collection<GeneralParameterDescriptor> with extra methods in agreement with the specification
Group is still a good suffix as it a) agrees with the specification b) Does not imply that the choice of Collection type has been made.
ParameterValueGroup should <b>be</b> order dependent. Implemented as a List or a Collection with iterator() documented to maintain order.
* ParameterDescriptorGroup should not allow duplicates, order does not appear to matter.
Ambigutity One:
One cannot tell from the specification if a ParameterGroup is ment to maintain order or not:
"A group of related parameter values. The same group can be repeated more than once in an Operation or higher level ParameterValueGroup, if those instances contain different values of one or more ParameterValues which suitably distinquish among those groups."
Tends to imply that the values are the only thing that distinquish groups, not order? This idea plays havoc with a ParameterGroup that has cardinality maxOccurs greater than 1, as it would imply we would also need to maintain distinct values? (That is two Parameter Groups could be equal).
Advantages:
Making ParameterValueGroup extend Collection will give us an add(ParameterValue) and allow us to handle optional ParameterValues.
* Downside is that we will have ParameterValueGroups that are invalid during setup.
0 Alternative is making ParameterDescriptorGroup.create(GeneralParameterValue[]) that can check validity.
NOTE WELL:
Some of this could be our interpretaion of the original. I noticed that only ParameterValueGroup was allowed maxOccurs > 1 in the original specification - and we let any GeneralParameter have full cardinality control.
Part of this is us using this API for more than what it was origionally intended. We are using it for all our parameter needs from every specificaiton.