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.

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

@@ -1,11 +1,11 @@
 /*
- * 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,
@@ -13,8 +13,7 @@
  * 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 <jbrisbin@vmware.com>

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 @@ import org.springframework.data.util.TypeInformation;
  * @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 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 */
 	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,7 +131,7 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	/**
 	 * 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);
@@ -122,9 +139,9 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	/**
 	 * 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,19 +155,32 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	}
 
 	/**
-	 * 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();
 
@@ -158,14 +188,14 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 
 	void doWithProperties(SimplePropertyHandler handler);
 
+	/**
+	 * Get {@link Iterable}
+	 * 
+	 * @return
+	 * @since 2.0
+	 */
 	Iterable<P> getPersistentProperties();
 
 	/**
@@ -211,7 +247,7 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentEntity<T, P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 	 * {@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 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 	 * 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 @@ public interface PersistentProperty<P extends PersistentProperty<P>> {
 	 * 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.PersistentEntity;
 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;
 

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

@@ -20,6 +20,7 @@ import java.util.Collection;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PropertyPath;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.util.TypeInformation;
 
 /**
@@ -31,13 +32,14 @@ import org.springframework.data.util.TypeInformation;
  * @author Jon Brisbin
  * @author Graeme Rocher
  * @author Mark Paluch
+ * @author Christoph Strobl
  */
 public interface MappingContext<E extends PersistentEntity<?, P>, P extends PersistentProperty<P>> {
 
 	/**
 	 * Returns all {@link PersistentEntity}s held in the context.
 	 *
-	 * @return
+	 * @return never {@literal null}.
 	 */
 	Collection<E> getPersistentEntities();
 
@@ -47,7 +49,7 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 	 *
 	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
 	 * @param type must not be {@literal null}.
-	 * @return
+	 * @return {@literal null} if no {@link PersistentEntity} found for {@literal type}.
 	 */
 	E getPersistentEntity(Class<?> type);
 
@@ -57,7 +59,9 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 	 *
 	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
 	 * @param type must not be {@literal null}.
-	 * @return
+	 * @return never {@literal null}.
+	 * @throws MappingException when no {@link PersistentEntity} can be found for given {@literal type}.
+	 * @since 2.0
 	 */
 	default E getRequiredPersistentEntity(Class<?> type) {
 
@@ -67,14 +71,14 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 			return entity;
 		}
 
-		throw new IllegalArgumentException(String.format("Couldn't find PersistentEntity for type %s!", type));
+		throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
 	}
 
 	/**
 	 * Returns whether the {@link MappingContext} currently contains a {@link PersistentEntity} for the type.
 	 *
 	 * @param type must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if {@link PersistentEntity} present for given {@literal type}.
 	 * @since 1.8
 	 */
 	boolean hasPersistentEntityFor(Class<?> type);
@@ -85,7 +89,7 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 	 *
 	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
 	 * @param type must not be {@literal null}.
-	 * @return
+	 * @return {@literal null} if no {@link PersistentEntity} found for {@link TypeInformation}.
 	 */
 	E getPersistentEntity(TypeInformation<?> type);
 
@@ -95,7 +99,8 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 	 *
 	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
 	 * @param type must not be {@literal null}.
-	 * @return
+	 * @return never {@literal null}.
+	 * @throws MappingException when no {@link PersistentEntity} can be found for given {@link TypeInformation}.
 	 */
 	default E getRequiredPersistentEntity(TypeInformation<?> type) {
 
@@ -105,7 +110,7 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 			return entity;
 		}
 
