DATACMNS-1101 - Polishing.

Move MappingException from o.s.d.mapping.model to o.s.d.mapping package and use it for getRequired* methods in MappingContext instead of throwing IllegalArgumentException. Further on we’ve consolidated usage of IllegalArgumentException and IllegalStateException. Along that IllegalMappingException was removed in favor or MappingException.

BasicPersistentEntity now looks up all properties by annotation instead of just returning the first one found. We’ve kept the original methods behavior and updated the comment as well as introduced getPersistentProperties returning all matching properties.

Author: christophstrobl

src/main/java/org/springframework/data/mapping/model/MappingException.java renamed to src/main/java/org/springframework/data/mapping/MappingException.java

@@ -1,20 +1,19 @@
 /*
- * Copyright (c) 2011 by the original author(s).
+ * Copyright 2011-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *     http://www.apache.org/licenses/LICENSE-2.0
+ *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-package org.springframework.data.mapping.model;
+package org.springframework.data.mapping;
 
 /**
  * @author Jon Brisbin <[email protected]>

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

@@ -16,6 +16,7 @@
 package org.springframework.data.mapping;
 
 import java.lang.annotation.Annotation;
+import java.util.Iterator;
 
 import org.springframework.data.convert.EntityInstantiator;
 import org.springframework.data.util.TypeInformation;
@@ -28,13 +29,14 @@
  * @author Jon Brisbin
  * @author Patryk Wasik
  * @author Mark Paluch
+ * @author Christoph Strobl
  */
 public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 
 	/**
 	 * The entity name including any package prefix.
 	 *
-	 * @return must never return {@literal null}
+	 * @return must never return {@literal null}.
 	 */
 	String getName();
 
@@ -51,7 +53,7 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * Returns whether the given {@link PersistentProperty} is referred to by a constructor argument of the
 	 * {@link PersistentEntity}.
 	 *
-	 * @param property
+	 * @param property can be {@literal null}.
 	 * @return true if the given {@link PersistentProperty} is referred to by a constructor argument or {@literal false}
 	 *         if not or {@literal null}.
 	 */
@@ -60,16 +62,16 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	/**
 	 * Returns whether the given {@link PersistentProperty} is the id property of the entity.
 	 *
-	 * @param property
-	 * @return
+	 * @param property can be {@literal null}.
+	 * @return {@literal true} given property is the entities id.
 	 */
 	boolean isIdProperty(PersistentProperty<?> property);
 
 	/**
 	 * Returns whether the given {@link PersistentProperty} is the version property of the entity.
 	 *
-	 * @param property
-	 * @return
+	 * @param property can be {@literal null}.
+	 * @return {@literal true} given property is used as version.
 	 */
 	boolean isVersionProperty(PersistentProperty<?> property);
 
@@ -81,6 +83,13 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 */
 	P getIdProperty();
 
