Jaxrs-api: Clarify StatusInfo#equals

[MarkusKull]

It is a known pitfall to compare Response#getStatusInfo with one of the Status-Enums as this will return unexpected results when reasonphrase differs. Happens especially with Tomcat8.5+.

See https://blog.zenika.com/2017/05/22/some-notes-about-jax-rs-http-statuses-and-tomcat/

Even if one wanted, this cannot be fixed by overriding equals because Enum-Baseclass of Status declares equals as final. Thus depending on order of comparison, it would still behave unexpectedly.

1) Please extend javadoc of Response#getStatusInfo() that the returned StatusType must not be compared with a Status because this comparison may return unequal when reasonphrase differs; Instead the statuscodes should be compared.
2) Deprecate StatusInfo#equals with the same javadoc.

    /**
     * @deprecated May return false when reasonPhrase differs. Instead compare statusCode directly.
     */
    @Deprecated
    @Override
    abstract boolean equals(Object obj);

[mkarg]

I wonder why you not simply ask to make equals work correctly?

[MarkusKull]

@mkarg Try it: "Cannot override the final method equals from Enum<Status>"

Overriding only StatusInfo#equals would work partly for that comparison-order, but not when users call Status#equals. For a transitive equals, more has to be done:

• change Status to an non-instantiable class instead of an enum and change former enum-members to constants of type StatusType. (Except for compatibility, one really ought do this because the current enum wrongly implies that there are never any other httpstatus)
• change StatusInfo from interface to final class

That would help insofar as one could now call equals transitively. Still, language lawyers will complain that equals only compares statusCode but not reasonPhrase. Will you then drop reasonPhrase because useless? But reasonPhrase is already used as seen in some jersey-issues. All in all, the compatibility hassles caused by such changes are grave.

[mkarg]

I think it would be worth letting the committers discuss that. ;-)

[unexist]

Maybe it is still worth pushing this issue.. ;)

[chkal]

I agree that there seems to be way to fix equals() (or am I missing something).

Therefore, I'm fine with (1) and (2) proposed in the original issue description. Anyone wants to open a pull request against the 3.1-SNAPSHOT branch?