Erroneous Javadoc for getReferencedProperty, getReferenceablePropertyIterator

Description

The Javadoc inside org.hibernate.mapping.PersistentClass is misleading and partly wrong. This is the case for all published versions of Hibernate.

  • getReferencedProperty: Opposed to the documentation properties that are identifiers are not included.

  • getReferenceablePropertyIterator: documentation refers to wrong documentation above and is not understandable

  • getPropertyIterator: unclear wording [enhancement]

My proposal is to change the documentation as follows:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 . /** * Build an iterator over the properties defined on this class. The returned * iterator only accounts for non-identifier properties (which excludes: * {@code <id>}, {@code @Id}). * <p/> * Differs from {@link #getUnjoinedPropertyIterator} in that the iterator * we return here will include properties defined as part of a join. * <p/> * Differs from {@link #getReferenceablePropertyIterator} in that the properties * defined in superclasses of the mapping inheritance are not included. * * @return An iterator over non-identifier properties. */ public Iterator getPropertyIterator() { /** * Build an iterator of properties which may be referenced in association mappings. * <p> * Includes properties defined in superclasses of the mapping inheritance. * Includes all properties defined as part of a join. * * @see #getReferencedProperty for a discussion of "referenceable" * @return The property iterator. */ public Iterator getReferenceablePropertyIterator() { /** * Given a property path, locate the appropriate association mapping reference. * Locates properties defined in superclasses of the mapping inheritance. * Locates all properties defined as part of a join. * <p/> * A referenceable property is a property which can be a target of a foreign-key * mapping ({@code <property-ref>}, {@code @*To*(mappedBy =}...). * It cannot be an identifier. * * @param propertyPath The property path to resolve into a property reference. * @return The referenced property (never null). * @throws MappingException If the property could not be found. */ public Property getReferencedProperty(String propertyPath) throws MappingException {

Mind that this changes the contract on handling identifiers, alsthough this contract has never been fulfilled.

Environment

None

Status

Assignee

Vlad Mihalcea

Reporter

Hayo

Fix versions

backPortable

None

Suitable for new contributors

None

Requires Release Note

None

Pull Request

None

backportDecision

None

Components

Affects versions

4.0.0.Final
3.6.9

Priority

Minor