I have a couple of questions on the spec wording.
1. * <li><p> <a name="build">{@code $BUILD}</a>, matching {@code
* (0|[1-9][0-9]*)} --- The build number, incremented for each promoted
* build. {@code $BUILD} is reset to {@code 1} when any portion of {@code
* $VNUM} is incremented. </p>
If the build number is reset to 1 each time $VNUM is changed, then what's
the purpose of build number 0? The spec allows it, but doesn't mention
how it is used.
2. * comparison method. The comparison methods {@link #compareTo(Version)
* compareTo()} and {@link #compareToIgnoreOptional(Version)
* compareToIgnoreOptional()} should be used consistently with the
* corresponding methods {@link #equals(Object) equals()} and {@link
* #equalsIgnoreOptional(Object) equalsIgnoreOptional()}. </p>
The phrase "should be used consistently with" reads a bit strange to me. Can it
be the case that what was actually meant is that Version class guarantees
`compareTo` method is consistent with `equals` and `compareToIgnoreOptional` is
consistent with `equalsIgnoreOptional`. If so, then this is not the question of
how they are used (which is up to a caller), but of how they are implemented.
Here's what java.lang.Comparable has to say about it:
* The natural ordering for a class {@code C} is said to be <i>consistent
* with equals</i> if and only if {@code e1.compareTo(e2) == 0} has
* the same boolean value as {@code e1.equals(e2)} for every
* {@code e1} and {@code e2} of class {@code C}.
...
* It is strongly recommended (though not required) that natural orderings be
* consistent with equals. This is so because sorted sets (and sorted maps)
* without explicit comparators behave "strangely" when they are used with
* elements (or keys) whose natural ordering is inconsistent with equals.
...
* <p>It is strongly recommended, but <i>not</i> strictly required that
* {@code (x.compareTo(y)==0) == (x.equals(y))}. Generally speaking, any
* class that implements the {@code Comparable} interface and violates
* this condition should clearly indicate this fact. The recommended
* language is "Note: this class has a natural ordering that is
* inconsistent with equals."
Maybe an explicit note could be moved to each of the comparison methods and/or
the top-level paragraph is rephrased a bit?
* <p> This method provides ordering which is consistent with equals()
and
* <p> This method provides ordering which is consistent with
equalsIgnoreOptional()
3. The following explicit wordings do no harm, of course, but in my opinion they
bloat the spec.
In comparison methods:
* <p> A version is not comparable to any other type of object.
If we make this class `final` as per [1], this might be removed.
In `equals` and `hashCode` methods:
* <p> This method satisfies the general contract of the ... method.
Well, once again, no harm obviously, but being a subtype is kind of all
information we really need to know to infer that.
*. Now an API question.
Does it make any sense to make a stronger guarantee for Version.version method
to return an immutable list (as in List.of) rather than just an unmodifiable
one?
Thanks.
--------------------------------------------------------------------------------
[1] http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-March/046814.html
