DATACMNS-1322 - Added @immutable to allow users to express a persistent entity to be considered immutable.

This is needed for downstream projects that attempt to merge persistent entity instances and previously didn't have a chance to detect that an object had to be set as-is instead of being merged recursively.

Author: odrotbohm

src/main/java/org/springframework/data/annotation/Immutable.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2018 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
+ *
+ * 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.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for persistent entities to indicate the class is designed in immutable way.
+ * 
+ * @author Oliver Gierke
+ * @since 2.1
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Immutable {
+}

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

@@ -18,6 +18,7 @@
 import java.lang.annotation.Annotation;
 import java.util.Iterator;
 
+import org.springframework.data.annotation.Immutable;
 import org.springframework.data.convert.EntityInstantiator;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
@@ -305,4 +306,14 @@ default <A extends Annotation> A getRequiredAnnotation(Class<A> annotationType)
 	 * @return whether the given bean is considered a new instance.
 	 */
 	boolean isNew(Object bean);
+
+	/**
+	 * Returns whether the entity is considered immutable, i.e. clients shouldn't attempt to change instances via the
+	 * {@link PersistentPropertyAccessor} obtained via {@link #getPropertyAccessor(Object)}.
+	 * 
+	 * @return
+	 * @see Immutable
+	 * @since 2.1
+	 */
+	boolean isImmutable();
 }

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

@@ -33,6 +33,7 @@
 import java.util.stream.Collectors;
 
 import org.springframework.core.annotation.AnnotatedElementUtils;
+import org.springframework.data.annotation.Immutable;
 import org.springframework.data.annotation.TypeAlias;
 import org.springframework.data.domain.Persistable;
 import org.springframework.data.mapping.Alias;
@@ -93,6 +94,7 @@ public class BasicPersistentEntity<T, P extends PersistentProperty<P>> implement
 
 	private final Lazy<Alias> typeAlias;
 	private final Lazy<IsNewStrategy> isNewStrategy;
+	private final Lazy<Boolean> isImmutable;
 
 	/**
 	 * Creates a new {@link BasicPersistentEntity} from the given {@link TypeInformation}.
@@ -130,7 +132,7 @@ public BasicPersistentEntity(TypeInformation<T> information, @Nullable Comparato
 		this.isNewStrategy = Lazy.of(() -> Persistable.class.isAssignableFrom(information.getType()) //
 				? PersistableIsNewStrategy.INSTANCE
 				: PersistentEntityIsNewStrategy.of(this));
-
+		this.isImmutable = Lazy.of(() -> isAnnotationPresent(Immutable.class));
 	}
 
 	/*
@@ -496,6 +498,15 @@ public boolean isNew(Object bean) {
 		return isNewStrategy.get().isNew(bean);
 	}
 
+	/* 
+	 * (non-Javadoc)
+	 * @see org.springframework.data.mapping.PersistentEntity#isImmutable()
+	 */
+	@Override
+	public boolean isImmutable() {
+		return isImmutable.get();
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Iterable#iterator()

src/test/java/org/springframework/data/mapping/model/BasicPersistentEntityUnitTests.java

@@ -41,6 +41,7 @@
 import org.springframework.data.annotation.AccessType.Type;
 import org.springframework.data.annotation.CreatedBy;
 import org.springframework.data.annotation.CreatedDate;
+import org.springframework.data.annotation.Immutable;
 import org.springframework.data.annotation.LastModifiedBy;
 import org.springframework.data.annotation.Persistent;
 import org.springframework.data.annotation.TypeAlias;
@@ -347,6 +348,13 @@ public void supportsPersistableViaIdentifierAccessor() {
 		assertThat(entity.getIdentifierAccessor(new PersistableEntity()).getRequiredIdentifier()).isEqualTo(4711L);
 	}
 
+	@Test // DATACMNS-1322
+	public void detectsImmutableEntity() {
+
+		assertThat(createEntity(SomeValue.class).isImmutable()).isTrue();
+		assertThat(createEntity(Entity.class).isImmutable()).isFalse();
+	}
+
 	private <S> BasicPersistentEntity<S, T> createEntity(Class<S> type) {
 		return createEntity(type, null);
 	}
@@ -416,4 +424,7 @@ public boolean isNew() {
 			return false;
 		}
 	}
+
+	@Immutable
+	static class SomeValue {}
 }