-		throw new IllegalArgumentException(String.format("Couldn't find PersistentEntity for type %s!", type));
+		throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
 	}
 
 	/**
@@ -123,10 +128,12 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 	 * Returns the {@link PersistentEntity} mapped by the given {@link PersistentProperty}.
 	 *
 	 * @param persistentProperty must not be {@literal null}.
-	 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or null if no
+	 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or {@literal null} if no
 	 *         {@link PersistentEntity} exists for it or the {@link PersistentProperty} does not refer to an entity (the
 	 *         type of the property is considered simple see
 	 *         {@link org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)}).
+	 * @throws MappingException when no {@link PersistentEntity} can be found for given
+	 *           {@link PersistentProperty}.
 	 */
 	default E getRequiredPersistentEntity(P persistentProperty) {
 
@@ -136,7 +143,7 @@ public interface MappingContext<E extends PersistentEntity<?, P>, P extends Pers
 			return entity;
 		}
 
-		throw new IllegalArgumentException(
+		throw new MappingException(
 				String.format("Couldn't find PersistentEntity for property %s!", persistentProperty));
 	}
 

src/main/java/org/springframework/data/mapping/model/AnnotationBasedPersistentProperty.java

@@ -34,6 +34,7 @@ import org.springframework.data.annotation.Reference;
 import org.springframework.data.annotation.Transient;
 import org.springframework.data.annotation.Version;
 import org.springframework.data.mapping.Association;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.util.Lazy;
@@ -65,8 +66,9 @@ public abstract class AnnotationBasedPersistentProperty<P extends PersistentProp
 	private final Lazy<Boolean> isTransient = Lazy.of(() -> super.isTransient() || isAnnotationPresent(Transient.class)
 			|| isAnnotationPresent(Value.class) || isAnnotationPresent(Autowired.class));
 
-	private final Lazy<Boolean> writable = Lazy.of(() -> !isTransient() && !isAnnotationPresent(ReadOnlyProperty.class));
-	private final Lazy<Boolean> reference = Lazy.of(() -> !isTransient() && isAnnotationPresent(Reference.class));
+	private final Lazy<Boolean> isWritable = Lazy
+			.of(() -> !isTransient() && !isAnnotationPresent(ReadOnlyProperty.class));
+	private final Lazy<Boolean> isReference = Lazy.of(() -> !isTransient() && isAnnotationPresent(Reference.class));
 	private final Lazy<Boolean> isId = Lazy.of(() -> isAnnotationPresent(Id.class));
 	private final Lazy<Boolean> isVersion = Lazy.of(() -> isAnnotationPresent(Version.class));
 
@@ -194,7 +196,7 @@ public abstract class AnnotationBasedPersistentProperty<P extends PersistentProp
 	 */
 	@Override
 	public boolean isAssociation() {
-		return reference.get();
+		return isReference.get();
 	}
 
 	/*
@@ -203,7 +205,7 @@ public abstract class AnnotationBasedPersistentProperty<P extends PersistentProp
 	 */
 	@Override
 	public boolean isWritable() {
-		return writable.get();
+		return isWritable.get();
 	}
 
 	/**
@@ -212,9 +214,8 @@ public abstract class AnnotationBasedPersistentProperty<P extends PersistentProp
 	 * subclasses.
 	 *
 	 * @param annotationType must not be {@literal null}.
-	 * @return
+	 * @return {@literal null} if annotation type not found on property.
 	 */
