HHH-8159 - Apply fixups indicated by analysis tools

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

@@ -23,25 +23,30 @@
  */
 package org.hibernate;
 
-
 /**
  * Annotation related exception.
- * The EJB3 EG will probably set a generic exception.
+ *
- * I'll then use this one.
+ * The EJB3 EG will probably set a generic exception.  I'll then use this one.
  *
  * @author Emmanuel Bernard
  */
 public class AnnotationException extends MappingException {
-
+	/**
-	public AnnotationException(String msg, Throwable root) {
+	 * Constructs an AnnotationException using the given message and cause.
-		super( msg, root );
+	 *
+	 * @param msg The message explaining the reason for the exception.
+	 * @param cause The underlying cause.
+	 */
+	public AnnotationException(String msg, Throwable cause) {
+		super( msg, cause );
 	}
 
-	public AnnotationException(Throwable root) {
+	/**
-		super( root );
+	 * Constructs an AnnotationException using the given message.
-	}
+	 *
-
+	 * @param msg The message explaining the reason for the exception.
-	public AnnotationException(String s) {
+	 */
-		super( s );
+	public AnnotationException(String msg) {
+		super( msg );
 	}
 }

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

@@ -33,19 +33,28 @@ import org.hibernate.internal.CoreMessageLogger;
  * @author Gavin King
  */
 public class AssertionFailure extends RuntimeException {
-
     private static final long serialVersionUID = 1L;
 
     private static final CoreMessageLogger LOG = Logger.getMessageLogger(CoreMessageLogger.class, AssertionFailure.class.getName());
 
-    public AssertionFailure( String s ) {
+	/**
-        super(s);
+	 * Creates an instance of AssertionFailure using the given message.
-        LOG.failed(this);
+	 *
+	 * @param message The message explaining the reason for the exception
+	 */
+    public AssertionFailure(String message) {
+        super( message );
+        LOG.failed( this );
     }
 
-    public AssertionFailure( String s,
+	/**
-                             Throwable t ) {
+	 * Creates an instance of AssertionFailure using the given message and underlying cause.
-        super(s, t);
+	 *
-        LOG.failed(t);
+	 * @param message The message explaining the reason for the exception
+	 * @param cause The underlying cause.
+	 */
+    public AssertionFailure(String message, Throwable cause) {
+        super( message, cause );
+        LOG.failed( cause );
     }
 }

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

@@ -47,6 +47,8 @@ public interface BasicQueryContract {
 	 *
 	 * @param flushMode The new FlushMode to use.
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getFlushMode()
 	 */
 	public BasicQueryContract setFlushMode(FlushMode flushMode);
@@ -70,6 +72,8 @@ public interface BasicQueryContract {
 	 *
 	 * @param cacheMode The new CacheMode to use.
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getCacheMode()
 	 */
 	public BasicQueryContract setCacheMode(CacheMode cacheMode);
@@ -93,6 +97,8 @@ public interface BasicQueryContract {
 	 *
 	 * @param cacheable Should the query results be cacheable?
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #isCacheable
 	 */
 	public BasicQueryContract setCacheable(boolean cacheable);
@@ -113,6 +119,8 @@ public interface BasicQueryContract {
 	 * @param cacheRegion the name of a query cache region, or {@code null} to indicate that the default region
 	 * should be used.
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getCacheRegion()
 	 */
 	public BasicQueryContract setCacheRegion(String cacheRegion);
@@ -136,6 +144,8 @@ public interface BasicQueryContract {
 	 *
 	 * @param timeout the timeout <b>in seconds</b>
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getTimeout()
 	 */
 	public BasicQueryContract setTimeout(int timeout);
@@ -160,6 +170,8 @@ public interface BasicQueryContract {
 	 *
 	 * @param fetchSize the fetch size hint
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getFetchSize()
 	 */
 	public BasicQueryContract setFetchSize(int fetchSize);
@@ -201,6 +213,8 @@ public interface BasicQueryContract {
 	 * The read-only/modifiable setting has no impact on entities/proxies
 	 * returned by the query that existed in the session before the query was executed.
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @param readOnly true, entities and proxies loaded by the query will be put in read-only mode
 	 *                 false, entities and proxies loaded by the query will be put in modifiable mode
 	 */
@@ -211,5 +225,5 @@ public interface BasicQueryContract {
 	 *
 	 * @return an array of types
 	 */
-	public Type[] getReturnTypes() throws HibernateException;
+	public Type[] getReturnTypes();
 }

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

@@ -23,30 +23,26 @@
  */
 package org.hibernate;
 
-import org.hibernate.tool.hbm2ddl.SchemaExportTask;
-
 /**
- * Controls how the session interacts with the second-level
+ * Controls how the session interacts with the second-level cache and query cache.
- * cache and query cache.
  *
  * @author Gavin King
  * @author Strong Liu
  * @see Session#setCacheMode(CacheMode)
  */
 public enum CacheMode {
-
 	/**
-	 * The session may read items from the cache, and add items to the cache
+	 * The session may read items from the cache, and add items to the cache.
 	 */
 	NORMAL( true, true ),
 	/**
 	 * The session will never interact with the cache, except to invalidate
-	 * cache items when updates occur
+	 * cache items when updates occur.
 	 */
 	IGNORE( false, false ),
 	/**
 	 * The session may read items from the cache, but will not add items,
-	 * except to invalidate items when updates occur
+	 * except to invalidate items when updates occur.
 	 */
 	GET( false, true ),
 	/**
@@ -56,9 +52,9 @@ public enum CacheMode {
 	PUT( true, false ),
 	/**
 	 * The session will never read items from the cache, but will add items
-	 * to the cache as it reads them from the database. In this mode, the
+	 * to the cache as it reads them from the database.  In this mode, the
 	 * effect of <tt>hibernate.cache.use_minimal_puts</tt> is bypassed, in
-	 * order to <em>force</em> a cache refresh
+	 * order to <em>force</em> a cache refresh.
 	 */
 	REFRESH( true, false );
 
@@ -66,19 +62,38 @@ public enum CacheMode {
 	private final boolean isPutEnabled;
 	private final boolean isGetEnabled;
 
-	CacheMode( boolean isPutEnabled, boolean isGetEnabled) {
+	private CacheMode( boolean isPutEnabled, boolean isGetEnabled) {
 		this.isPutEnabled = isPutEnabled;
 		this.isGetEnabled = isGetEnabled;
 	}
 
+	/**
+	 * Does this cache mode indicate that reads are allowed?
+	 *
+	 * @return {@code true} if cache reads are allowed; {@code false} otherwise.
+	 */
 	public boolean isGetEnabled() {
 		return isGetEnabled;
 	}
 
+	/**
+	 * Does this cache mode indicate that writes are allowed?
+	 *
+	 * @return {@code true} if cache writes are allowed; {@code false} otherwise.
+	 */
 	public boolean isPutEnabled() {
 		return isPutEnabled;
 	}
 
+	/**
+	 * Used to interpret externalized forms of this enum.
+	 *
+	 * @param setting The externalized form.
+	 *
+	 * @return The matching enum value.
+	 *
+	 * @throws MappingException Indicates the external form was not recognized as a valid enum value.
+	 */
 	public static CacheMode interpretExternalSetting(String setting) {
 		if (setting == null) {
 			return null;

hibernate-core/src/main/java/org/hibernate/CallbackException.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, 2013, 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,38 +20,44 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
- * Should be thrown by persistent objects from <tt>Lifecycle</tt>
+ * Intended to be thrown from {@link org.hibernate.classic.Lifecycle} and {@link Interceptor} callbacks.
- * or <tt>Interceptor</tt> callbacks.
+ * <p/>
+ * IMPL NOTE : This is a legacy exception type from back in the day before Hibernate moved to a untyped (runtime)
+ * exception strategy.
  *
- * @see org.hibernate.classic.Lifecycle
- * @see Interceptor
  * @author Gavin King
  */
-
 public class CallbackException extends HibernateException {
-
+	/**
-	public CallbackException(Exception root) {
+	 * Creates a CallbackException using the given underlying cause.
-		super("An exception occurred in a callback", root);
+	 *
+	 * @param cause The underlying cause
+	 */
+	public CallbackException(Exception cause) {
+		this( "An exception occurred in a callback", cause );
 	}
 
+	/**
+	 * Creates a CallbackException using the given message.
+	 *
+	 * @param message The message explaining the reason for the exception
+	 */
 	public CallbackException(String message) {
-		super(message);
+		super( message );
 	}
 
-	public CallbackException(String message, Exception e) {
+	/**
-		super(message, e);
+	 * Creates a CallbackException using the given message and underlying cause.
+	 *
+	 * @param message The message explaining the reason for the exception
+	 * @param cause The underlying cause
+	 */
+	public CallbackException(String message, Exception cause) {
+		super( message, cause );
 	}
 
 }
-
-
-
-
-
-

hibernate-core/src/main/java/org/hibernate/ConnectionReleaseMode.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, 2013, 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,7 +20,6 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
@@ -31,7 +30,6 @@ package org.hibernate;
  * @author Steve Ebersole
  */
 public enum ConnectionReleaseMode{
-
 	/**
 	 * Indicates that JDBC connection should be aggressively released after each 
 	 * SQL statement is executed. In this mode, the application <em>must</em>
@@ -55,7 +53,14 @@ public enum ConnectionReleaseMode{
 	 */
 	ON_CLOSE;
 
-	public static ConnectionReleaseMode parse(String name){
+	/**
+	 * Alias for {@link ConnectionReleaseMode#valueOf(String)} using upper-case version of the incoming name.
+	 *
+	 * @param name The name to parse
+	 *
+	 * @return The matched enum value.
+	 */
+	public static ConnectionReleaseMode parse(final String name){
 		return ConnectionReleaseMode.valueOf( name.toUpperCase() );
 	}
 }

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

@@ -143,7 +143,7 @@ public interface Criteria extends CriteriaSpecification {
 	public Criteria setFetchMode(String associationPath, FetchMode mode) throws HibernateException;
 
 	/**
-	 * Set the lock mode of the current entity
+	 * Set the lock mode of the current entity.
 	 *
 	 * @param lockMode The lock mode to be applied
 	 *
@@ -152,7 +152,7 @@ public interface Criteria extends CriteriaSpecification {
 	public Criteria setLockMode(LockMode lockMode);
 
 	/**
-	 * Set the lock mode of the aliased entity
+	 * Set the lock mode of the aliased entity.
 	 *
 	 * @param alias The previously assigned alias representing the entity to
 	 *			which the given lock mode should apply.
@@ -533,7 +533,7 @@ public interface Criteria extends CriteriaSpecification {
 	public List list() throws HibernateException;
 	
 	/**
-	 * Get the results as an instance of {@link ScrollableResults}
+	 * Get the results as an instance of {@link ScrollableResults}.
 	 *
 	 * @return The {@link ScrollableResults} representing the matched
 	 * query results.

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

@@ -94,7 +94,7 @@ public interface CustomEntityDirtinessStrategy {
 	public static interface DirtyCheckContext {
 		/**
 		 * The callback to indicate that dirty checking (the dirty attribute determination phase) should be handled
-		 * by the calling {@link CustomEntityDirtinessStrategy} using the given {@link AttributeChecker}
+		 * by the calling {@link CustomEntityDirtinessStrategy} using the given {@link AttributeChecker}.
 		 *
 		 * @param attributeChecker The delegate usable by the context for determining which attributes are dirty.
 		 */
@@ -139,7 +139,7 @@ public interface CustomEntityDirtinessStrategy {
 		public int getAttributeIndex();
 
 		/**
-		 * Get the name of this attribute
+		 * Get the name of this attribute.
 		 *
 		 * @return The attribute name
 		 */

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

@@ -1,7 +1,7 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2008-2011, Red Hat Inc. 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 Inc.
@@ -24,36 +24,80 @@
 package org.hibernate;
 
 /**
- * Raised whenever a duplicate for a certain type occurs.
+ * Raised whenever a duplicate for a certain type occurs.  Duplicate class, table, property name etc.
- * Duplicate class, table, property name etc.
  * 
  * @author Max Rydahl Andersen
  * @author Steve Ebersole
  */
 public class DuplicateMappingException extends MappingException {
+	/**
+	 * Enumeration of the types of things that can be duplicated.
+	 */
 	public static enum Type {
+		/**
+		 * A duplicate entity definition was encountered.
+		 */
 		ENTITY,
+		/**
+		 * A duplicate table definition was encountered.
+		 */
 		TABLE,
+		/**
+		 * A duplicate property/attribute definition was encountered.
+		 */
 		PROPERTY,
+		/**
+		 * A duplicate column definition was encountered.
+		 */
 		COLUMN
 	}
 
 	private final String name;
 	private final String type;
 
+	/**
+	 * Creates a DuplicateMappingException using the given type and name.
+	 *
+	 * @param type The type of the duplicated thing.
+	 * @param name The name of the duplicated thing.
+	 */
 	public DuplicateMappingException(Type type, String name) {
 		this( type.name(), name );
 	}
 
+	/**
+	 * Creates a DuplicateMappingException using the given type and name.
+	 *
+	 * @param type The type of the duplicated thing.
+	 * @param name The name of the duplicated thing.
+	 *
+	 * @deprecated Use the for taking {@link Type} instead.
+	 */
 	@Deprecated
 	public DuplicateMappingException(String type, String name) {
 		this( "Duplicate " + type + " mapping " + name, type, name );
 	}
 
+	/**
+	 * Creates a DuplicateMappingException using the given customMessage, type and name.
+	 *
+	 * @param customMessage A custom exception message explaining the exception condition
+	 * @param type The type of the duplicated thing.
+	 * @param name The name of the duplicated thing.
+	 */
 	public DuplicateMappingException(String customMessage, Type type, String name) {
 		this( customMessage, type.name(), name );
 	}
 
+	/**
+	 * Creates a DuplicateMappingException using the given customMessage, type and name.
+	 *
+	 * @param customMessage A custom exception message explaining the exception condition
+	 * @param type The type of the duplicated thing.
+	 * @param name The name of the duplicated thing.
+	 *
+	 * @deprecated Use the for taking {@link Type} instead.
+	 */
 	@Deprecated
 	public DuplicateMappingException(String customMessage, String type, String name) {
 		super( customMessage );

hibernate-core/src/main/java/org/hibernate/EmptyInterceptor.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, 2013, 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,26 +20,29 @@
  * 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;
 
 import org.hibernate.type.Type;
 
 /**
- * An interceptor that does nothing. May be used as a base class
+ * An interceptor that does nothing.  May be used as a base class for application-defined custom interceptors.
- * for application-defined custom interceptors.
  * 
  * @author Gavin King
  */
 public class EmptyInterceptor implements Interceptor, Serializable {
-	
+	/**
+	 * The singleton reference.
+	 */
 	public static final Interceptor INSTANCE = new EmptyInterceptor();
 
-	protected EmptyInterceptor() {}
+	protected EmptyInterceptor() {
+	}
 
+	@Override
 	public void onDelete(
 			Object entity, 
 			Serializable id, 
@@ -47,6 +50,7 @@ public class EmptyInterceptor implements Interceptor, Serializable {
 			String[] propertyNames, 
 			Type[] types) {}
 
+	@Override
 	public boolean onFlushDirty(
 			Object entity, 
 			Serializable id, 
@@ -57,6 +61,7 @@ public class EmptyInterceptor implements Interceptor, Serializable {
 		return false;
 	}
 
+	@Override
 	public boolean onLoad(
 			Object entity, 
 			Serializable id, 
@@ -66,6 +71,7 @@ public class EmptyInterceptor implements Interceptor, Serializable {
 		return false;
 	}
 
+	@Override
 	public boolean onSave(
 			Object entity, 
 			Serializable id, 
@@ -75,18 +81,27 @@ public class EmptyInterceptor implements Interceptor, Serializable {
 		return false;
 	}
 
-	public void postFlush(Iterator entities) {}
+	@Override
-	public void preFlush(Iterator entities) {}
+	public void postFlush(Iterator entities) {
+	}
 
+	@Override
+	public void preFlush(Iterator entities) {
+	}
+
+	@Override
 	public Boolean isTransient(Object entity) {
 		return null;
 	}
 
+	@Override
 	public Object instantiate(String entityName, EntityMode entityMode, Serializable id) {
 		return null;
 	}
 
-	public int[] findDirty(Object entity,
+	@Override
+	public int[] findDirty(
+			Object entity,
 			Serializable id,
 			Object[] currentState,
 			Object[] previousState,
@@ -95,26 +110,43 @@ public class EmptyInterceptor implements Interceptor, Serializable {
 		return null;
 	}
 
+	@Override
 	public String getEntityName(Object object) {
 		return null;
 	}
 
+	@Override
 	public Object getEntity(String entityName, Serializable id) {
 		return null;
 	}
 
-	public void afterTransactionBegin(Transaction tx) {}
+	@Override
-	public void afterTransactionCompletion(Transaction tx) {}
+	public void afterTransactionBegin(Transaction tx) {
-	public void beforeTransactionCompletion(Transaction tx) {}
+	}
 
+	@Override
+	public void afterTransactionCompletion(Transaction tx) {
+	}
+
+	@Override
+	public void beforeTransactionCompletion(Transaction tx) {
+	}
+
+	@Override
 	public String onPrepareStatement(String sql) {
 		return sql;
 	}
 
-	public void onCollectionRemove(Object collection, Serializable key) throws CallbackException {}
+	@Override
+	public void onCollectionRemove(Object collection, Serializable key) throws CallbackException {
+	}
 
-	public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException {}
+	@Override
+	public void onCollectionRecreate(Object collection, Serializable key) throws CallbackException {
+	}
 
-	public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException {}
+	@Override
+	public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException {
+	}
 	
 }

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

@@ -29,12 +29,20 @@ package org.hibernate;
  * @author Steve Ebersole
  */
 public enum EntityMode {
+	/**
+	 * The {@code pojo} entity mode describes an entity model made up of entity classes (loosely) following
+	 * the java bean convention.
+	 */
 	POJO( "pojo" ),
+
+	/**
+	 * The {@code dynamic-map} entity mode describes an entity model defined using {@link java.util.Map} references.
+	 */
 	MAP( "dynamic-map" );
 
 	private final String name;
 
-	EntityMode(String name) {
+	private EntityMode(String name) {
 		this.name = name;
 	}
 

hibernate-core/src/main/java/org/hibernate/FetchMode.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, 2013, 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,7 +20,6 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
@@ -32,6 +31,7 @@ package org.hibernate;
  * For HQL queries, use the <tt>FETCH</tt> keyword instead.
  *
  * @see Criteria#setFetchMode(java.lang.String, FetchMode)
+ *
  * @author Gavin King
  */
 public enum FetchMode  {
@@ -52,18 +52,16 @@ public enum FetchMode  {
 
 	/**
 	 * Fetch lazily. Equivalent to <tt>outer-join="false"</tt>.
+	 *
 	 * @deprecated use <tt>FetchMode.SELECT</tt>
 	 */
+	@Deprecated
 	public static final FetchMode LAZY = SELECT;
 	/**
-	 * Fetch eagerly, using an outer join. Equivalent to
+	 * Fetch eagerly, using an outer join. Equivalent to <tt>outer-join="true"</tt>.
-	 * <tt>outer-join="true"</tt>.
+	 *
 	 * @deprecated use <tt>FetchMode.JOIN</tt>
 	 */
+	@Deprecated
 	public static final FetchMode EAGER = JOIN;
 }
-
-
-
-
-

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

@@ -35,13 +35,14 @@ package org.hibernate;
  * @author Gavin King
  */
 public enum FlushMode {
-		/**
+	/**
 	 * The {@link Session} is never flushed unless {@link Session#flush}
 	 * is explicitly called by the application. This mode is very
 	 * efficient for read only transactions.
 	 *
 	 * @deprecated use {@link #MANUAL} instead.
 	 */
+	@Deprecated
 	NEVER ( 0 ),
 
 	/**
@@ -76,24 +77,52 @@ public enum FlushMode {
 		this.level = level;
 	}
 
+	/**
+	 * Checks to see if {@code this} flush mode is less than the given flush mode.
+	 *
+	 * @param other THe flush mode value to be checked against {@code this}
+	 *
+	 * @return {@code true} indicates {@code other} is less than {@code this}; {@code false} otherwise
+	 */
 	public boolean lessThan(FlushMode other) {
-		return this.level<other.level;
+		return this.level < other.level;
 	}
 
+	/**
+	 * Checks to see if the given mode is the same as {@link #MANUAL}
+	 *
+	 * @param mode The mode to check
+	 *
+	 * @return true/false
+	 *
+	 * @deprecated Just use equality check against {@link #MANUAL}.  Legacy from before this was an enum
+	 */
+	@Deprecated
 	public static boolean isManualFlushMode(FlushMode mode) {
 		return MANUAL.level == mode.level;
 	}
 
-	public static FlushMode interpretExternalSetting(String setting) {
+	/**
-		if ( setting == null ) {
+	 * Interprets an external representation of the flush mode.  {@code null} is returned as {@code null}, otherwise
+	 * {@link FlushMode#valueOf(String)} is used with the upper-case version of the incoming value.  An unknown,
+	 * non-null value results in a MappingException being thrown.
+	 *
+	 * @param externalName The external representation
+	 *
+	 * @return The interpreted FlushMode value.
+	 *
+	 * @throws MappingException Indicates an unrecognized external representation
+	 */
+	public static FlushMode interpretExternalSetting(String externalName) {
+		if ( externalName == null ) {
 			return null;
 		}
 
 		try {
-			return FlushMode.valueOf( setting.toUpperCase() );
+			return FlushMode.valueOf( externalName.toUpperCase() );
 		}
 		catch ( IllegalArgumentException e ) {
-			throw new MappingException( "unknown FlushMode : " + setting );
+			throw new MappingException( "unknown FlushMode : " + externalName );
 		}
 	}
 }

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

@@ -70,8 +70,9 @@ public final class Hibernate {
 		if ( proxy == null ) {
 			return;
 		}
-		else if ( proxy instanceof HibernateProxy ) {
+
-			( ( HibernateProxy ) proxy ).getHibernateLazyInitializer().initialize();
+		if ( proxy instanceof HibernateProxy ) {
+			( (HibernateProxy) proxy ).getHibernateLazyInitializer().initialize();
 		}
 		else if ( proxy instanceof PersistentCollection ) {
 			( (PersistentCollection) proxy ).forceInitialization();
@@ -84,12 +85,13 @@ public final class Hibernate {
 	 * @param proxy a persistable object, proxy, persistent collection or <tt>null</tt>
 	 * @return true if the argument is already initialized, or is not a proxy or collection
 	 */
+	@SuppressWarnings("SimplifiableIfStatement")
 	public static boolean isInitialized(Object proxy) {
 		if ( proxy instanceof HibernateProxy ) {
-			return !( ( HibernateProxy ) proxy ).getHibernateLazyInitializer().isUninitialized();
+			return !( (HibernateProxy) proxy ).getHibernateLazyInitializer().isUninitialized();
 		}
 		else if ( proxy instanceof PersistentCollection ) {
-			return ( ( PersistentCollection ) proxy ).wasInitialized();
+			return ( (PersistentCollection) proxy ).wasInitialized();
 		}
 		else {
 			return true;
@@ -106,7 +108,7 @@ public final class Hibernate {
 	 */
 	public static Class getClass(Object proxy) {
 		if ( proxy instanceof HibernateProxy ) {
-			return ( ( HibernateProxy ) proxy ).getHibernateLazyInitializer()
+			return ( (HibernateProxy) proxy ).getHibernateLazyInitializer()
 					.getImplementation()
 					.getClass();
 		}
@@ -115,10 +117,24 @@ public final class Hibernate {
 		}
 	}
 
+	/**
+	 * Obtain a lob creator for the given session.
+	 *
+	 * @param session The session for which to obtain a lob creator
+	 *
+	 * @return The log creator reference
+	 */
 	public static LobCreator getLobCreator(Session session) {
 		return getLobCreator( (SessionImplementor) session );
 	}
 
+	/**
+	 * Obtain a lob creator for the given session.
+	 *
+	 * @param session The session for which to obtain a lob creator
+	 *
+	 * @return The log creator reference
+	 */
 	public static LobCreator getLobCreator(SessionImplementor session) {
 		return session.getFactory()
 				.getJdbcServices()
@@ -126,17 +142,19 @@ public final class Hibernate {
 	}
 
 	/**
-	 * Close an <tt>Iterator</tt> created by <tt>iterate()</tt> immediately,
+	 * Close an {@link Iterator} instances obtained from {@link org.hibernate.Query#iterate()} immediately
 	 * instead of waiting until the session is closed or disconnected.
 	 *
-	 * @param iterator an <tt>Iterator</tt> created by <tt>iterate()</tt>
+	 * @param iterator an Iterator created by iterate()
-	 * @throws HibernateException
+	 *
-	 * @see org.hibernate.Query#iterate
+	 * @throws HibernateException Indicates a problem closing the Hibernate iterator.
+	 * @throws IllegalArgumentException If the Iterator is not a "Hibernate Iterator".
+	 *
 	 * @see Query#iterate()
 	 */
 	public static void close(Iterator iterator) throws HibernateException {
 		if ( iterator instanceof HibernateIterator ) {
-			( ( HibernateIterator ) iterator ).close();
+			( (HibernateIterator) iterator ).close();
 		}
 		else {
 			throw new IllegalArgumentException( "not a Hibernate iterator" );
@@ -152,10 +170,9 @@ public final class Hibernate {
 	 * @return true if the named property of the object is not listed as uninitialized; false otherwise
 	 */
 	public static boolean isPropertyInitialized(Object proxy, String propertyName) {
-		
+		final Object entity;
-		Object entity;
 		if ( proxy instanceof HibernateProxy ) {
-			LazyInitializer li = ( ( HibernateProxy ) proxy ).getHibernateLazyInitializer();
+			final LazyInitializer li = ( (HibernateProxy) proxy ).getHibernateLazyInitializer();
 			if ( li.isUninitialized() ) {
 				return false;
 			}
@@ -168,13 +185,12 @@ public final class Hibernate {
 		}
 
 		if ( FieldInterceptionHelper.isInstrumented( entity ) ) {
-			FieldInterceptor interceptor = FieldInterceptionHelper.extractFieldInterceptor( entity );
+			final FieldInterceptor interceptor = FieldInterceptionHelper.extractFieldInterceptor( entity );
 			return interceptor == null || interceptor.isInitialized( propertyName );
 		}
 		else {
 			return true;
 		}
-		
 	}
 
 }

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

@@ -1,7 +1,7 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2007-2011, Red Hat Inc. or third-party contributors as
+ * Copyright (c) 2007,2011, 2013, 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.
@@ -23,9 +23,8 @@
  */
 package org.hibernate;
 
-
 /**
- * The base {@link Throwable} type for Hibernate.
+ * The base exception type for Hibernate exceptions.
  * <p/>
  * Note that all {@link java.sql.SQLException SQLExceptions} will be wrapped in some form of 
  * {@link JDBCException}.
@@ -35,16 +34,32 @@ package org.hibernate;
  * @author Gavin King
  */
 public class HibernateException extends RuntimeException {
+	/**
+	 * Constructs a HibernateException using the given exception message.
+	 *
+	 * @param message The message explaining the reason for the exception
+	 */
 	public HibernateException(String message) {
 		super( message );
 	}
 
-	public HibernateException(Throwable root) {
+	/**
-		super( root );
+	 * Constructs a HibernateException using the given message and underlying cause.
+	 *
+	 * @param cause The underlying cause.
+	 */
+	public HibernateException(Throwable cause) {
+		super( cause );
 	}
 
-	public HibernateException(String message, Throwable root) {
+	/**
-		super( message, root );
+	 * Constructs a HibernateException using the given message and underlying cause.
+	 *
+	 * @param message The message explaining the reason for the exception.
+	 * @param cause The underlying cause.
+	 */
+	public HibernateException(String message, Throwable cause) {
+		super( message, cause );
 	}
 }
 

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

@@ -26,7 +26,7 @@ package org.hibernate;
 import java.io.Serializable;
 
 /**
- * Loads an entity by its primary identifier
+ * Loads an entity by its primary identifier.
  * 
  * @author Eric Dalquist
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/InstantiationException.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, 2013, 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,49 +20,71 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
- * Thrown if Hibernate can't instantiate an entity or component
+ * Thrown if Hibernate can't instantiate a class at runtime.
- * class at runtime.
  *
  * @author Gavin King
  */
-
 public class InstantiationException extends HibernateException {
-
 	private final Class clazz;
 
-	public InstantiationException(String s, Class clazz, Throwable root) {
+	/**
-		super(s, root);
+	 * Constructs a InstantiationException.
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param clazz The Class we are attempting to instantiate
+	 * @param cause The underlying exception
+	 */
+	public InstantiationException(String message, Class clazz, Throwable cause) {
+		super( message, cause );
 		this.clazz = clazz;
 	}
 
-	public InstantiationException(String s, Class clazz) {
+	/**
-		super(s);
+	 * Constructs a InstantiationException.
-		this.clazz = clazz;
+	 *
-	}
+	 * @param message A message explaining the exception condition
-
+	 * @param clazz The Class we are attempting to instantiate
-	public InstantiationException(String s, Class clazz, Exception e) {
+	 */
-		super(s, e);
+	public InstantiationException(String message, Class clazz) {
+		this( message, clazz, null );
+	}
+
+	/**
+	 * Constructs a InstantiationException.
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param clazz The Class we are attempting to instantiate
+	 * @param cause The underlying exception
+	 */
+	public InstantiationException(String message, Class clazz, Exception cause) {
+		super( message, cause );
 		this.clazz = clazz;
 	}
 
+	/**
+	 * @deprecated Use {@link #getUninstantiatableClass} instead
+	 */
+	@Deprecated
 	public Class getPersistentClass() {
 		return clazz;
 	}
 
+	/**
+	 * Returns the Class we were attempting to instantiate.
+	 *
+	 * @return The class we are unable to instantiate
+	 */
+	public Class getUninstantiatableClass() {
+		return clazz;
+	}
+
+	@Override
 	public String getMessage() {
-		return super.getMessage() + clazz.getName();
+		return super.getMessage() + " : " + clazz.getName();
 	}
 
 }
-
-
-
-
-
-

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

@@ -30,18 +30,18 @@ import org.hibernate.type.Type;
 
 /**
  * Allows user code to inspect and/or change property values.
- * <br><br>
+ *
  * Inspection occurs before property values are written and after they are read
- * from the database.<br>
+ * from the database.
- * <br>
+ *
  * There might be a single instance of <tt>Interceptor</tt> for a <tt>SessionFactory</tt>, or a new instance
  * might be specified for each <tt>Session</tt>. Whichever approach is used, the interceptor must be
  * serializable if the <tt>Session</tt> is to be serializable. This means that <tt>SessionFactory</tt>-scoped
- * interceptors should implement <tt>readResolve()</tt>.<br>
+ * interceptors should implement <tt>readResolve()</tt>.
- * <br>
+ *
  * The <tt>Session</tt> may not be invoked from a callback (nor may a callback cause a collection or proxy to
- * be lazily initialized).<br>
+ * be lazily initialized).
- * <br>
+ *
  * Instead of implementing this interface directly, it is usually better to extend <tt>EmptyInterceptor</tt>
  * and override only the callback methods of interest.
  *
@@ -155,9 +155,9 @@ public interface Interceptor {
 	public void onCollectionUpdate(Object collection, Serializable key) throws CallbackException;
 
 	/**
-	 * Called before a flush
+	 * Called before a flush.
 	 *
-	 * @param entities The entities to be flushed
+	 * @param entities The entities to be flushed.
 	 *
 	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.
 	 */
@@ -215,6 +215,7 @@ public interface Interceptor {
 	 * @param entityName the name of the entity
 	 * @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.
@@ -222,8 +223,10 @@ public interface Interceptor {
 	public Object instantiate(String entityName, EntityMode entityMode, Serializable id) throws CallbackException;
 
 	/**
-	 * Get the entity name for a persistent or transient instance
+	 * 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.
@@ -231,9 +234,11 @@ public interface Interceptor {
 	public String getEntityName(Object object) throws CallbackException;
 
 	/**
-	 * Get a fully loaded entity instance that is cached externally
+	 * Get a fully loaded entity instance that is cached externally.
+	 *
 	 * @param entityName the name of the entity
 	 * @param id the instance identifier
+	 *
 	 * @return a fully initialized entity
 	 *
 	 * @throws CallbackException Thrown if the interceptor encounters any problems handling the callback.

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

@@ -28,7 +28,9 @@ import org.hibernate.internal.util.xml.XmlDocument;
 
 /**
  * Thrown when a mapping is found to be invalid.
- * Similar to MappingException, but this contains more info about the path and type of mapping (e.g. file, resource or url)
+ *
+ * Similar to MappingException, but this contains more info about the path and type of
+ * mapping (e.g. file, resource or url)
  * 
  * @author Max Rydahl Andersen
  * @author Steve Ebersole
@@ -37,44 +39,104 @@ public class InvalidMappingException extends MappingException {
 	private final String path;
 	private final String type;
 
+	/**
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param type The type of invalid mapping document
+	 * @param path The path (type specific) of the invalid mapping document
+	 * @param cause The underlying cause
+	 */
 	public InvalidMappingException(String customMessage, String type, String path, Throwable cause) {
-		super(customMessage, cause);
+		super( customMessage, cause );
-		this.type=type;
+		this.type = type;
-		this.path=path;
+		this.path = path;
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param type The type of invalid mapping document
+	 * @param path The path (type specific) of the invalid mapping document
+	 */
 	public InvalidMappingException(String customMessage, String type, String path) {
 		super(customMessage);
 		this.type=type;
 		this.path=path;
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param xmlDocument The document that was invalid
+	 * @param cause The underlying cause
+	 */
 	public InvalidMappingException(String customMessage, XmlDocument xmlDocument, Throwable cause) {
 		this( customMessage, xmlDocument.getOrigin().getType(), xmlDocument.getOrigin().getName(), cause );
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param xmlDocument The document that was invalid
+	 */
 	public InvalidMappingException(String customMessage, XmlDocument xmlDocument) {
 		this( customMessage, xmlDocument.getOrigin().getType(), xmlDocument.getOrigin().getName() );
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param origin The origin of the invalid mapping document
+	 */
 	public InvalidMappingException(String customMessage, Origin origin) {
 		this( customMessage, origin.getType().toString(), origin.getName() );
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information and a standard message.
+	 *
+	 * @param type The type of invalid mapping document
+	 * @param path The path (type specific) of the invalid mapping document
+	 */
 	public InvalidMappingException(String type, String path) {
 		this("Could not parse mapping document from " + type + (path==null?"":" " + path), type, path);
 	}
 
+	/**
+	 * Constructs an InvalidMappingException using the given information and a standard message.
+	 *
+	 * @param type The type of invalid mapping document
+	 * @param path The path (type specific) of the invalid mapping document
+	 * @param cause The underlying cause
+	 */
 	public InvalidMappingException(String type, String path, Throwable cause) {
 		this("Could not parse mapping document from " + type + (path==null?"":" " + path), type, path, cause);		
 	}
 
-	public InvalidMappingException(String message, org.hibernate.internal.util.xml.Origin origin, Exception cause) {
+	/**
-		this( message, origin.getType(), origin.getName(), cause );
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param origin The origin of the invalid mapping document
+	 * @param cause The underlying cause
+	 */
+	public InvalidMappingException(String customMessage, org.hibernate.internal.util.xml.Origin origin, Exception cause) {
+		this( customMessage, origin.getType(), origin.getName(), cause );
 	}
 
-	public InvalidMappingException(String message, org.hibernate.internal.util.xml.Origin origin) {
+	/**
-		this( message, origin, null );
+	 * Constructs an InvalidMappingException using the given information.
+	 *
+	 * @param customMessage The custom message explaining the exception condition
+	 * @param origin The origin of the invalid mapping document
+	 */
+	public InvalidMappingException(String customMessage, org.hibernate.internal.util.xml.Origin origin) {
+		this( customMessage, origin, null );
 	}
 
 	public String getType() {

hibernate-core/src/main/java/org/hibernate/JDBCException.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, 2013, 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,31 +20,35 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.sql.SQLException;
 
-
 /**
- * Wraps an <tt>SQLException</tt>. Indicates that an exception
+ * Wraps a {@link SQLException}.  Indicates that an exception occurred during a JDBC call.
- * occurred during a JDBC call.
+ *
+ * @author Gavin King
  *
  * @see java.sql.SQLException
- * @author Gavin King
  */
 public class JDBCException extends HibernateException {
+	private final SQLException sqlException;
+	private final String sql;
 
-	private SQLException sqle;
+	/**
-	private String sql;
+	 * Constructs a JDBCException using the given information
-
+	 *
-	public JDBCException(String string, SQLException root) {
+	 * @param message The message explaining the exception condition
-		super(string, root);
+	 * @param cause The underlying cause
-		sqle=root;
+	 */
+	public JDBCException(String message, SQLException cause) {
+		this( message, cause, null );
 	}
 
-	public JDBCException(String string, SQLException root, String sql) {
+	public JDBCException(String string, SQLException cause, String sql) {
-		this(string, root);
+		super( string, cause );
+		this.sqlException = cause;
 		this.sql = sql;
 	}
 
@@ -54,7 +58,7 @@ public class JDBCException extends HibernateException {
 	 * @return String
 	 */
 	public String getSQLState() {
-		return sqle.getSQLState();
+		return sqlException.getSQLState();
 	}
 
 	/**
@@ -63,7 +67,7 @@ public class JDBCException extends HibernateException {
 	 * @return int the error code
 	 */
 	public int getErrorCode() {
-		return sqle.getErrorCode();
+		return sqlException.getErrorCode();
 	}
 
 	/**
@@ -71,7 +75,7 @@ public class JDBCException extends HibernateException {
 	 * @return SQLException
 	 */
 	public SQLException getSQLException() {
-		return sqle;
+		return sqlException;
 	}
 	
 	/**

hibernate-core/src/main/java/org/hibernate/LazyInitializationException.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, 2013, 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,17 +20,17 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import org.jboss.logging.Logger;
 
 import org.hibernate.internal.CoreMessageLogger;
 
 /**
- * Indicates access to unfetched data outside of a session context.
+ * Indicates an attempt to access not-yet-fetched data outside of a session context.
- * For example, when an uninitialized proxy or collection is accessed
+ *
- * after the session was closed.
+ * For example, when an uninitialized proxy or collection is accessed after the session was closed.
  *
  * @see Hibernate#initialize(java.lang.Object)
  * @see Hibernate#isInitialized(java.lang.Object)
@@ -38,11 +38,19 @@ import org.hibernate.internal.CoreMessageLogger;
  */
 public class LazyInitializationException extends HibernateException {
 
-	private static final CoreMessageLogger LOG = Logger.getMessageLogger( CoreMessageLogger.class, LazyInitializationException.class.getName() );
+	private static final CoreMessageLogger LOG = Logger.getMessageLogger(
+			CoreMessageLogger.class,
+			LazyInitializationException.class.getName()
+	);
 
-	public LazyInitializationException(String msg) {
+	/**
-		super( msg );
+	 * Constructs a LazyInitializationException using the given message
-		LOG.trace( msg, this );
+	 *
+	 * @param message A message explaining the exception condition
+	 */
+	public LazyInitializationException(String message) {
+		super( message );
+		LOG.trace( message, this );
 	}
 
 }

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

@@ -30,7 +30,7 @@ import java.sql.Clob;
 import java.sql.NClob;
 
 /**
- * A {@link Session session's} helper for creating LOB data
+ * A {@link Session session's} helper for creating LOB data.
  *
  * @author Steve Ebersole
  */
@@ -56,7 +56,7 @@ public interface LobHelper {
 	public Blob createBlob(InputStream stream, long length);
 
 	/**
-	 * Create a new {@link java.sql.Clob} from content
+	 * Create a new {@link java.sql.Clob} from content.
 	 *
 	 * @param string The string data
 	 *

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

@@ -36,18 +36,17 @@ import java.util.Map;
  */
 public class LockOptions implements Serializable {
 	/**
-	 * NONE represents LockMode.NONE (timeout + scope do not apply)
+	 * Represents LockMode.NONE (timeout + scope do not apply).
 	 */
 	public static final LockOptions NONE = new LockOptions(LockMode.NONE);
 
 	/**
-	 * READ represents LockMode.READ (timeout + scope do not apply)
+	 * Represents LockMode.READ (timeout + scope do not apply).
 	 */
 	public static final LockOptions READ = new LockOptions(LockMode.READ);
 
 	/**
-	 * UPGRADE represents LockMode.UPGRADE (will wait forever for lock and
+	 * Represents LockMode.UPGRADE (will wait forever for lock and scope of false meaning only entity is locked).
-	 * scope of false meaning only entity is locked)
 	 */
 	@SuppressWarnings("deprecation")
 	public static final LockOptions UPGRADE = new LockOptions(LockMode.UPGRADE);
@@ -73,12 +72,19 @@ public class LockOptions implements Serializable {
 	private LockMode lockMode = LockMode.NONE;
 	private int timeout = WAIT_FOREVER;
 
-	//initialize lazily as LockOptions is frequently created without needing this
+	private Map<String,LockMode> aliasSpecificLockModes;
-	private Map<String,LockMode> aliasSpecificLockModes = null;
 
+	/**
+	 * Constructs a LockOptions with all default options
+	 */
 	public LockOptions() {
 	}
 
+	/**
+	 * Constructs a LockOptions with the given lock mode
+	 *
+	 * @param lockMode The lock mode to use
+	 */
 	public LockOptions( LockMode lockMode) {
 		this.lockMode = lockMode;
 	}
@@ -109,7 +115,6 @@ public class LockOptions implements Serializable {
 		return this;
 	}
 
-
 	/**
 	 * Specify the {@link LockMode} to be used for a specific query alias.
 	 *
@@ -186,7 +191,7 @@ public class LockOptions implements Serializable {
 	}
 
 	/**
-	 * Iterator for accessing Alias (key) and LockMode (value) as Map.Entry
+	 * Iterator for accessing Alias (key) and LockMode (value) as Map.Entry.
 	 *
 	 * @return Iterator for accessing the Map.Entry's
 	 */
@@ -265,7 +270,7 @@ public class LockOptions implements Serializable {
 	}
 
 	/**
-	 * Set the cope.
+	 * Set the scope.
 	 *
 	 * @param scope The new scope setting
 	 *
@@ -276,6 +281,11 @@ public class LockOptions implements Serializable {
 		return this;
 	}
 
+	/**
+	 * Make a copy.
+	 *
+	 * @return The copy
+	 */
 	public LockOptions makeCopy() {
 		final LockOptions copy = new LockOptions();
 		copy( this, copy );

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

@@ -1,7 +1,7 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2008-2011, Red Hat Inc. 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 Inc.
@@ -24,23 +24,38 @@
 package org.hibernate;
 
 /**
- * An exception that usually occurs at configuration time, rather
+ * An exception that occurs while reading mapping sources (xml/annotations),usually as a result of something
- * than runtime, as a result of something screwy in the O-R mappings.
+ * screwy in the O-R mappings.
  *
  * @author Gavin King
  */
 public class MappingException extends HibernateException {
-
+	/**
-	public MappingException(String msg, Throwable root) {
+	 * Constructs a MappingException using the given information
-		super( msg, root );
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param cause The underlying cause
+	 */
+	public MappingException(String message, Throwable cause) {
+		super( message, cause );
 	}
 
-	public MappingException(Throwable root) {
+	/**
-		super(root);
+	 * Constructs a MappingException using the given information
+	 *
+	 * @param cause The underlying cause
+	 */
+	public MappingException(Throwable cause) {
+		super(cause);
 	}
 
-	public MappingException(String s) {
+	/**
-		super(s);
+	 * Constructs a MappingException using the given information
+	 *
+	 * @param message A message explaining the exception condition
+	 */
+	public MappingException(String message) {
+		super(message);
 	}
 
 }

hibernate-core/src/main/java/org/hibernate/MappingNotFoundException.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, 2013, 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,37 +20,62 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
  * Thrown when a resource for a mapping could not be found.
  * 
  * @author Max Rydahl Andersen
  */
 public class MappingNotFoundException extends MappingException {
-
 	private final String path;
 	private final String type;
 
+	/**
+	 * Constructs a MappingNotFoundException using the given information.
+	 *
+	 * @param customMessage A message explaining the exception condition
+	 * @param type The type of mapping that could not be found
+	 * @param path The path (type specific) of the mapping that could not be found
+	 * @param cause The underlying cause
+	 */
 	public MappingNotFoundException(String customMessage, String type, String path, Throwable cause) {
 		super(customMessage, cause);
 		this.type=type;
 		this.path=path;
 	}
 
+	/**
+	 * Constructs a MappingNotFoundException using the given information.
+	 *
+	 * @param customMessage A message explaining the exception condition
+	 * @param type The type of mapping that could not be found
+	 * @param path The path (type specific) of the mapping that could not be found
+	 */
 	public MappingNotFoundException(String customMessage, String type, String path) {
 		super(customMessage);
 		this.type=type;
 		this.path=path;
 	}
 
+	/**
+	 * Constructs a MappingNotFoundException using the given information, using a standard message.
+	 *
+	 * @param type The type of mapping that could not be found
+	 * @param path The path (type specific) of the mapping that could not be found
+	 */
 	public MappingNotFoundException(String type, String path) {
 		this(type + ": " + path + " not found", type, path);
 	}
 
+	/**
+	 * Constructs a MappingNotFoundException using the given information, using a standard message.
+	 *
+	 * @param type The type of mapping that could not be found
+	 * @param path The path (type specific) of the mapping that could not be found
+	 * @param cause The underlying cause
+	 */
 	public MappingNotFoundException(String type, String path, Throwable cause) {
 		this(type + ": " + path + " not found", type, path, cause);
 	}

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

@@ -49,7 +49,7 @@ public enum MultiTenancyStrategy {
 	 */
 	DATABASE,
 	/**
-	 * No multi-tenancy
+	 * No multi-tenancy.
 	 */
 	NONE;
 
@@ -58,10 +58,24 @@ public enum MultiTenancyStrategy {
 			MultiTenancyStrategy.class.getName()
 	);
 
+	/**
+	 * Does this strategy indicate a requirement for the specialized
+	 * {@link org.hibernate.engine.jdbc.connections.spi.MultiTenantConnectionProvider}, rather than the
+	 * traditional {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider}
+	 *
+	 * @return {@code true} indicates a MultiTenantConnectionProvider is required; {@code false} indicates it is not.
+	 */
 	public boolean requiresMultiTenantConnectionProvider() {
 		return this == DATABASE || this == SCHEMA;
 	}
 
+	/**
+	 * Extract the MultiTenancyStrategy from the setting map.
+	 *
+	 * @param properties The map of settings.
+	 *
+	 * @return The selected strategy.  {@link #NONE} is always the default.
+	 */
 	public static MultiTenancyStrategy determineMultiTenancyStrategy(Map properties) {
 		final Object strategy = properties.get( Environment.MULTI_TENANT );
 		if ( strategy == null ) {

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

@@ -24,7 +24,7 @@
 package org.hibernate;
 
 /**
- * Loads an entity by its natural identifier
+ * Loads an entity by its natural identifier.
  * 
  * @author Eric Dalquist
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/NonUniqueObjectException.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, 2013, 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,19 +20,17 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 
 import org.hibernate.pretty.MessageHelper;
 
 /**
- * This exception is thrown when an operation would
+ * This exception is thrown when an operation would break session-scoped identity. This occurs if the
- * break session-scoped identity. This occurs if the
+ * user tries to associate two different instances of the same Java class with a particular identifier,
- * user tries to associate two different instances of
+ * in the scope of a single Session.
- * the same Java class with a particular identifier,
- * in the scope of a single <tt>Session</tt>.
  *
  * @author Gavin King
  */
@@ -40,27 +38,43 @@ public class NonUniqueObjectException extends HibernateException {
 	private final Serializable identifier;
 	private final String entityName;
 
-	public NonUniqueObjectException(String message, Serializable id, String clazz) {
+	/**
-		super(message);
+	 * Constructs a NonUniqueObjectException using the given information.
-		this.entityName = clazz;
+	 *
-		this.identifier = id;
+	 * @param message A message explaining the exception condition
+	 * @param entityId The identifier of the entity
+	 * @param entityName The name of the entity
+	 */
+	public NonUniqueObjectException(String message, Serializable entityId, String entityName) {
+		super( message );
+		this.entityName = entityName;
+		this.identifier = entityId;
 	}
 
-	public NonUniqueObjectException(Serializable id, String clazz) {
+	/**
-		this("a different object with the same identifier value was already associated with the session", id, clazz);
+	 * Constructs a NonUniqueObjectException using the given information, using a standard message
-	}
+	 *
-
+	 * @param entityId The identifier of the entity
-	public Serializable getIdentifier() {
+	 * @param entityName The name of the entity
-		return identifier;
+	 */
-	}
+	public NonUniqueObjectException(Serializable entityId, String entityName) {
-
+		this(
-	public String getMessage() {
+				"A different object with the same identifier value was already associated with the session",
-		return super.getMessage() + ": " +
+				entityId,
-			MessageHelper.infoString(entityName, identifier);
+				entityName
+		);
 	}
 
 	public String getEntityName() {
 		return entityName;
 	}
 
+	public Serializable getIdentifier() {
+		return identifier;
+	}
+
+	@Override
+	public String getMessage() {
+		return super.getMessage() + " : " + MessageHelper.infoString( entityName, identifier );
+	}
 }

hibernate-core/src/main/java/org/hibernate/NonUniqueResultException.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, 2013, 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,20 +20,22 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
  * Thrown when the application calls <tt>Query.uniqueResult()</tt> and
- * the query returned more than one result. Unlike all other Hibernate
+ * the query returned more than one result.  Unlike all other Hibernate
  * exceptions, this one is recoverable!
  *
  * @author Gavin King
  */
 public class NonUniqueResultException extends HibernateException {
-
+	/**
+	 * Constructs a NonUniqueResultException
+	 *
+	 * @param resultCount The number of actual results.
+	 */
 	public NonUniqueResultException(int resultCount) {
 		super( "query did not return a unique result: " + resultCount );
 	}

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

@@ -1,3 +1,26 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * Copyright (c) 2013, 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;
 
 /**
@@ -21,21 +44,37 @@ public enum NullPrecedence {
 	 */
 	LAST;
 
-	public static NullPrecedence parse(String type) {
+	/**
-		if ( "none".equalsIgnoreCase( type ) ) {
+	 * Interprets a string representation of a NullPrecedence, returning {@code null} by default.  For
+	 * alternative default handling, see {@link #parse(String, NullPrecedence)}
+	 *
+	 * @param name The String representation to interpret
+	 *
+	 * @return The recognized NullPrecedence, or {@code null}
+	 */
+	public static NullPrecedence parse(String name) {
+		if ( "none".equalsIgnoreCase( name ) ) {
 			return NullPrecedence.NONE;
 		}
-		else if ( "first".equalsIgnoreCase( type ) ) {
+		else if ( "first".equalsIgnoreCase( name ) ) {
 			return NullPrecedence.FIRST;
 		}
-		else if ( "last".equalsIgnoreCase( type ) ) {
+		else if ( "last".equalsIgnoreCase( name ) ) {
 			return NullPrecedence.LAST;
 		}
 		return null;
 	}
 
-	public static NullPrecedence parse(String type, NullPrecedence defaultValue) {
+	/**
-		final NullPrecedence value = parse( type );
+	 * Interprets a string representation of a NullPrecedence, returning the specified default if not recognized.
+	 *
+	 * @param name The String representation to interpret
+	 * @param defaultValue The default value to use
+	 *
+	 * @return The recognized NullPrecedence, or {@code defaultValue}.
+	 */
+	public static NullPrecedence parse(String name, NullPrecedence defaultValue) {
+		final NullPrecedence value = parse( name );
 		return value != null ? value : defaultValue;
 	}
 }

hibernate-core/src/main/java/org/hibernate/ObjectDeletedException.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, 2013, 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,21 +20,26 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 
 /**
- * Thrown when the user tries to do something illegal with a deleted
+ * Thrown when the user tries to do something illegal with a deleted object.
- * object.
  *
  * @author Gavin King
  */
 public class ObjectDeletedException extends UnresolvableObjectException {
-
+	/**
-	public ObjectDeletedException(String message, Serializable identifier, String clazz) {
+	 * Constructs an ObjectDeletedException using the given information
-		super(message, identifier, clazz);
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param identifier The identifier of the entity
+	 * @param entityName The name of the entity
+	 */
+	public ObjectDeletedException(String message, Serializable identifier, String entityName) {
+		super( message, identifier, entityName );
 	}
 
 }

hibernate-core/src/main/java/org/hibernate/ObjectNotFoundException.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, 2013, 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;
 
 /**
@@ -39,8 +39,13 @@ import java.io.Serializable;
  * @author Gavin King
  */
 public class ObjectNotFoundException extends UnresolvableObjectException {
-
+	/**
-	public ObjectNotFoundException(Serializable identifier, String clazz) {
+	 * Constructs a ObjectNotFoundException using the given information.
-		super(identifier, clazz);
+	 *
+	 * @param identifier The identifier of the entity
+	 * @param entityName The name of the entity
+	 */
+	public ObjectNotFoundException(Serializable identifier, String entityName) {
+		super(identifier, entityName);
 	}
 }

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

@@ -1,7 +1,7 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2009-2011, Red Hat Inc. or third-party contributors as
+ * Copyright (c) 2009, 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 Inc.
@@ -32,7 +32,14 @@ import org.hibernate.dialect.lock.OptimisticEntityLockException;
  *
  * @deprecated Use {@link org.hibernate.dialect.lock.OptimisticEntityLockException} instead
  */
+@Deprecated
 public class OptimisticLockException extends OptimisticEntityLockException {
+	/**
+	 * Constructs a OptimisticLockException using the specified information
+	 *
+	 * @param entity The entity instance that could not be locked
+	 * @param message A message explaining the exception condition
+	 */
 	public OptimisticLockException(Object entity, String message) {
 		super( entity, message );
 	}

hibernate-core/src/main/java/org/hibernate/PersistentObjectException.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, 2013, 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,11 +20,9 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
  * Thrown when the user passes a persistent instance to a <tt>Session</tt>
  * method that expects a transient instance.
@@ -32,8 +30,12 @@ package org.hibernate;
  * @author Gavin King
  */
 public class PersistentObjectException extends HibernateException {
-	
+	/**
-	public PersistentObjectException(String s) {
+	 * Constructs a PersistentObjectException using the given message.
-		super(s);
+	 *
+	 * @param message A message explaining the exception condition
+	 */
+	public PersistentObjectException(String message) {
+		super( message );
 	}
 }

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

@@ -31,7 +31,14 @@ import java.sql.SQLException;
  * @author Scott Marlow
  */
 public class PessimisticLockException extends JDBCException {
-	public PessimisticLockException(String s, SQLException se, String sql) {
+	/**
-		super( s, se, sql );
+	 * Constructs a PessimisticLockException using the specified information
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param sqlException The underlying SQL exception
+	 * @param sql The sql that led to the exception (may be null, though usually should not be)
+	 */
+	public PessimisticLockException(String message, SQLException sqlException, String sql) {
+		super( message, sqlException, sql );
 	}
 }

hibernate-core/src/main/java/org/hibernate/PropertyAccessException.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, 2013, 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,7 +20,6 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
@@ -39,13 +38,26 @@ import org.hibernate.internal.util.StringHelper;
  * @author Gavin King
  */
 public class PropertyAccessException extends HibernateException {
-
 	private final Class persistentClass;
 	private final String propertyName;
 	private final boolean wasSetter;
 
-	public PropertyAccessException(Throwable root, String s, boolean wasSetter, Class persistentClass, String propertyName) {
+	/**
-		super(s, root);
+	 * Constructs a PropertyAccessException using the specified information.
+	 *
+	 * @param cause The underlying cause
+	 * @param message A message explaining the exception condition
+	 * @param wasSetter Was the attempting to access the setter the cause of the exception?
+	 * @param persistentClass The class which is supposed to contain the property in question
+	 * @param propertyName The name of the property.
+	 */
+	public PropertyAccessException(
+			Throwable cause,
+			String message,
+			boolean wasSetter,
+			Class persistentClass,
+			String propertyName) {
+		super(message, cause);
 		this.persistentClass = persistentClass;
 		this.wasSetter = wasSetter;
 		this.propertyName = propertyName;

hibernate-core/src/main/java/org/hibernate/PropertyNotFoundException.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, 2013, 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,11 +20,9 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
  * Indicates that an expected getter or setter method could not be
  * found on a class.
@@ -32,9 +30,12 @@ package org.hibernate;
  * @author Gavin King
  */
 public class PropertyNotFoundException extends MappingException {
-
+	/**
-	public PropertyNotFoundException(String s) {
+	 * Constructs a PropertyNotFoundException given the specified message.
-		super(s);
+	 *
+	 * @param message A message explaining the exception condition
+	 */
+	public PropertyNotFoundException(String message) {
+		super(message);
 	}
-
 }

hibernate-core/src/main/java/org/hibernate/PropertyValueException.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, 2013, 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,7 +20,6 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
@@ -36,12 +35,18 @@ import org.hibernate.internal.util.StringHelper;
  * @author Gavin King
  */
 public class PropertyValueException extends HibernateException {
-
 	private final String entityName;
 	private final String propertyName;
 
-	public PropertyValueException(String s, String entityName, String propertyName) {
+	/**
-		super(s);
+	 * Constructs a PropertyValueException using the specified information.
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param entityName The name of the entity, containing the property
+	 * @param propertyName The name of the property being accessed.
+	 */
+	public PropertyValueException(String message, String entityName, String propertyName) {
+		super(message);
 		this.entityName = entityName;
 		this.propertyName = propertyName;
 	}
@@ -56,25 +61,6 @@ public class PropertyValueException extends HibernateException {
 
 	@Override
     public String getMessage() {
-		return super.getMessage() + ": " +
+		return super.getMessage() + " : " + StringHelper.qualify( entityName, propertyName );
-			StringHelper.qualify(entityName, propertyName);
-	}
-
-	/**
-	 * Return a well formed property path.
-	 * Basicaly, it will return parent.child
-	 *
-	 * @param parent parent in path
-	 * @param child child in path
-	 * @return parent-child path
-	 */
-	public static String buildPropertyPath(String parent, String child) {
-		return new StringBuilder(parent).append('.').append(child).toString();
 	}
 }
-
-
-
-
-
-

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

@@ -99,6 +99,8 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @param maxResults the maximum number of rows
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getMaxResults()
 	 */
 	public Query setMaxResults(int maxResults);
@@ -117,6 +119,8 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @param firstResult a row number, numbered from <tt>0</tt>
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getFirstResult()
 	 */
 	public Query setFirstResult(int firstResult);
@@ -159,6 +163,8 @@ public interface Query extends BasicQueryContract {
 	 * </ol>
 	 * For alias-specific locking, use {@link #setLockMode(String, LockMode)}.
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getLockOptions()
 	 */
 	public Query setLockOptions(LockOptions lockOptions);
@@ -175,6 +181,8 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @param alias a query alias, or <tt>this</tt> for a collection filter
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getLockOptions()
 	 */
 	public Query setLockMode(String alias, LockMode lockMode);
@@ -194,21 +202,25 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @param comment The human-readable comment
 	 *
+	 * @return {@code this}, for method chaining
+	 *
 	 * @see #getComment()
 	 */
 	public Query setComment(String comment);
 
 	/**
 	 * Return the HQL select clause aliases (if any)
+	 *
 	 * @return an array of aliases as strings
 	 */
-	public String[] getReturnAliases() throws HibernateException;
+	public String[] getReturnAliases();
 
 	/**
 	 * Return the names of all named parameters of the query.
+	 *
 	 * @return the parameter names, in no particular order
 	 */
-	public String[] getNamedParameters() throws HibernateException;
+	public String[] getNamedParameters();
 
 	/**
 	 * Return the query results as an <tt>Iterator</tt>. If the query
@@ -219,9 +231,8 @@ public interface Query extends BasicQueryContract {
 	 * SQL query returns identifiers only.<br>
 	 *
 	 * @return the result iterator
-	 * @throws HibernateException
 	 */
-	public Iterator iterate() throws HibernateException;
+	public Iterator iterate();
 
 	/**
 	 * Return the query results as <tt>ScrollableResults</tt>. The
@@ -229,10 +240,10 @@ public interface Query extends BasicQueryContract {
 	 * support for scrollable <tt>ResultSet</tt>s.<br>
 	 *
 	 * @see ScrollableResults
+	 *
 	 * @return the result iterator
-	 * @throws HibernateException
 	 */
-	public ScrollableResults scroll() throws HibernateException;
+	public ScrollableResults scroll();
 
 	/**
 	 * Return the query results as <tt>ScrollableResults</tt>. The
@@ -241,10 +252,10 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @see ScrollableResults
 	 * @see ScrollMode
+	 *
 	 * @return the result iterator
-	 * @throws HibernateException
 	 */
-	public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException;
+	public ScrollableResults scroll(ScrollMode scrollMode);
 
 	/**
 	 * Return the query results as a <tt>List</tt>. If the query contains
@@ -252,18 +263,18 @@ public interface Query extends BasicQueryContract {
 	 * of <tt>Object[]</tt>.
 	 *
 	 * @return the result list
-	 * @throws HibernateException
 	 */
-	public List list() throws HibernateException;
+	public List list();
 
 	/**
 	 * Convenience method to return a single instance that matches
 	 * the query, or null if the query returns no results.
 	 *
 	 * @return the single result or <tt>null</tt>
+	 *
 	 * @throws NonUniqueResultException if there is more than one matching result
 	 */
-	public Object uniqueResult() throws HibernateException;
+	public Object uniqueResult();
 
 	/**
 	 * Execute the update or delete statement.
@@ -272,24 +283,29 @@ public interface Query extends BasicQueryContract {
 	 * method.
 	 *
 	 * @return The number of entities updated or deleted.
-	 * @throws HibernateException
 	 */
-	public int executeUpdate() throws HibernateException;
+	public int executeUpdate();
 
 	/**
 	 * Bind a value to a JDBC-style query parameter.
+	 *
 	 * @param position the position of the parameter in the query
 	 * string, numbered from <tt>0</tt>.
 	 * @param val the possibly-null parameter value
 	 * @param type the Hibernate type
+	 *
+	 * @return {@code this}, for method chaining
 	 */
 	public Query setParameter(int position, Object val, Type type);
 
 	/**
 	 * Bind a value to a named query parameter.
+	 *
 	 * @param name the name of the parameter
 	 * @param val the possibly-null parameter value
 	 * @param type the Hibernate type
+	 *
+	 * @return {@code this}, for method chaining
 	 */
 	public Query setParameter(String name, Object val, Type type);
 
@@ -297,79 +313,110 @@ public interface Query extends BasicQueryContract {
 	 * Bind a value to a JDBC-style query parameter. The Hibernate type of the parameter is
 	 * first detected via the usage/position in the query and if not sufficient secondly 
 	 * guessed from the class of the given object.
+	 *
 	 * @param position the position of the parameter in the query
 	 * string, numbered from <tt>0</tt>.
 	 * @param val the non-null parameter value
-	 * @throws org.hibernate.HibernateException if no type could be determined
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameter(int position, Object val) throws HibernateException;
+	public Query setParameter(int position, Object val);
 
 	/**
 	 * Bind a value to a named query parameter. The Hibernate type of the parameter is
 	 * first detected via the usage/position in the query and if not sufficient secondly 
 	 * guessed from the class of the given object.
+	 *
 	 * @param name the name of the parameter
 	 * @param val the non-null parameter value
-	 * @throws org.hibernate.HibernateException if no type could be determined
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameter(String name, Object val) throws HibernateException;
+	public Query setParameter(String name, Object val);
 	
 	/**
-	 * Bind values and types to positional parameters.
+	 * Bind values and types to positional parameters.  Allows binding more than one at a time; no real performance
+	 * impact.
+	 *
+	 * The number of elements in each array should match.  That is, element number-0 in types array corresponds to
+	 * element-0 in the values array, etc,
+	 *
+	 * @param types The types
+	 * @param values The values
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameters(Object[] values, Type[] types) throws HibernateException;
+	public Query setParameters(Object[] values, Type[] types);
 
 	/**
 	 * Bind multiple values to a named query parameter. This is useful for binding
 	 * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
+	 *
 	 * @param name the name of the parameter
-	 * @param vals a collection of values to list
+	 * @param values a collection of values to list
 	 * @param type the Hibernate type of the values
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameterList(String name, Collection vals, Type type) throws HibernateException;
+	public Query setParameterList(String name, Collection values, Type type);
 
 	/**
 	 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
 	 * first detected via the usage/position in the query and if not sufficient secondly 
 	 * guessed from the class of the first object in the collection. This is useful for binding a list of values
 	 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
+	 *
 	 * @param name the name of the parameter
-	 * @param vals a collection of values to list
+	 * @param values a collection of values to list
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameterList(String name, Collection vals) throws HibernateException;
+	public Query setParameterList(String name, Collection values);
 
 	/**
 	 * Bind multiple values to a named query parameter. This is useful for binding
 	 * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
+	 *
 	 * @param name the name of the parameter
-	 * @param vals a collection of values to list
+	 * @param values a collection of values to list
 	 * @param type the Hibernate type of the values
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameterList(String name, Object[] vals, Type type) throws HibernateException;
+	public Query setParameterList(String name, Object[] values, Type type);
 
 	/**
 	 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
 	 * first detected via the usage/position in the query and if not sufficient secondly 
 	 * guessed from the class of the first object in the array. This is useful for binding a list of values
 	 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
+	 *
 	 * @param name the name of the parameter
-	 * @param vals a collection of values to list
+	 * @param values a collection of values to list
+	 *
+	 * @return {@code this}, for method chaining
 	 */
-	public Query setParameterList(String name, Object[] vals) throws HibernateException;
+	public Query setParameterList(String name, Object[] values);
 
 	/**
 	 * Bind the property values of the given bean to named parameters of the query,
 	 * matching property names with parameter names and mapping property types to
-	 * Hibernate types using hueristics.
+	 * Hibernate types using heuristics.
+	 *
 	 * @param bean any JavaBean or POJO
+	 *
+	 * @return {@code this}, for method chaining
 	 */	
 	public Query setProperties(Object bean) throws HibernateException;
 	
 	/**
 	 * Bind the values of the given Map for each named parameters of the query,
 	 * matching key names with parameter names and mapping value types to
-	 * Hibernate types using hueristics.
+	 * Hibernate types using heuristics.
+	 *
 	 * @param bean a java.util.Map
+	 *
+	 * @return {@code this}, for method chaining
 	 */
 	public Query setProperties(Map bean) throws HibernateException;
 
@@ -412,28 +459,34 @@ public interface Query extends BasicQueryContract {
 	public Query setBigDecimal(String name, BigDecimal number);
 	public Query setBigInteger(String name, BigInteger number);
 
-        /**
+	/**
-         * Bind the date (time is truncated) of a given Date object to a named query parameter.
+	 * Bind the date (time is truncated) of a given Date object to a named query parameter.
-         * 
+	 *
 	 * @param name The name of the parameter
 	 * @param date The date object
-         */
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setDate(String name, Date date);
 
-        /**
+	/**
-         * Bind the time (date is truncated) of a given Date object to a named query parameter.
+	 * Bind the time (date is truncated) of a given Date object to a named query parameter.
-         * 
+	 *
 	 * @param name The name of the parameter
 	 * @param date The date object
-         */
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setTime(String name, Date date);
 
-        /**
+	/**
-         * Bind the date and the time of a given Date object to a named query parameter.
+	 * Bind the date and the time of a given Date object to a named query parameter.
-         *
+	 *
 	 * @param name The name of the parameter
 	 * @param date The date object
-         */
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setTimestamp(String name, Date date);
 
 	public Query setCalendar(String name, Calendar calendar);
@@ -441,16 +494,22 @@ public interface Query extends BasicQueryContract {
 
 	/**
 	 * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
+	 *
 	 * @param position the position of the parameter in the query
 	 * string, numbered from <tt>0</tt>.
 	 * @param val a non-null instance of a persistent class
+	 *
+	 * @return {@code this}, for method chaining
 	 */
 	public Query setEntity(int position, Object val); // use setParameter for null values
 
 	/**
 	 * Bind an instance of a mapped persistent class to a named query parameter.
+	 *
 	 * @param name the name of the parameter
 	 * @param val a non-null instance of a persistent class
+	 *
+	 * @return {@code this}, for method chaining
 	 */
 	public Query setEntity(String name, Object val); // use setParameter for null values
 	

hibernate-core/src/main/java/org/hibernate/QueryException.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, 2013, 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,45 +20,90 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
+import org.jboss.logging.Logger;
 
 /**
- * A problem occurred translating a Hibernate query to SQL
+ * A problem occurred translating a Hibernate query to SQL due to invalid query syntax, etc.
- * due to invalid query syntax, etc.
  */
 public class QueryException extends HibernateException {
+	private static final Logger log = Logger.getLogger( QueryException.class );
 
 	private String queryString;
 
+	/**
+	 * Constructs a QueryException using the specified exception message
+	 *
+	 * @param message A message explaining the exception condition
+	 */
 	public QueryException(String message) {
 		super(message);
 	}
-	public QueryException(String message, Throwable e) {
+
-		super(message, e);
+	/**
+	 * Constructs a QueryException using the specified exception message and cause
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param cause The underlying cause
+	 */
+	public QueryException(String message, Throwable cause) {
+		super(message, cause);
 	}
 
+	/**
+	 * Constructs a QueryException using the specified exception message and query-string
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param queryString The query being evaluated when the exception occurred
+	 */
 	public QueryException(String message, String queryString) {
 		super(message);
 		this.queryString = queryString;
 	}
 
-	public QueryException(Exception e) {
+	/**
-		super(e);
+	 * Constructs a QueryException using the specified cause
+	 *
+	 * @param cause The underlying cause
+	 */
+	public QueryException(Exception cause) {
+		super(cause);
 	}
+
+	/**
+	 * Retrieve the query being evaluated when the exception occurred.  May be null, but generally should not.
+	 *
+	 * @return The query string
+	 */
 	public String getQueryString() {
 		return queryString;
 	}
 
+	/**
+	 * Set the query string.  EVen an option, since often the part of the code generating the exception does not
+	 * have access to the query overall.
+	 *
+	 * @param queryString The query string.
+	 */
 	public void setQueryString(String queryString) {
+		if ( this.queryString != null ) {
+			log.debugf(
+					"queryString overriding non-null previous value [%s] : %s",
+					this.queryString,
+					queryString
+			);
+		}
 		this.queryString = queryString;
 	}
 
+	@Override
 	public String getMessage() {
 		String msg = super.getMessage();
-		if ( queryString!=null ) msg += " [" + queryString + ']';
+		if ( queryString!=null ) {
+			msg += " [" + queryString + ']';
+		}
 		return msg;
 	}
 

hibernate-core/src/main/java/org/hibernate/cfg/Ejb3JoinColumn.java

@@ -556,7 +556,7 @@ public class Ejb3JoinColumn extends Ejb3Column {
 				);
 			}
 			catch (MappingException e) {
-				throw new RecoverableException(e);
+				throw new RecoverableException( e.getMessage(), e );
 			}
 		}
 		Table matchingTable = columnOwner instanceof PersistentClass ?

hibernate-core/src/main/java/org/hibernate/cfg/RecoverableException.java

@@ -22,25 +22,35 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.cfg;
+
 import org.hibernate.AnnotationException;
 
 /**
- * Should neven be exposed to the client
+ * An exception that indicates a condition where the hope is that subsequent processing will be able to
- * An exception that wrap an underlying exception whith the hope
+ * recover from it.
- * subsequent processing will recover from it.
+ *
+ * @deprecated Was only ever referenced in a single place, in an extremely dubious way.
  *
  * @author Emmanuel Bernard
  */
+@Deprecated
 public class RecoverableException extends AnnotationException {
-	public RecoverableException(String msg, Throwable root) {
+	/**
-		super( msg, root );
+	 * Constructs a RecoverableException using the given message and underlying cause.
+	 *
+	 * @param msg The message explaining the condition that caused the exception
+	 * @param cause The underlying exception
+	 */
+	public RecoverableException(String msg, Throwable cause) {
+		super( msg, cause );
 	}
 
-	public RecoverableException(Throwable root) {
+	/**
-		super( root );
+	 * Constructs a RecoverableException using the given message and underlying cause.
-	}
+	 *
-
+	 * @param msg
-	public RecoverableException(String s) {
+	 */
-		super( s );
+	public RecoverableException(String msg) {
+		super( msg );
 	}
 }

hibernate-core/src/main/java/org/hibernate/internal/AbstractQueryImpl.java

@@ -887,8 +887,8 @@ public abstract class AbstractQueryImpl implements Query {
 		return setParameterList( name, Arrays.asList(vals), type );
 	}
 
-	public Query setParameterList(String name, Object[] vals) throws HibernateException {
+	public Query setParameterList(String name, Object[] values) throws HibernateException {
-		return setParameterList( name, Arrays.asList(vals) );
+		return setParameterList( name, Arrays.asList( values ) );
 	}
 
 	public Query setProperties(Map map) throws HibernateException {

shared/config/checkstyle/checkstyle.xml

@@ -25,6 +25,14 @@
 <!DOCTYPE module PUBLIC "-//Puppy Crawl//DTD Check Configuration 1.1//EN" "http://www.puppycrawl.com/dtds/configuration_1_2.dtd">
 <module name="Checker">
 
+    <!--
+        Note that checkstyle is used to validate contributed code and generally used to fail builds if
+        the checks fail.  So as much as I'd like to have, for example, the TodoCommentCheck enabled it
+        is just not practical given how we use the plugin.
+
+        The commented-out checks are ones I would ultimately like to (re)enable.
+    -->
+
     <module name="TreeWalker">
 
         <!-- Annotation checks : http://checkstyle.sourceforge.net/config_annotation.html -->
@@ -88,9 +96,6 @@
         <module name="BooleanExpressionComplexity" />
 
         <!-- Misc checks : http://checkstyle.sourceforge.net/config_misc.html-->
-        <module name="TodoComment">
-            <property name="format" value="TODO|todo" />
-        </module>
         <module name="UpperEll" />
         <module name="ArrayTypeStyle" />
 <!--