[hibernate-issues] [Hibernate-JIRA] Created: (HHH-6941) Erroneous Javadoc for getReferencedProperty, getReferenceablePropertyIterator
Erroneous Javadoc for getReferencedProperty, getReferenceablePropertyIterator
-----------------------------------------------------------------------------
Key: HHH-6941
URL: http://opensource.atlassian.com/projects/hibernate/browse/HHH-6941
Project: Hibernate Core
Issue Type: Bug
Components: documentation
Affects Versions: 3.6.9, 4.0.0.Final
Reporter: Hayo
Priority: Minor
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:
{code}.
/**
* 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 {
{code}
Mind that this changes the contract on handling identifiers, alsthough this contract has
never been fulfilled.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira