Document that Session.getReference not always returns a T

Description

The type signature for Session.getReference is inherited from EntityManager and promises to return a T. The User Guide contains an example snippet where this guarantee is violated.

Since this behavior is surprising, it should be documented at the Javadoc of that method.

Is this surprise also the reason that the unit test uses the complicated Identifiable.class.isInstance(book) instead of the simpler book instanceof Identifiable? When I write the latter in IntelliJ, it warns me that the expression is always true (which it is). It also warns me that book instanceof Book is always true because of the method's type signature. But that warning is wrong since the JVM does not ensure the correct type in this situation. Minimal example:

Almost every Java developer and also the IDE developers assume that a method declared as returning a T indeed returns a T. Since Session.getReference violates this assumption in an actual documented use case, this should be documented.

Environment

None

Status

Assignee

Vlad Mihalcea

Reporter

Roland Illig

Fix versions

Labels

None

backPortable

None

Suitable for new contributors

None

Requires Release Note

None

Pull Request

None

backportDecision

None

Components

Affects versions

Priority

Major
Configure