Polish Javadoc of PersistentEntity regarding iteration order of PersistentProperty instances.

Fixes #2814.

Author: odrotbohm

src/main/java/org/springframework/data/mapping/PersistentEntity.java

@@ -24,7 +24,7 @@
 import org.springframework.util.Assert;
 
 /**
- * Represents a persistent entity.
+ * Represents a persistent entity. The order of the properties returned via the {@link Iterator} is not guaranteed.
  *
  * @author Oliver Gierke
  * @author Graeme Rocher
@@ -47,9 +47,9 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> extends It
 	 * Returns the {@link PreferredConstructor} to be used to instantiate objects of this {@link PersistentEntity}.
 	 *
 	 * @return {@literal null} in case no suitable constructor for automatic construction can be found. This usually
-	 *         indicates that the instantiation of the object of that persistent entity is done through either a customer
-	 *         {@link org.springframework.data.mapping.model.EntityInstantiator} or handled by custom conversion
-	 *         mechanisms entirely.
+	 *         indicates that the instantiation of the object of that persistent entity is done through either a
+	 *         customer {@link org.springframework.data.mapping.model.EntityInstantiator} or handled by custom
+	 *         conversion mechanisms entirely.
 	 * @deprecated since 3.0, use {@link #getInstanceCreatorMetadata()}.
 	 */
 	@Nullable
@@ -61,8 +61,8 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> extends It
 	 *
 	 * @return {@literal null} in case no suitable creation mechanism for automatic construction can be found. This
 	 *         usually indicates that the instantiation of the object of that persistent entity is done through either a
-	 *         customer {@link org.springframework.data.mapping.model.EntityInstantiator} or handled by custom conversion
-	 *         mechanisms entirely.
+	 *         customer {@link org.springframework.data.mapping.model.EntityInstantiator} or handled by custom
+	 *         conversion mechanisms entirely.
 	 * @since 3.0
 	 */
 	@Nullable
@@ -136,17 +136,17 @@ default P getRequiredIdProperty() {
 	}
 
 	/**
-	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property is
-	 * available on the entity.
+	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property
+	 * is available on the entity.
 	 *
 	 * @return the version property of the {@link PersistentEntity}.
 	 */
 	@Nullable
 	P getVersionProperty();
 
 	/**
-	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property is
-	 * available on the entity.
+	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property
+	 * is available on the entity.
 	 *
 	 * @return the version property of the {@link PersistentEntity}.
 	 * @throws IllegalStateException if {@link PersistentEntity} does not define a {@literal version} property.
@@ -237,8 +237,8 @@ default P getPersistentProperty(Class<? extends Annotation> annotationType) {
 	Class<T> getType();
 
 	/**
-	 * Returns the alias to be used when storing type information. Might be {@literal null} to indicate that there was no
-	 * alias defined through the mapping metadata.
+	 * Returns the alias to be used when storing type information. Might be {@literal null} to indicate that there was
+	 * no alias defined through the mapping metadata.
 	 *
 	 * @return
 	 */
@@ -253,26 +253,39 @@ default P getPersistentProperty(Class<? extends Annotation> annotationType) {
 
 	/**
 	 * Applies the given {@link PropertyHandler} to all {@link PersistentProperty}s contained in this
-	 * {@link PersistentEntity}.
+	 * {@link PersistentEntity}. The iteration order is undefined.
 	 *
 	 * @param handler must not be {@literal null}.
 	 */
 	void doWithProperties(PropertyHandler<P> handler);
 
+	/**
+	 * Applies the given {@link SimplePropertyHandler} to all {@link PersistentProperty}s contained in this
+	 * {@link PersistentEntity}. The iteration order is undefined.
+	 *
+	 * @param handler must not be {@literal null}.
+	 */
 	void doWithProperties(SimplePropertyHandler handler);
 
 	/**
-	 * Applies the given {@link AssociationHandler} to all {@link Association} contained in this {@link PersistentEntity}.
+	 * Applies the given {@link AssociationHandler} to all {@link Association} contained in this
+	 * {@link PersistentEntity}. The iteration order is undefined.
 	 *
 	 * @param handler must not be {@literal null}.
 	 */
 	void doWithAssociations(AssociationHandler<P> handler);
 
+	/**
+	 * Applies the given {@link SimpleAssociationHandler} to all {@link Association} contained in this
+	 * {@link PersistentEntity}. The iteration order is undefined.
+	 *
+	 * @param handler must not be {@literal null}.
+	 */
 	void doWithAssociations(SimpleAssociationHandler handler);
 
 	/**
-	 * Applies the given {@link PropertyHandler} to both all {@link PersistentProperty}s as well as all inverse properties
-	 * of all {@link Association}s.
+	 * Applies the given {@link PropertyHandler} to both all {@link PersistentProperty}s as well as all inverse
+	 * properties of all {@link Association}s. The iteration order is undefined.
 	 *
 	 * @param handler must not be {@literal null}.
 	 * @since 2.5
@@ -357,7 +370,7 @@ default <A extends Annotation> A getRequiredAnnotation(Class<A> annotationType)
 	 *
 	 * @param bean must not be {@literal null}.
 	 * @throws IllegalArgumentException in case the given bean is not an instance of the typ represented by the
-	 *           {@link PersistentEntity}.
+	 *             {@link PersistentEntity}.
 	 * @return whether the given bean is considered a new instance.
 	 */
 	boolean isNew(Object bean);
@@ -373,8 +386,8 @@ default <A extends Annotation> A getRequiredAnnotation(Class<A> annotationType)
 	boolean isImmutable();
 
 	/**
-	 * Returns whether the entity needs properties to be populated, i.e. if any property exists that's not initialized by
-	 * the constructor.
+	 * Returns whether the entity needs properties to be populated, i.e. if any property exists that's not initialized
+	 * by the constructor.
 	 *
 	 * @return
 	 * @since 2.1