-
 	public <A extends Annotation> A findAnnotation(Class<A> annotationType) {
 
 		Assert.notNull(annotationType, "Annotation type must not be null!");

src/main/java/org/springframework/data/mapping/model/BasicPersistentEntity.java

@@ -21,6 +21,7 @@ import lombok.RequiredArgsConstructor;
 import java.io.Serializable;
 import java.lang.annotation.Annotation;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -29,6 +30,7 @@ import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 import java.util.TreeSet;
+import java.util.stream.Collectors;
 
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.data.annotation.TypeAlias;
@@ -36,6 +38,7 @@ import org.springframework.data.mapping.Alias;
 import org.springframework.data.mapping.Association;
 import org.springframework.data.mapping.AssociationHandler;
 import org.springframework.data.mapping.IdentifierAccessor;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PersistentPropertyAccessor;
@@ -47,6 +50,8 @@ import org.springframework.data.mapping.TargetAwareIdentifierAccessor;
 import org.springframework.data.util.Lazy;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.util.Assert;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
 import org.springframework.util.StringUtils;
 
 /**
@@ -72,7 +77,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	private final Map<String, P> propertyCache;
 	private final Map<Class<? extends Annotation>, Optional<Annotation>> annotationCache;
-	private final Map<Class<? extends Annotation>, Optional<P>> propertyAnnotationCache;
+	private final MultiValueMap<Class<? extends Annotation>, P> propertyAnnotationCache;
 
 	private P idProperty;
 	private P versionProperty;
@@ -106,11 +111,11 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 		this.persistentPropertiesCache = new ArrayList<>();
 		this.comparator = comparator;
 		this.constructor = new PreferredConstructorDiscoverer<>(this).getConstructor();
-		this.associations = comparator == null ? new HashSet<>() : new TreeSet<>(new AssociationComparator<P>(comparator));
+		this.associations = comparator == null ? new HashSet<>() : new TreeSet<>(new AssociationComparator<>(comparator));
 
 		this.propertyCache = new HashMap<>();
 		this.annotationCache = new HashMap<>();
-		this.propertyAnnotationCache = new HashMap<>();
+		this.propertyAnnotationCache = new LinkedMultiValueMap<>();
 		this.propertyAccessorFactory = BeanWrapperPropertyAccessorFactory.INSTANCE;
 		this.typeAlias = Lazy.of(() -> getAliasFromAnnotation(getType()));
 	}
@@ -189,7 +194,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	/*
 	 * (non-Javadoc)
-	 * @see org.springframework.data.mapping.MutablePersistentEntity#addPersistentProperty(P)
+	 * @see org.springframework.data.mapping.model.MutablePersistentEntity#addPersistentProperty(P)
 	 */
 	public void addPersistentProperty(P property) {
 
@@ -251,7 +256,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	/*
 	 * (non-Javadoc)
-	 * @see org.springframework.data.mapping.MutablePersistentEntity#addAssociation(org.springframework.data.mapping.model.Association)
+	 * @see org.springframework.data.mapping.model.MutablePersistentEntity#addAssociation(org.springframework.data.mapping.model.Association)
 	 */
 	public void addAssociation(Association<P> association) {
 
@@ -266,36 +271,35 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 	 * (non-Javadoc)
 	 * @see org.springframework.data.mapping.PersistentEntity#getPersistentProperty(java.lang.String)
 	 */
+	@Override
 	public P getPersistentProperty(String name) {
 		return propertyCache.get(name);
 	}
 
 	/*
 	 * (non-Javadoc)
-	 * @see org.springframework.data.mapping.PersistentEntity#getPersistentProperty(java.lang.Class)
+	 * @see org.springframework.data.mapping.PersistentEntity#getPersistentProperties(java.lang.String)
 	 */
 	@Override
-	public P getPersistentProperty(Class<? extends Annotation> annotationType) {
+	public Iterable<P> getPersistentProperties(Class<? extends Annotation> annotationType) {
 
 		Assert.notNull(annotationType, "Annotation type must not be null!");
-
-		return propertyAnnotationCache.computeIfAbsent(annotationType, this::doFindPersistentProperty).orElse(null);
+		return propertyAnnotationCache.computeIfAbsent(annotationType, this::doFindPersistentProperty);
 	}
 
-	private Optional<P> doFindPersistentProperty(Class<? extends Annotation> annotationType) {
+	private List<P> doFindPersistentProperty(Class<? extends Annotation> annotationType) {
 
-		Optional<P> property = properties.stream() //
+		List<P> annotatedProperties = properties.stream() //
 				.filter(it -> it.isAnnotationPresent(annotationType)) //
-				.findAny();
+				.collect(Collectors.toList());
 
-		if (property.isPresent()) {
-
-			return property;
+		if (!annotatedProperties.isEmpty()) {
+			return annotatedProperties;
 		}
 
 		return associations.stream() //
 				.map(Association::getInverse) //
-				.filter(it -> it.isAnnotationPresent(annotationType)).findAny();
+				.filter(it -> it.isAnnotationPresent(annotationType)).collect(Collectors.toList());
 	}
 
 	/*
@@ -354,8 +358,8 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 	 * @see org.springframework.data.mapping.PersistentEntity#getPersistentProperties()
 	 */
 	@Override
-	public Iterable<P> getPersistentProperties() {
-		return persistentPropertiesCache;
+	public List<P> getPersistentProperties() {
+		return Collections.unmodifiableList(persistentPropertiesCache);
 	}
 
 	/*
@@ -389,8 +393,8 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 	 * @see org.springframework.data.mapping.PersistentEntity#getAssociations()
 	 */
 	@Override
-	public Iterable<Association<P>> getAssociations() {
-		return associations;
+	public Set<Association<P>> getAssociations() {
+		return Collections.unmodifiableSet(associations);
 	}
 
 	/*
@@ -400,7 +404,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 	@Override
 	@SuppressWarnings("unchecked")
 	public <A extends Annotation> A findAnnotation(Class<A> annotationType) {
-		return (A) doFindAnnotation(annotationType).orElse(null);
+		return doFindAnnotation(annotationType).orElse(null);
 	}
 
 	/*
@@ -412,15 +416,15 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 		return doFindAnnotation(annotationType).isPresent();
 	}
 
-	private <A extends Annotation> Optional<Annotation> doFindAnnotation(Class<A> annotationType) {
+	private <A extends Annotation> Optional<A> doFindAnnotation(Class<A> annotationType) {
 
-		return annotationCache.computeIfAbsent(annotationType,
+		return (Optional<A>) annotationCache.computeIfAbsent(annotationType,
 				it -> Optional.ofNullable(AnnotatedElementUtils.findMergedAnnotation(getType(), it)));
 	}
 
 	/*
 	 * (non-Javadoc)
-	 * @see org.springframework.data.mapping.MutablePersistentEntity#verify()
+	 * @see org.springframework.data.mapping.model.MutablePersistentEntity#verify()
 	 */
 	public void verify() {
 
@@ -469,7 +473,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	/**
 	 * Calculates the {@link Alias} to be used for the given type.
-	 * 
+	 *
 	 * @param type must not be {@literal null}.
 	 * @return
 	 */

src/main/java/org/springframework/data/mapping/model/BeanWrapper.java

@@ -18,6 +18,7 @@ package org.springframework.data.mapping.model;
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PersistentPropertyAccessor;
 import org.springframework.util.Assert;

src/main/java/org/springframework/data/mapping/model/IllegalMappingException.java

@@ -1,37 +0,0 @@
-/* Copyright (C) 2010 SpringSource
- *
- * 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
- *
- * 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;
-
-/**
- * Thrown when an error occurs reading the mapping between object and datastore
- * 
- * @author Graeme Rocher
- * @since 1.0
- */
-public class IllegalMappingException extends RuntimeException {
-
-	/**
-	 *
-	 */
-	private static final long serialVersionUID = 1L;
-
-	public IllegalMappingException(String s, Throwable throwable) {
-		super(s, throwable);
-	}
-
-	public IllegalMappingException(String s) {
-		super(s);
-	}
-}

src/main/java/org/springframework/data/mapping/model/MutablePersistentEntity.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011-2016 by the original author(s).
+ * Copyright 2011-2017 the original authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 package org.springframework.data.mapping.model;
 
 import org.springframework.data.mapping.Association;
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PersistentPropertyAccessor;

src/main/java/org/springframework/data/mapping/model/PersistentEntityParameterValueProvider.java

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.mapping.model;
 
+import org.springframework.data.mapping.MappingException;
 import org.springframework.data.mapping.PersistentEntity;
 import org.springframework.data.mapping.PersistentProperty;
 import org.springframework.data.mapping.PreferredConstructor;