+	/**
+	 * Returns the id property of the {@link PersistentEntity}.
+	 *
+	 * @return the id property of the {@link PersistentEntity}.
+	 * @throws IllegalStateException if {@link PersistentEntity} does not define an {@literal id} property.
+	 * @since 2.0
+	 */
 	default P getRequiredIdProperty() {
 
 		P property = getIdProperty();
@@ -100,6 +109,14 @@ default P getRequiredIdProperty() {
 	 */
 	P getVersionProperty();
 
+	/**
+	 * 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.
+	 * @since 2.0
+	 */
 	default P getRequiredVersionProperty() {
 
 		P property = getVersionProperty();
@@ -114,17 +131,17 @@ default P getRequiredVersionProperty() {
 	/**
 	 * Obtains a {@link PersistentProperty} instance by name.
 	 *
-	 * @param name The name of the property
+	 * @param name The name of the property. Can be {@literal null}.
 	 * @return the {@link PersistentProperty} or {@literal null} if it doesn't exist.
 	 */
 	P getPersistentProperty(String name);
 
 	/**
 	 * Returns the {@link PersistentProperty} with the given name.
 	 *
-	 * @param name the name of the property, must not be {@literal null} or empty.
+	 * @param name the name of the property. Can be {@literal null} or empty.
 	 * @return the {@link PersistentProperty} with the given name.
-	 * @throws IllegalArgumentException in case no property with the given name exists.
+	 * @throws IllegalStateException in case no property with the given name exists.
 	 */
 	default P getRequiredPersistentProperty(String name) {
 
@@ -138,34 +155,47 @@ default P getRequiredPersistentProperty(String name) {
 	}
 
 	/**
-	 * Returns the property equipped with an annotation of the given type.
+	 * Returns the first property equipped with an {@link Annotation} of the given type.
 	 *
 	 * @param annotationType must not be {@literal null}.
-	 * @return
+	 * @return {@literal null} if no property found with given annotation type.
 	 * @since 1.8
 	 */
-	P getPersistentProperty(Class<? extends Annotation> annotationType);
+	default P getPersistentProperty(Class<? extends Annotation> annotationType) {
+
+		Iterator<P> it = getPersistentProperties(annotationType).iterator();
+		return it.hasNext() ? it.next() : null;
+	}
+
+	/**
+	 * Returns all properties equipped with an {@link Annotation} of the given type.
+	 *
+	 * @param annotationType must not be {@literal null}.
+	 * @return {@literal empty} {@link Iterator} if no match found. Never {@literal null}.
+	 * @since 2.0
+	 */
+	Iterable<P> getPersistentProperties(Class<? extends Annotation> annotationType);
 
 	/**
 	 * Returns whether the {@link PersistentEntity} has an id property. If this call returns {@literal true},
 	 * {@link #getIdProperty()} will return a non-{@literal null} value.
 	 *
-	 * @return
+	 * @return {@literal true} if entity has an {@literal id} property.
 	 */
 	boolean hasIdProperty();
 
 	/**
 	 * Returns whether the {@link PersistentEntity} has a version property. If this call returns {@literal true},
 	 * {@link #getVersionProperty()} will return a non-{@literal null} value.
 	 *
-	 * @return
+	 * @return {@literal true} if entity has a {@literal version} property.
 	 */
 	boolean hasVersionProperty();
 
 	/**
 	 * Returns the resolved Java type of this entity.
 	 *
-	 * @return The underlying Java class for this entity
+	 * @return The underlying Java class for this entity. Never {@literal null}.
 	 */
 	Class<T> getType();
 
@@ -194,6 +224,12 @@ default P getRequiredPersistentProperty(String name) {
 
 	void doWithProperties(SimplePropertyHandler handler);
 
+	/**
+	 * Get {@link Iterable}
+	 * 
+	 * @return
+	 * @since 2.0
+	 */
 	Iterable<P> getPersistentProperties();
 
 	/**
@@ -211,7 +247,7 @@ default P getRequiredPersistentProperty(String name) {
 	 * Looks up the annotation of the given type on the {@link PersistentEntity}.
 	 *
 	 * @param annotationType must not be {@literal null}.
-	 * @return
+	 * @return {@literal null} if not found.
 	 * @since 1.8
 	 */
 	<A extends Annotation> A findAnnotation(Class<A> annotationType);
@@ -220,7 +256,7 @@ default P getRequiredPersistentProperty(String name) {
 	 * Checks whether the annotation of the given type is present on the {@link PersistentEntity}.
 	 *
 	 * @param annotationType must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if {@link Annotation} of given type is present.
 	 * @since 2.0
 	 */
 	<A extends Annotation> boolean isAnnotationPresent(Class<A> annotationType);
@@ -229,7 +265,7 @@ default P getRequiredPersistentProperty(String name) {
 	 * Returns a {@link PersistentPropertyAccessor} to access property values of the given bean.
 	 *
 	 * @param bean must not be {@literal null}.
-	 * @return
+	 * @return new {@link PersistentPropertyAccessor}.
 	 * @since 1.10
 	 */
 	PersistentPropertyAccessor getPropertyAccessor(Object bean);
@@ -238,7 +274,7 @@ default P getRequiredPersistentProperty(String name) {
 	 * Returns the {@link IdentifierAccessor} for the given bean.
 	 *
 	 * @param bean must not be {@literal null}.
-	 * @return
+	 * @return new {@link IdentifierAccessor}.
 	 * @since 1.10
 	 */
 	IdentifierAccessor getIdentifierAccessor(Object bean);

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

@@ -35,7 +35,7 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 	/**
 	 * Returns the {@link PersistentEntity} owning the current {@link PersistentProperty}.
 	 *
-	 * @return
+	 * @return never {@literal null}.
 	 */
 	PersistentEntity<?, P> getOwner();
 
@@ -87,10 +87,22 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 
 	Field getField();
 
+	/**
+	 * @return {@literal null} if no expression defined.
+	 */
 	String getSpelExpression();
 
+	/**
+	 * @return {@literal null} if property is not part of an {@link Association}.
+	 */
 	Association<P> getAssociation();
 
+	/**
+	 * Get the {@link Association} of this property.
+	 *
+	 * @return never {@literal null}.
+	 * @throws IllegalStateException if not involved in an {@link Association}.
+	 */
 	default Association<P> getRequiredAssociation() {
 
 		Association<P> association = getAssociation();
@@ -106,7 +118,7 @@ default Association<P> getRequiredAssociation() {
 	 * Returns whether the type of the {@link PersistentProperty} is actually to be regarded as {@link PersistentEntity}
 	 * in turn.
 	 *
-	 * @return
+	 * @return {@literal true} a {@link PersistentEntity}.
 	 */
 	boolean isEntity();
 
@@ -116,7 +128,7 @@ default Association<P> getRequiredAssociation() {
 	 * {@link PersistentEntity} creation you should rather call {@link PersistentEntity#isIdProperty(PersistentProperty)}
 	 * to determine whether the current property is the id property of that {@link PersistentEntity} under consideration.
 	 *
-	 * @return
+	 * @return {@literal true} if the {@literal id} property.
 	 */
 	boolean isIdProperty();
 
@@ -210,7 +222,7 @@ default Association<P> getRequiredAssociation() {
 	 * potentially backing field and traverse accessor methods to potentially available super types.
 	 *
 	 * @param annotationType the annotation to look up, must not be {@literal null}.
-	 * @return the annotation of the given type.
+	 * @return the annotation of the given type. Can be {@literal null}.
 	 * @see AnnotationUtils#findAnnotation(Method, Class)
 	 */
 	<A extends Annotation> A findAnnotation(Class<A> annotationType);
@@ -220,7 +232,7 @@ default Association<P> getRequiredAssociation() {
 	 * Usefull to lookup annotations that can be configured on the type but overridden on an individual property.
 	 *
 	 * @param annotationType must not be {@literal null}.
-	 * @return
+	 * @return the annotation of the given type. Can be {@literal null}.
 	 */
 	<A extends Annotation> A findPropertyOrOwnerAnnotation(Class<A> annotationType);
 

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

@@ -35,7 +35,7 @@ public interface PersistentPropertyAccessor {
 	 *
 	 * @param property must not be {@literal null}.
 	 * @param value can be {@literal null}.
-	 * @throws org.springframework.data.mapping.model.MappingException in case an exception occurred when setting the
+	 * @throws MappingException in case an exception occurred when setting the
 	 *           property value.
 	 */
 	void setProperty(PersistentProperty<?> property, Object value);

src/main/java/org/springframework/data/mapping/context/AbstractMappingContext.java

@@ -44,7 +44,7 @@
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PropertyPath;
 import org.springframework.data.mapping.model.ClassGeneratingPropertyAccessorFactory;
-import org.springframework.data.mapping.model.MappingException;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.model.MutablePersistentEntity;
 import org.springframework.data.mapping.model.PersistentPropertyAccessorFactory;
 import org.springframework.data.mapping.model.Property;

src/main/java/org/springframework/data/mapping/context/InvalidPersistentPropertyPath.java

@@ -15,7 +15,7 @@
  */
 package org.springframework.data.mapping.context;
 
-import org.springframework.data.mapping.model.MappingException;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.util.Assert;