[hibernate-issues] [Hibernate-JIRA] Created: (HHH-6941) Erroneous Javadoc for getReferencedProperty, getReferenceablePropertyIterator

[Hayo (JIRA)]

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