Merge remote-tracking branch 'origin/master'

Conflicts:
	hibernate-envers/src/main/java/org/hibernate/envers/configuration/metadata/AuditMetadataGenerator.java
	hibernate-envers/src/main/java/org/hibernate/envers/entities/mapper/relation/OneToOneNotOwningMapper.java
	hibernate-envers/src/main/java/org/hibernate/envers/entities/mapper/relation/ToOneIdMapper.java

documentation/src/main/docbook/manual/en-US/content/events.xml

@@ -147,11 +147,10 @@ public class AuditInterceptor extends EmptyInterceptor {
 
         <para>
             A <literal>Session</literal>-scoped interceptor is specified
-            when a session is opened using one of the overloaded SessionFactory.openSession()
-            methods accepting an <literal>Interceptor</literal>.
+            when a session is opened.
         </para>
 
-        <programlisting role="JAVA"><![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]></programlisting>
+        <programlisting role="JAVA"><![CDATA[Session session = sf.withOptions( new AuditInterceptor() ).openSession();]]></programlisting>
 
         <para>
             A <literal>SessionFactory</literal>-scoped interceptor is registered with the <literal>Configuration</literal>

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

@@ -246,7 +246,7 @@ public interface Criteria extends CriteriaSpecification {
 	 * @return this (for method chaining)
 	 *
 	 * @throws HibernateException Indicates a problem creating the sub criteria
-	 * @deprecated use {@link #createAlias(String, String, JoinType, Criterion}
+	 * @deprecated use {@link #createAlias(String, String, JoinType, Criterion)}
 	 */
 	@Deprecated
 	public Criteria createAlias(String associationPath, String alias, int joinType, Criterion withClause) throws HibernateException;
@@ -453,6 +453,7 @@ public interface Criteria extends CriteriaSpecification {
 	 *
 	 * @param readOnly true, entities and proxies loaded by the criteria will be put in read-only mode
 	 *                 false, entities and proxies loaded by the criteria will be put in modifiable mode
+	 * @return {@code this}, for method chaining
 	 */
 	public Criteria setReadOnly(boolean readOnly);
 

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

@@ -1,10 +1,10 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ * Copyright (c) 2008-2011, Red Hat Inc. or third-party contributors as
  * indicated by the @author tags or express copyright attribution
  * statements applied by the authors.  All third-party contributions are
- * distributed under license by Red Hat Middleware LLC.
+ * distributed under license by Red Hat Inc.
  *
  * This copyrighted material is made available to anyone wishing to use, modify,
  * copy, or redistribute it subject to the terms and conditions of the GNU
@@ -20,9 +20,9 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 import java.util.Iterator;
 
@@ -45,62 +45,134 @@
  * Instead of implementing this interface directly, it is usually better to extend <tt>EmptyInterceptor</tt>
  * and override only the callback methods of interest.
  *
- * @see SessionFactory#openSession(Interceptor)
+ * @see SessionBuilder#interceptor(Interceptor)
+ * @see SharedSessionBuilder#interceptor()
  * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
  * @see EmptyInterceptor
+ *
  * @author Gavin King
  */
 public interface Interceptor {
 	/**
 	 * Called just before an object is initialized. The interceptor may change the <tt>state</tt>, which will
 	 * be propagated to the persistent object. Note that when this method is called, <tt>entity</tt> will be
 	 * an empty uninitialized instance of the class.
+	 * <p/>
+	 * NOTE: The indexes across the <tt>state</tt>, <tt>propertyNames</tt> and <tt>types</tt> arrays match.
 	 *
-	 * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
+	 * @param entity The entity instance being loaded
+	 * @param id The identifier value being loaded
+	 * @param state The entity state (which will be pushed into the entity instance)
+	 * @param propertyNames The names of the entity properties, corresponding to the <tt>state</tt>.
+	 * @param types The types of the entity properties, corresponding to the <tt>state</tt>.
+	 *
+	 * @return {@code true} if the user modified the <tt>state</tt> in any way.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public boolean onLoad(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
+
 	/**
 	 * Called when an object is detected to be dirty, during a flush. The interceptor may modify the detected
 	 * <tt>currentState</tt>, which will be propagated to both the database and the persistent object.
 	 * Note that not all flushes end in actual synchronization with the database, in which case the
 	 * new <tt>currentState</tt> will be propagated to the object, but not necessarily (immediately) to
 	 * the database. It is strongly recommended that the interceptor <b>not</b> modify the <tt>previousState</tt>.
+	 * <p/>
+	 * NOTE: The indexes across the <tt>currentState</tt>, <tt>previousState</tt>, <tt>propertyNames</tt> and
+	 * <tt>types</tt> arrays match.
+	 *
+	 * @param entity The entity instance detected as being dirty and being flushed
+	 * @param id The identifier of the entity
+	 * @param currentState The entity's current state
+	 * @param previousState The entity's previous (load time) state.
+	 * @param propertyNames The names of the entity properties
+	 * @param types The types of the entity properties
+	 *
+	 * @return {@code true} if the user modified the <tt>currentState</tt> in any way.
 	 *
-	 * @return <tt>true</tt> if the user modified the <tt>currentState</tt> in any way.
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public boolean onFlushDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types) throws CallbackException;
+
 	/**
 	 * Called before an object is saved. The interceptor may modify the <tt>state</tt>, which will be used for
 	 * the SQL <tt>INSERT</tt> and propagated to the persistent object.
 	 *
+	 * @param entity The entity instance whose state is being inserted
+	 * @param id The identifier of the entity
+	 * @param state The state of the entity which will be inserted
+	 * @param propertyNames The names of the entity properties.
+	 * @param types The types of the entity properties
+	 *
 	 * @return <tt>true</tt> if the user modified the <tt>state</tt> in any way.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public boolean onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
+
 	/**
 	 *  Called before an object is deleted. It is not recommended that the interceptor modify the <tt>state</tt>.
+	 *
+	 * @param entity The entity instance being deleted
+	 * @param id The identifier of the entity
+	 * @param state The state of the entity
+	 * @param propertyNames The names of the entity properties.
+	 * @param types The types of the entity properties
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void onDelete(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types) throws CallbackException;
+
 	/**
 	 * Called before a collection is (re)created.
+	 *
+	 * @param collection The collection instance.
+	 * @param key The collection key value.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException;
+
 	/**
 	 * Called before a collection is deleted.
+	 *
+	 * @param collection The collection instance.
+	 * @param key The collection key value.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void onCollectionRemove(Object collection, Serializable key) throws CallbackException;
+
 	/**
 	 * Called before a collection is updated.
+	 *
+	 * @param collection The collection instance.
+	 * @param key The collection key value.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException;
+
 	/**
 	 * Called before a flush
+	 *
+	 * @param entities The entities to be flushed
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void preFlush(Iterator entities) throws CallbackException;
+
 	/**
 	 * Called after a flush that actually ends in execution of the SQL statements required to synchronize
 	 * in-memory state with the database.
+	 *
+	 * @param entities The entities that were flushed.
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public void postFlush(Iterator entities) throws CallbackException;
+
 	/**
 	 * Called to distinguish between transient and detached entities. The return value determines the
 	 * state of the entity with respect to the current session.
@@ -114,15 +186,25 @@ public interface Interceptor {
 	 * @return Boolean or <tt>null</tt> to choose default behaviour
 	 */
 	public Boolean isTransient(Object entity);
+
 	/**
 	 * Called from <tt>flush()</tt>. The return value determines whether the entity is updated
 	 * <ul>
 	 * <li>an array of property indices - the entity is dirty
 	 * <li>an empty array - the entity is not dirty
 	 * <li><tt>null</tt> - use Hibernate's default dirty-checking algorithm
 	 * </ul>
-	 * @param entity a persistent entity
-	 * @return array of dirty property indices or <tt>null</tt> to choose default behaviour
+	 *
+	 * @param entity The entity for which to find dirty properties.
+	 * @param id The identifier of the entity
+	 * @param currentState The current entity state as taken from the entity instance
+	 * @param previousState The state of the entity when it was last synchronized (generally when it was loaded)
+	 * @param propertyNames The names of the entity properties.
+	 * @param types The types of the entity properties
+	 *
+	 * @return array of dirty property indices or {@code null} to indicate Hibernate should perform default behaviour
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public int[] findDirty(Object entity, Serializable id, Object[] currentState, Object[] previousState, String[] propertyNames, Type[] types);
 	/**
@@ -134,13 +216,17 @@ public interface Interceptor {
 	 * @param entityMode The type of entity instance to be returned.
 	 * @param id the identifier of the new instance
 	 * @return an instance of the class, or <tt>null</tt> to choose default behaviour
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public Object instantiate(String entityName, EntityMode entityMode, Serializable id) throws CallbackException;
 
 	/**
 	 * Get the entity name for a persistent or transient instance
 	 * @param object an entity instance
 	 * @return the name of the entity
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public String getEntityName(Object object) throws CallbackException;
 
@@ -149,22 +235,31 @@ public interface Interceptor {
 	 * @param entityName the name of the entity
 	 * @param id the instance identifier
 	 * @return a fully initialized entity
-	 * @throws CallbackException
+	 *
+	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
 	public Object getEntity(String entityName, Serializable id) throws CallbackException;
 
 	/**
 	 * Called when a Hibernate transaction is begun via the Hibernate <tt>Transaction</tt> 
 	 * API. Will not be called if transactions are being controlled via some other 
 	 * mechanism (CMT, for example).
+	 *
+	 * @param tx The Hibernate transaction facade object
 	 */
 	public void afterTransactionBegin(Transaction tx);
+
 	/**
 	 * Called before a transaction is committed (but not before rollback).
+	 *
+	 * @param tx The Hibernate transaction facade object
 	 */
 	public void beforeTransactionCompletion(Transaction tx);
+
 	/**
 	 * Called after a transaction is committed or rolled back.
+	 *
+	 * @param tx The Hibernate transaction facade object
 	 */
 	public void afterTransactionCompletion(Transaction tx);
 

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

@@ -0,0 +1,65 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * Copyright (c) 2012, Red Hat Inc. or third-party contributors as
+ * indicated by the @author tags or express copyright attribution
+ * statements applied by the authors.  All third-party contributions are
+ * distributed under license by Red Hat Inc.
+ *
+ * This copyrighted material is made available to anyone wishing to use, modify,
+ * copy, or redistribute it subject to the terms and conditions of the GNU
+ * Lesser General Public License, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this distribution; if not, write to:
+ * Free Software Foundation, Inc.
+ * 51 Franklin Street, Fifth Floor
+ * Boston, MA  02110-1301  USA
+ */
+package org.hibernate;
+
+/**
+ * Possible values regarding the mutability of a natural id.
+ *
+ * @author Steve Ebersole
+ *
+ * @see org.hibernate.annotations.NaturalId
+ */
+public enum NaturalIdMutability {
+	/**
+	 * The natural id is mutable.  Hibernate will write changes in the natural id value when flushing updates to the
+	 * 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
+	 * id values change there.  This will ensure caching gets invalidated if the natural id value is changed in the
+	 * database (outside of this Hibernate SessionFactory).
+	 *
+	 * Note however that frequently changing natural ids are really not natural ids and should really not be mapped
+	 * 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,
+
+	/**
+	 * @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
+}