From 9aec113ed343f09c5a02ac39effd89337c20a4ee Mon Sep 17 00:00:00 2001 From: Oliver Drotbohm Date: Tue, 4 Apr 2023 13:23:44 +0200 Subject: [PATCH] Polish Javadoc of PersistentEntity regarding iteration order of PersistentProperty instances. Fixes #2814. --- .../data/mapping/PersistentEntity.java | 41 ++++++++++++------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/src/main/java/org/springframework/data/mapping/PersistentEntity.java b/src/main/java/org/springframework/data/mapping/PersistentEntity.java index c15957c0a..a5dd87ac4 100644 --- a/src/main/java/org/springframework/data/mapping/PersistentEntity.java +++ b/src/main/java/org/springframework/data/mapping/PersistentEntity.java @@ -24,7 +24,7 @@ import org.springframework.lang.Nullable; 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 @@ -136,8 +136,8 @@ public interface PersistentEntity> extends It } /** - * 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}. */ @@ -145,8 +145,8 @@ public interface PersistentEntity> extends It 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 @@ public interface PersistentEntity> extends It Class 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 @@ public interface PersistentEntity> extends It /** * 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

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

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 @@ public interface PersistentEntity> extends It * * @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 @@ public interface PersistentEntity> extends It 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