HHH-6970 - Expand notion of "natural id mutability" to ternary value

hibernate-core/src/main/java/org/hibernate/NaturalIdMutability.java

@@ -27,6 +27,8 @@ package org.hibernate;
  * Possible values regarding the mutability of a natural id.
  *
  * @author Steve Ebersole
+ *
+ * @see org.hibernate.annotations.NaturalId
  */
 public enum NaturalIdMutability {
 	/**
@@ -34,12 +36,14 @@ public enum NaturalIdMutability {
 	 * the entity to the database.  Also, it will invalidate any caching when such a change is detected.
 	 */
 	MUTABLE,
+
 	/**
 	 * The natural id is immutable.  Hibernate will ignore any changes in the natural id value when flushing updates
 	 * to the entity to the database.  Additionally Hibernate <b>will not</b> check with the database to check if the
 	 * natural id values change there.  Essentially the user is assuring Hibernate that the values will not change.
 	 */
 	IMMUTABLE,
+
 	/**
 	 * The natural id is immutable.  Hibernate will ignore any changes in the natural id value when flushing updates
 	 * to the entity to the database.  However, Hibernate <b>will</b> check with the database to check if the natural
@@ -50,5 +54,12 @@ public enum NaturalIdMutability {
 	 * as such.  The overhead of maintaining caching of natural ids in these cases is far greater than the benefit
 	 * from such caching.  In such cases, a database index is a much better solution.
 	 */
-	IMMUTABLE_CHECKED
+	IMMUTABLE_CHECKED,
+
+	/**
+	 * @deprecated Added in deprecated form solely to allow seamless working until the deprecated attribute
+	 * {@link org.hibernate.annotations.NaturalId#mutable()} can be removed.
+	 */
+	@Deprecated
+	UNSPECIFIED
 }

hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java

@@ -54,9 +54,13 @@ public @interface NaturalId {
 	boolean mutable() default false;
 
 	/**
-	 * The mutability behavior of this natural id
+	 * The mutability behavior of this natural id.
+	 * 
+	 * Note: the current default value is the {@link NaturalIdMutability#UNSPECIFIED} value which was added
+	 * in deprecated form until the deprecated {@link #mutable()} attribute here can be removed.  This lets existing
+	 * applications continue to work seamlessly using their existing natural id annotations.
 	 *
 	 * @return The mutability behavior.
 	 */
-	NaturalIdMutability mutability();
+	NaturalIdMutability mutability() default NaturalIdMutability.UNSPECIFIED;
 }