Update Parameters to properly implement compareTo and equals

[Peter Powers]

It appears that the initial compareTo implementations were done to support equals and often only return 0 or -1. There are situations in which one would want to sort groups of parameters for presentation. Need to implement compareTo such that sorting is by parameter name, then value, with null params, names, or values always returning -1 and sinking in any list (unless both two params both have null values). This should be done using the generics Comparable<T> interface. For lists of with type ParameterAPI<?>, compareTo in a specific Param will throw ClassCastExceptions? so these need to be caught and passed up to abstract parents that will compare on name only.

[Peter Powers]

First pass at implementing generic Comparable. Currently maintains previous evaluation but needs further work. Some equals implementations adjusted for compactness.

in [7517]

[Peter Powers]

Unit test errors have provided insight on this issue. (Note: the Parameter class name makes talking about generic parameterization a bit confusing)

Equivalency via equals(obj) for parameters is now implemented as follows in AbstractParameter?:

• compare object
• check if Parameter
• check specific Parameter implementation class
• check name
• check value, handling null

This should suffice for all implementations, however, any class that is used as a generic parameterization E in Parameter<E> should have a robust implementation of equals to ensure proper evaluation of value.equals(p.getValue()) in AbstractParameter?.equals(obj).

As stated originally, equals should NOT defer to compareTo(Parameter<E>).

In the case of compareTo(), AbstractParameter? provides a comparison on name. This, too should suffice for most if not all comparison situations. In the event that a Collection<Parameter> or ParameterList? needs sorting, such sorting will likely be done for presentation purposes only where name will be the important key. If additional sorting on value is required, it could be implemented by a subclass, but would need to defer to the parent implementation in the event of a ClassCastException? (this could occur when sorting a List of unknown parameterized type e.g. List<Parameter<?>>)

To properly compare values in AbstractParameter?, the Parameter<E> Type E would have to be <E extends Comparable<E>> or better yet <E extends Comparable<? super E>> (to handle child classes). This in turn requires that all possible parameterization types implement Comparable (e.g. LocationLists?, Regions etc...). It makes no sense to go to such lengths at this time.

Note that for Parameters compareTo is not consistent with equals as suggested in the documentation of the Comparable<E> interface. This is ok, however, Parameters should NOT be used as keys in any collections that relies on hashing or other comparisons to check or sort contents (e.g. Set, Maps etc...)

[Peter Powers]

Moving beyond the Parameters themselves, compareTo should not be used in any equivalency test for objects that wrap Parameters. As an example, Site currently uses param.compareTo(param) to check if the values of internal site params are the same. Should use param.equals(param) instead.

[Peter Powers]

Site equals(obj) rewritten in [7933]

[Peter Powers]

Changes to equals and compareTo for all commons params in [7934]

No parameter implementation handles equals or compareTo; all work is done by AbstractParameter?.

[Kevin Milner]

is this ready to be closed? any unit tests for the equals method?

[Peter Powers]

Tests for equals complete in [7972] and [7974].

Tests for compareTo revealed that cruisecontrol jvm doesn't like runtime type ambiguity when sorting a List<Parameter<?>>. Although we're updating the cc JRE, I also changed Parameter to implement Comparable<?> instead of Comparable<T>. Seems ok for now; however, any Parameter implementations that override compareTo(param) may have to cast the param.value to the runtime type. Changes made in [7979].