HHH-8159 - Apply fixups indicated by analysis tools

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

@@ -89,7 +89,7 @@ public enum FlushMode {
 	}
 
 	/**
-	 * Checks to see if the given mode is the same as {@link #MANUAL}
+	 * Checks to see if the given mode is the same as {@link #MANUAL}.
 	 *
 	 * @param mode The mode to check
 	 *

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

@@ -66,7 +66,11 @@ public class InstantiationException extends HibernateException {
 	}
 
 	/**
+	 * Returns the Class we were attempting to instantiate.
+	 *
 	 * @deprecated Use {@link #getUninstantiatableClass} instead
+	 *
+	 * @return The class we are unable to instantiate
 	 */
 	@Deprecated
 	public Class getPersistentClass() {

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

@@ -37,7 +37,7 @@ public class JDBCException extends HibernateException {
 	private final String sql;
 
 	/**
-	 * Constructs a JDBCException using the given information
+	 * Constructs a JDBCException using the given information.
 	 *
 	 * @param message The message explaining the exception condition
 	 * @param cause The underlying cause
@@ -46,41 +46,54 @@ public class JDBCException extends HibernateException {
 		this( message, cause, null );
 	}
 
-	public JDBCException(String string, SQLException cause, String sql) {
+	/**
-		super( string, cause );
+	 * Constructs a JDBCException using the given information.
+	 *
+	 * @param message The message explaining the exception condition
+	 * @param cause The underlying cause
+	 * @param sql The sql being executed when the exception occurred
+	 */
+	public JDBCException(String message, SQLException cause, String sql) {
+		super( message, cause );
 		this.sqlException = cause;
 		this.sql = sql;
 	}
 
 	/**
-	 * Get the SQLState of the underlying <tt>SQLException</tt>.
+	 * Get the X/Open or ANSI SQL SQLState error code from the underlying {@link SQLException}.
-	 * @see java.sql.SQLException
+	 *
-	 * @return String
+	 * @return The X/Open or ANSI SQL SQLState error code; may return null.
+	 *
+	 * @see java.sql.SQLException#getSQLState()
 	 */
 	public String getSQLState() {
 		return sqlException.getSQLState();
 	}
 
 	/**
-	 * Get the <tt>errorCode</tt> of the underlying <tt>SQLException</tt>.
+	 * Get the vendor specific error code from the underlying {@link SQLException}.
-	 * @see java.sql.SQLException
+	 *
-	 * @return int the error code
+	 * @return The vendor specific error code
+	 *
+	 * @see java.sql.SQLException#getErrorCode()
 	 */
 	public int getErrorCode() {
 		return sqlException.getErrorCode();
 	}
 
 	/**
-	 * Get the underlying <tt>SQLException</tt>.
+	 * Get the underlying {@link SQLException}.
-	 * @return SQLException
+	 *
+	 * @return The SQLException
 	 */
 	public SQLException getSQLException() {
 		return sqlException;
 	}
 	
 	/**
-	 * Get the actual SQL statement that caused the exception
+	 * Get the actual SQL statement being executed when the exception occurred.
-	 * (may be null)
+	 *
+	 * @return The SQL statement; may return null.
 	 */
 	public String getSQL() {
 		return sql;

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

@@ -44,7 +44,7 @@ public class LazyInitializationException extends HibernateException {
 	);
 
 	/**
-	 * Constructs a LazyInitializationException using the given message
+	 * Constructs a LazyInitializationException using the given message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -75,13 +75,13 @@ public class LockOptions implements Serializable {
 	private Map<String,LockMode> aliasSpecificLockModes;
 
 	/**
-	 * Constructs a LockOptions with all default options
+	 * Constructs a LockOptions with all default options.
 	 */
 	public LockOptions() {
 	}
 
 	/**
-	 * Constructs a LockOptions with the given lock mode
+	 * Constructs a LockOptions with the given lock mode.
 	 *
 	 * @param lockMode The lock mode to use
 	 */
@@ -173,6 +173,11 @@ public class LockOptions implements Serializable {
 		return lockMode == null ? LockMode.NONE : lockMode;
 	}
 
+	/**
+	 * Does this LockOptions object define alias-specific lock modes?
+	 *
+	 * @return {@code true} if this LockOptions object define alias-specific lock modes; {@code false} otherwise.
+	 */
 	public boolean hasAliasSpecificLockModes() {
 		return aliasSpecificLockModes != null
 				&& ! aliasSpecificLockModes.isEmpty();
@@ -203,7 +208,7 @@ public class LockOptions implements Serializable {
 	}
 
 	/**
-	 * Currently needed for follow-on locking
+	 * Currently needed for follow-on locking.
 	 *
 	 * @return The greatest of all requested lock modes.
 	 */
@@ -256,7 +261,7 @@ public class LockOptions implements Serializable {
 		return this;
 	}
 
-	private boolean scope=false;
+	private boolean scope;
 
 	/**
 	 * Retrieve the current lock scope setting.
@@ -293,7 +298,7 @@ public class LockOptions implements Serializable {
 	}
 
 	/**
-	 * Perform a shallow copy
+	 * Perform a shallow copy.
 	 *
 	 * @param source Source for the copy (copied from)
 	 * @param destination Destination for the copy (copied to)

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

@@ -31,7 +31,7 @@ package org.hibernate;
  */
 public class MappingException extends HibernateException {
 	/**
-	 * Constructs a MappingException using the given information
+	 * Constructs a MappingException using the given information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param cause The underlying cause
@@ -41,7 +41,7 @@ public class MappingException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a MappingException using the given information
+	 * Constructs a MappingException using the given information.
 	 *
 	 * @param cause The underlying cause
 	 */
@@ -50,7 +50,7 @@ public class MappingException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a MappingException using the given information
+	 * Constructs a MappingException using the given information.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -61,7 +61,7 @@ public enum MultiTenancyStrategy {
 	/**
 	 * 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}
+	 * traditional {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider}?
 	 *
 	 * @return {@code true} indicates a MultiTenantConnectionProvider is required; {@code false} indicates it is not.
 	 */

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

@@ -52,7 +52,7 @@ public class NonUniqueObjectException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a NonUniqueObjectException using the given information, using a standard message
+	 * Constructs a NonUniqueObjectException using the given information, using a standard message.
 	 *
 	 * @param entityId The identifier of the entity
 	 * @param entityName The name of the entity

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

@@ -32,7 +32,7 @@ package org.hibernate;
  */
 public class NonUniqueResultException extends HibernateException {
 	/**
-	 * Constructs a NonUniqueResultException
+	 * Constructs a NonUniqueResultException.
 	 *
 	 * @param resultCount The number of actual results.
 	 */

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

@@ -32,7 +32,7 @@ import java.io.Serializable;
  */
 public class ObjectDeletedException extends UnresolvableObjectException {
 	/**
-	 * Constructs an ObjectDeletedException using the given information
+	 * Constructs an ObjectDeletedException using the given information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param identifier The identifier of the entity

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

@@ -35,7 +35,7 @@ import org.hibernate.dialect.lock.OptimisticEntityLockException;
 @Deprecated
 public class OptimisticLockException extends OptimisticEntityLockException {
 	/**
-	 * Constructs a OptimisticLockException using the specified information
+	 * 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

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

@@ -32,7 +32,7 @@ import java.sql.SQLException;
  */
 public class PessimisticLockException extends JDBCException {
 	/**
-	 * Constructs a PessimisticLockException using the specified information
+	 * Constructs a PessimisticLockException using the specified information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param sqlException The underlying SQL exception

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

@@ -77,6 +77,7 @@ import org.hibernate.type.Type;
  *
  * @author Gavin King
  */
+@SuppressWarnings("UnusedDeclaration")
 public interface Query extends BasicQueryContract {
 	/**
 	 * Get the query string.
@@ -163,6 +164,8 @@ public interface Query extends BasicQueryContract {
 	 * </ol>
 	 * For alias-specific locking, use {@link #setLockMode(String, LockMode)}.
 	 *
+	 * @param lockOptions The lock options to apply to the query.
+	 *
 	 * @return {@code this}, for method chaining
 	 *
 	 * @see #getLockOptions()
@@ -179,7 +182,8 @@ public interface Query extends BasicQueryContract {
 	 * speaking, for maximum portability, this method should only be used to mark that the rows corresponding to
 	 * the given alias should be included in pessimistic locking ({@link LockMode#PESSIMISTIC_WRITE}).
 	 *
-	 * @param alias a query alias, or <tt>this</tt> for a collection filter
+	 * @param alias a query alias, or {@code "this"} for a collection filter
+	 * @param lockMode The lock mode to apply.
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -209,7 +213,7 @@ public interface Query extends BasicQueryContract {
 	public Query setComment(String comment);
 
 	/**
-	 * Return the HQL select clause aliases (if any)
+	 * Return the HQL select clause aliases, if any.
 	 *
 	 * @return an array of aliases as strings
 	 */
@@ -246,14 +250,16 @@ public interface Query extends BasicQueryContract {
 	public ScrollableResults scroll();
 
 	/**
-	 * Return the query results as <tt>ScrollableResults</tt>. The
+	 * Return the query results as ScrollableResults. The scrollability of the returned results
-	 * scrollability of the returned results depends upon JDBC driver
+	 * depends upon JDBC driver support for scrollable ResultSets.
-	 * support for scrollable <tt>ResultSet</tt>s.<br>
+	 *
+	 * @param scrollMode The scroll mode
+	 *
+	 * @return the result iterator
 	 *
 	 * @see ScrollableResults
 	 * @see ScrollMode
 	 *
-	 * @return the result iterator
 	 */
 	public ScrollableResults scroll(ScrollMode scrollMode);
 
@@ -278,9 +284,8 @@ public interface Query extends BasicQueryContract {
 
 	/**
 	 * Execute the update or delete statement.
-	 * </p>
+	 *
-	 * The semantics are compliant with the ejb3 Query.executeUpdate()
+	 * The semantics are compliant with the ejb3 Query.executeUpdate() method.
-	 * method.
 	 *
 	 * @return The number of entities updated or deleted.
 	 */
@@ -407,7 +412,7 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @return {@code this}, for method chaining
 	 */	
-	public Query setProperties(Object bean) throws HibernateException;
+	public Query setProperties(Object bean);
 	
 	/**
 	 * Bind the values of the given Map for each named parameters of the query,
@@ -418,45 +423,356 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @return {@code this}, for method chaining
 	 */
-	public Query setProperties(Map bean) throws HibernateException;
+	public Query setProperties(Map bean);
 
+	/**
+	 * Bind a positional String-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setString(int position, String val);
+
+	/**
+	 * Bind a positional char-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCharacter(int position, char val);
+
+	/**
+	 * Bind a positional boolean-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBoolean(int position, boolean val);
+
+	/**
+	 * Bind a positional byte-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setByte(int position, byte val);
+
+	/**
+	 * Bind a positional short-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setShort(int position, short val);
+
+	/**
+	 * Bind a positional int-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setInteger(int position, int val);
+
+	/**
+	 * Bind a positional long-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setLong(int position, long val);
+
+	/**
+	 * Bind a positional float-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setFloat(int position, float val);
+
+	/**
+	 * Bind a positional double-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setDouble(int position, double val);
+
+	/**
+	 * Bind a positional binary-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBinary(int position, byte[] val);
+
+	/**
+	 * Bind a positional String-valued parameter using streaming.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setText(int position, String val);
+
+	/**
+	 * Bind a positional binary-valued parameter using serialization.
+	 *
+	 * @param position The parameter position
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setSerializable(int position, Serializable val);
+
+	/**
+	 * Bind a positional Locale-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param locale The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setLocale(int position, Locale locale);
+
+	/**
+	 * Bind a positional BigDecimal-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param number The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBigDecimal(int position, BigDecimal number);
+
+	/**
+	 * Bind a positional BigDecimal-valued parameter.
+	 *
+	 * @param position The parameter position
+	 * @param number The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBigInteger(int position, BigInteger number);
 
+	/**
+	 * Bind a positional Date-valued parameter using just the Date portion.
+	 *
+	 * @param position The parameter position
+	 * @param date The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setDate(int position, Date date);
+
+	/**
+	 * Bind a positional Date-valued parameter using just the Time portion.
+	 *
+	 * @param position The parameter position
+	 * @param date The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setTime(int position, Date date);
+
+	/**
+	 * Bind a positional Date-valued parameter using the full Timestamp.
+	 *
+	 * @param position The parameter position
+	 * @param date The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setTimestamp(int position, Date date);
 
+	/**
+	 * Bind a positional Calendar-valued parameter using the full Timestamp portion.
+	 *
+	 * @param position The parameter position
+	 * @param calendar The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCalendar(int position, Calendar calendar);
+
+	/**
+	 * Bind a positional Calendar-valued parameter using just the Date portion.
+	 *
+	 * @param position The parameter position
+	 * @param calendar The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCalendarDate(int position, Calendar calendar);
 
+	/**
+	 * Bind a named String-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setString(String name, String val);
+
+	/**
+	 * Bind a named char-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCharacter(String name, char val);
+
+	/**
+	 * Bind a named boolean-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBoolean(String name, boolean val);
+
+	/**
+	 * Bind a named byte-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setByte(String name, byte val);
+
+	/**
+	 * Bind a named short-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setShort(String name, short val);
+
+	/**
+	 * Bind a named int-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setInteger(String name, int val);
+
+	/**
+	 * Bind a named long-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setLong(String name, long val);
+
+	/**
+	 * Bind a named float-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setFloat(String name, float val);
+
+	/**
+	 * Bind a named double-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setDouble(String name, double val);
+
+	/**
+	 * Bind a named binary-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBinary(String name, byte[] val);
+
+	/**
+	 * Bind a named String-valued parameter using streaming.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setText(String name, String val);
+
+	/**
+	 * Bind a named binary-valued parameter using serialization.
+	 *
+	 * @param name The parameter name
+	 * @param val The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setSerializable(String name, Serializable val);
+
+	/**
+	 * Bind a named Locale-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param locale The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setLocale(String name, Locale locale);
+
+	/**
+	 * Bind a named BigDecimal-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param number The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBigDecimal(String name, BigDecimal number);
+
+	/**
+	 * Bind a named BigInteger-valued parameter.
+	 *
+	 * @param name The parameter name
+	 * @param number The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setBigInteger(String name, BigInteger number);
 
 	/**
@@ -489,11 +805,29 @@ public interface Query extends BasicQueryContract {
 	 */
 	public Query setTimestamp(String name, Date date);
 
+	/**
+	 * Bind a named Calendar-valued parameter using the full Timestamp.
+	 *
+	 * @param name The parameter name
+	 * @param calendar The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCalendar(String name, Calendar calendar);
+
+	/**
+	 * Bind a named Calendar-valued parameter using just the Date portion.
+	 *
+	 * @param name The parameter name
+	 * @param calendar The bind value
+	 *
+	 * @return {@code this}, for method chaining
+	 */
 	public Query setCalendarDate(String name, Calendar calendar);
 
 	/**
 	 * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
+	 * Use {@link #setParameter(int, Object)} for null values.
 	 *
 	 * @param position the position of the parameter in the query
 	 * string, numbered from <tt>0</tt>.
@@ -501,17 +835,18 @@ public interface Query extends BasicQueryContract {
 	 *
 	 * @return {@code this}, for method chaining
 	 */
-	public Query setEntity(int position, Object val); // use setParameter for null values
+	public Query setEntity(int position, Object val);
 
 	/**
-	 * Bind an instance of a mapped persistent class to a named query parameter.
+	 * Bind an instance of a mapped persistent class to a named query parameter.  Use
+	 * {@link #setParameter(String, Object)} for null values.
 	 *
 	 * @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
+	public Query setEntity(String name, Object val);
 	
 	
 	/**

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

@@ -34,7 +34,7 @@ public class QueryException extends HibernateException {
 	private String queryString;
 
 	/**
-	 * Constructs a QueryException using the specified exception message
+	 * Constructs a QueryException using the specified exception message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */
@@ -43,7 +43,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified exception message and cause
+	 * Constructs a QueryException using the specified exception message and cause.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param cause The underlying cause
@@ -53,7 +53,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified exception message and query-string
+	 * 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
@@ -64,7 +64,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified cause
+	 * Constructs a QueryException using the specified cause.
 	 *
 	 * @param cause The underlying cause
 	 */
@@ -82,7 +82,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Set the query string.  EVen an option, since often the part of the code generating the exception does not
+	 * 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.
@@ -108,10 +108,3 @@ public class QueryException extends HibernateException {
 	}
 
 }
-
-
-
-
-
-
-

hibernate-core/src/main/java/org/hibernate/QueryParameterException.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,21 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
-package org.hibernate;
+package org.hibernate;
-
 
 /**
- * Parameter invalid or not found in the query
+ * Parameter invalid or not found in the query.
  * 
  * @author Emmanuel Bernard
  */
 public class QueryParameterException extends QueryException {
-
+	/**
-	public QueryParameterException(Exception e) {
+	 * Constructs a QueryParameterException using the supplied exception message.
-		super( e );
+	 *
-	}
+	 * @param message The message explaining the exception condition
-
+	 */
 	public QueryParameterException(String message) {
 		super( message );
 	}
-
-	public QueryParameterException(String message, Throwable e) {
-		super( message, e );
-	}
-
-	public QueryParameterException(String message, String queryString) {
-		super( message, queryString );
-	}
 }

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

@@ -1,10 +1,10 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2009, Red Hat Middleware LLC or third-party contributors as
+ * Copyright (c) 2009, 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,26 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.sql.SQLException;
 
 /**
- *
  * Thrown when a database query timeout occurs.
  *
  * @author Scott Marlow
  */
-
 public class QueryTimeoutException extends JDBCException {
-
+	/**
-	public QueryTimeoutException( String s, JDBCException je, String sql ) {
+	 * Constructs a QueryTimeoutException using the supplied information.
-		super(s, je.getSQLException(), sql);
+	 *
-	}
+	 * @param message The message explaining the exception condition
-
+	 * @param sqlException The underlying SQLException
-	public QueryTimeoutException( String s, SQLException se, String sql ) {
+	 * @param sql The sql being executed when the exception occurred.
-		super(s, se, sql);
+	 */
+	public QueryTimeoutException(String message, SQLException sqlException, String sql) {
+		super(message, sqlException, sql);
 	}
 
 }

hibernate-core/src/main/java/org/hibernate/ReplicationMode.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;
 
@@ -37,6 +36,7 @@ public enum ReplicationMode {
 	 * Throw an exception when a row already exists.
 	 */
 	EXCEPTION {
+		@Override
 		public boolean shouldOverwriteCurrentVersion(Object entity, Object currentVersion, Object newVersion, VersionType versionType) {
 			throw new AssertionFailure( "should not be called" );
 		}
@@ -45,6 +45,7 @@ public enum ReplicationMode {
 	 * Ignore replicated entities when a row already exists.
 	 */
 	IGNORE {
+		@Override
 		public boolean shouldOverwriteCurrentVersion(Object entity, Object currentVersion, Object newVersion, VersionType versionType) {
 			return false;
 		}
@@ -53,6 +54,7 @@ public enum ReplicationMode {
 	 * Overwrite existing rows when a row already exists.
 	 */
 	OVERWRITE {
+		@Override
 		public boolean shouldOverwriteCurrentVersion(Object entity, Object currentVersion, Object newVersion, VersionType versionType) {
 			return true;
 		}
@@ -61,17 +63,26 @@ public enum ReplicationMode {
 	 * When a row already exists, choose the latest version.
 	 */
 	LATEST_VERSION {
+		@Override
+		@SuppressWarnings("unchecked")
 		public boolean shouldOverwriteCurrentVersion(Object entity, Object currentVersion, Object newVersion, VersionType versionType) {
-			if ( versionType == null ) {
+			// always overwrite non-versioned data (because we don't know which is newer)
-				return true; //always overwrite nonversioned data
+			return versionType == null || versionType.getComparator().compare( currentVersion, newVersion ) <= 0;
-			}
-			return versionType.getComparator().compare( currentVersion, newVersion ) <= 0;
 		}
 	};
 
+	/**
+	 * Determine whether the mode dictates that the data being replicated should overwrite the data found.
+	 *
+	 * @param entity The entity being replicated
+	 * @param currentVersion The version currently on the target database table.
+	 * @param newVersion The replicating version
+	 * @param versionType The version type
+	 *
+	 * @return {@code true} indicates the data should be overwritten; {@code false} indicates it should not.
+	 */
 	public abstract boolean shouldOverwriteCurrentVersion(Object entity, Object currentVersion, Object newVersion, VersionType versionType);
 
-
 }
 
 

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

@@ -29,11 +29,12 @@ package org.hibernate;
  * @author Steve Ebersole
  */
 public class ResourceClosedException extends HibernateException {
-	public ResourceClosedException(String s) {
+	/**
-		super( s );
+	 * Constructs a ResourceClosedException using the supplied message.
-	}
+	 *
-
+	 * @param message The message explaining the exception condition
-	public ResourceClosedException(String string, Throwable root) {
+	 */
-		super( string, root );
+	public ResourceClosedException(String message) {
+		super( message );
 	}
 }

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

@@ -28,20 +28,33 @@ import org.hibernate.engine.query.spi.sql.NativeSQLQueryReturn;
 import org.hibernate.type.Type;
 
 /**
- * Represents a "native sql" query and allows the user to define certain aspects about its execution, such as:<ul>
+ * Represents a "native sql" query.
- * <li>result-set value mapping (see below)</li>
- * <li>
- * 	Tables used via {@link #addSynchronizedQuerySpace}, {@link #addSynchronizedEntityName} and
- *  {@link #addSynchronizedEntityClass}.  This allows Hibernate to properly know how to deal with auto-flush checking
- *  as well as cached query results if the results of the query are being cached.
- * </li>
- * </ul>
- * <p/>
- * In terms of result-set mapping, there are 3 approaches to defining:<ul>
- * <li>If this represents a named sql query, the mapping could be associated with the query as part of its metadata</li>
- * <li>A pre-defined (defined in metadata and named) mapping can be associated with {@link #setResultSetMapping}</li>
- * <li>Defined locally per the various {@link #addEntity}, {@link #addRoot}, {@link #addJoin}, {@link #addFetch} and {@link #addScalar} methods</li>
  *
+ * Allows the user to define certain aspects about its execution, such as:<ul>
+ *     <li>
+ *         result-set value mapping (see below)
+ *     </li>
+ *     <li>
+ *         Tables used via {@link #addSynchronizedQuerySpace}, {@link #addSynchronizedEntityName} and
+ *         {@link #addSynchronizedEntityClass}.  This allows Hibernate to know how to properly deal with
+ *         auto-flush checking as well as cached query results if the results of the query are being
+ *         cached.
+ *     </li>
+ * </ul>
+ *
+ * In terms of result-set mapping, there are 3 approaches to defining:<ul>
+ *     <li>
+ *         If this represents a named sql query, the mapping could be associated with the query as part
+ *         of its metadata
+ *     </li>
+ *     <li>
+ *         A pre-defined (defined in metadata and named) mapping can be associated with
+ *         {@link #setResultSetMapping}
+ *     </li>
+ *     <li>
+ *         Defined locally per the various {@link #addEntity}, {@link #addRoot}, {@link #addJoin},
+ *         {@link #addFetch} and {@link #addScalar} methods
+ *     </li>
  * </ul>
  * 
  * @author Gavin King
@@ -74,6 +87,11 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	 */
 	public boolean isCallable();
 
+	/**
+	 * Retrieve the returns associated with this query.
+	 *
+	 * @return The return descriptors
+	 */
 	public List<NativeSQLQueryReturn> getQueryReturns();
 
 	/**
@@ -100,7 +118,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addScalar(String columnAlias, Type type);
 
 	/**
-	 * Add a new root return mapping, returning a {@link RootReturn} to allow further definition
+	 * Add a new root return mapping, returning a {@link RootReturn} to allow further definition.
 	 *
 	 * @param tableAlias The SQL table alias to map to this entity
 	 * @param entityName The name of the entity.
@@ -112,7 +130,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public RootReturn addRoot(String tableAlias, String entityName);
 
 	/**
-	 * Add a new root return mapping, returning a {@link RootReturn} to allow further definition
+	 * Add a new root return mapping, returning a {@link RootReturn} to allow further definition.
 	 *
 	 * @param tableAlias The SQL table alias to map to this entity
 	 * @param entityType The java type of the entity.
@@ -136,7 +154,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addEntity(String entityName);
 
 	/**
-	 * Declare a "root" entity
+	 * Declare a "root" entity.
 	 *
 	 * @param tableAlias The SQL table alias
 	 * @param entityName The entity name
@@ -146,7 +164,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addEntity(String tableAlias, String entityName);
 
 	/**
-	 * Declare a "root" entity, specifying a lock mode
+	 * Declare a "root" entity, specifying a lock mode.
 	 *
 	 * @param tableAlias The SQL table alias
 	 * @param entityName The entity name
@@ -167,7 +185,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addEntity(Class entityType);
 
 	/**
-	 * Declare a "root" entity
+	 * Declare a "root" entity.
 	 *
 	 * @param tableAlias The SQL table alias
 	 * @param entityType The java type of the entity to add as a root
@@ -177,7 +195,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addEntity(String tableAlias, Class entityType);
 
 	/**
-	 * Declare a "root" entity, specifying a lock mode
+	 * Declare a "root" entity, specifying a lock mode.
 	 *
 	 * @param tableAlias The SQL table alias
 	 * @param entityName The entity name
@@ -226,7 +244,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	public SQLQuery addJoin(String tableAlias, String ownerTableAlias, String joinPropertyName);
 
 	/**
-	 * Declare a join fetch result, specifying a lock mode
+	 * Declare a join fetch result, specifying a lock mode.
 	 *
 	 * @param tableAlias The SQL table alias for the data to be mapped to this fetch
 	 * @param path The association path ([owner-alias].[property-name]).
@@ -252,11 +270,11 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	}
 
 	/**
-	 * Allows access to further control how root returns are mapped back from result sets
+	 * Allows access to further control how root returns are mapped back from result sets.
 	 */
 	public static interface RootReturn {
 		/**
-		 * Set the lock mode for this return
+		 * Set the lock mode for this return.
 		 *
 		 * @param lockMode The new lock mode.
 		 *
@@ -265,7 +283,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 		public RootReturn setLockMode(LockMode lockMode);
 
 		/**
-		 * Name the column alias that identifies the entity's discriminator
+		 * Name the column alias that identifies the entity's discriminator.
 		 *
 		 * @param columnAlias The discriminator column alias
 		 *
@@ -274,7 +292,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 		public RootReturn setDiscriminatorAlias(String columnAlias);
 
 		/**
-		 * Add a simple property-to-one-column mapping
+		 * Add a simple property-to-one-column mapping.
 		 *
 		 * @param propertyName The name of the property.
 		 * @param columnAlias The name of the column
@@ -294,11 +312,11 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 	}
 
 	/**
-	 * Allows access to further control how join fetch returns are mapped back from result sets
+	 * Allows access to further control how join fetch returns are mapped back from result sets.
 	 */
 	public static interface FetchReturn {
 		/**
-		 * Set the lock mode for this return
+		 * Set the lock mode for this return.
 		 *
 		 * @param lockMode The new lock mode.
 		 *
@@ -307,7 +325,7 @@ public interface SQLQuery extends Query, SynchronizeableQuery {
 		public FetchReturn setLockMode(LockMode lockMode);
 
 		/**
-		 * Add a simple property-to-one-column mapping
+		 * Add a simple property-to-one-column mapping.
 		 *
 		 * @param propertyName The name of the property.
 		 * @param columnAlias The name of the column

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

@@ -1,52 +0,0 @@
-/*
- * Hibernate, Relational Persistence for Idiomatic Java
- *
- * Copyright (c) 2010, 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;
-import org.hibernate.engine.query.spi.sql.NativeSQLQueryReturn;
-import org.hibernate.type.Type;
-
-/**
- * Allows programmatic access from {@link SQLQuery} to define how to map SQL {@link java.sql.ResultSet results}
- * back to in-memory objects, both entities as well as scalars.  Essentially it defines an API akin to the
- * {@code <return/>}, {@code <return-scalar/>} and {@code <return-join/>} elements under {@code <sql-query/>}
- * definition in a Hibernate <tt>hbm.xml</tt> file.
- *
- * @author Steve Ebersole
- */
-public interface SQLQueryResultMappingBuilder {
-
-	public static interface ReturnsHolder {
-		public void add(NativeSQLQueryReturn queryReturn);
-	}
-
-	public static class ScalarReturn {
-		private final ReturnsHolder returnsHolder;
-		private String name;
-		private Type type;
-
-		public ScalarReturn(ReturnsHolder returnsHolder) {
-			this.returnsHolder = returnsHolder;
-		}
-	}
-
-}

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

@@ -27,58 +27,60 @@ package org.hibernate;
 import java.sql.ResultSet;
 
 /**
- * Specifies the type of JDBC scrollable result set to use
+ * Specifies the type of JDBC scrollable result set to use underneath a {@link ScrollableResults}.
- * underneath a <tt>ScrollableResults</tt>
  *
  * @author Gavin King
- * @see Query#scroll(ScrollMode)
- * @see ScrollableResults
  */
 public enum ScrollMode {
 	/**
+	 * Requests a scrollable result that is only scrollable forwards.
+	 *
 	 * @see java.sql.ResultSet#TYPE_FORWARD_ONLY
 	 */
 	FORWARD_ONLY( ResultSet.TYPE_FORWARD_ONLY ),
 
 	/**
+	 * Requests a scrollable result which is sensitive to changes in the underlying data
+	 *
 	 * @see java.sql.ResultSet#TYPE_SCROLL_SENSITIVE
 	 */
-	SCROLL_SENSITIVE(
+	SCROLL_SENSITIVE( ResultSet.TYPE_SCROLL_SENSITIVE ),
-			ResultSet.TYPE_SCROLL_SENSITIVE
+
-	),
 	/**
+	 * Requests a scrollable result which is insensitive to changes in the underlying data
+	 *
 	 * Note that since the Hibernate session acts as a cache, you
-	 * might need to expicitly evict objects, if you need to see
+	 * might need to explicitly evict objects, if you need to see
 	 * changes made by other transactions.
 	 *
 	 * @see java.sql.ResultSet#TYPE_SCROLL_INSENSITIVE
 	 */
-	SCROLL_INSENSITIVE(
+	SCROLL_INSENSITIVE( ResultSet.TYPE_SCROLL_INSENSITIVE );
-			ResultSet.TYPE_SCROLL_INSENSITIVE
+
-	);
 	private final int resultSetType;
 
 	private ScrollMode(int level) {
 		this.resultSetType = level;
 	}
 
-
 	/**
+	 * Get the corresponding JDBC scroll type code constant value.
+	 *
 	 * @return the JDBC result set type code
 	 */
 	public int toResultSetType() {
 		return resultSetType;
 	}
 
-
+	/**
+	 * Determine if {@code this} mode is "less than" the provided mode.
+	 *
+	 * @param other The provided mode
+	 *
+	 * @return {@code true} if this mode is less than the other.
+	 */
 	public boolean lessThan(ScrollMode other) {
 		return this.resultSetType < other.resultSetType;
 	}
 
 }
-
-
-
-
-
-

hibernate-core/src/main/java/org/hibernate/ScrollableResults.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) 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;
 import java.math.BigDecimal;
@@ -44,179 +43,335 @@ import org.hibernate.type.Type;
  * Contrary to JDBC, columns of results are numbered from zero.
  *
  * @see Query#scroll()
+ *
  * @author Gavin King
  */
 public interface ScrollableResults {
 	/**
-	 * Advance to the next result
+	 * Advance to the next result.
-	 * @return <tt>true</tt> if there is another result
+	 *
+	 * @return {@code true} if there is another result
 	 */
-	public boolean next() throws HibernateException;
+	public boolean next();
+
 	/**
-	 * Retreat to the previous result
+	 * Retreat to the previous result.
-	 * @return <tt>true</tt> if there is a previous result
+	 *
+	 * @return {@code true} if there is a previous result
 	 */
-	public boolean previous() throws HibernateException;
+	public boolean previous();
+
 	/**
-	 * Scroll an arbitrary number of locations
+	 * Scroll the specified number of positions from the current position.
-	 * @param i a positive (forward) or negative (backward) number of rows
+	 *
-	 * @return <tt>true</tt> if there is a result at the new location
+	 * @param positions a positive (forward) or negative (backward) number of rows
+	 *
+	 * @return {@code true} if there is a result at the new location
 	 */
-	public boolean scroll(int i) throws HibernateException;
+	public boolean scroll(int positions);
+
 	/**
-	 * Go to the last result
+	 * Go to the last result.
-	 * @return <tt>true</tt> if there are any results
+	 *
+	 * @return {@code true} if there are any results
 	 */
-	public boolean last() throws HibernateException;
+	public boolean last();
+
 	/**
-	 * Go to the first result
+	 * Go to the first result.
-	 * @return <tt>true</tt> if there are any results
+	 *
+	 * @return {@code true} if there are any results
 	 */
-	public boolean first() throws HibernateException;
+	public boolean first();
+
 	/**
-	 * Go to a location just before first result (this is the initial location)
+	 * Go to a location just before first result,  This is the location of the cursor on a newly returned
+	 * scrollable result.
 	 */
-	public void beforeFirst() throws HibernateException;
+	public void beforeFirst();
+
 	/**
-	 * Go to a location just after the last result
+	 * Go to a location just after the last result.
 	 */
-	public void afterLast() throws HibernateException;
+	public void afterLast();
+
 	/**
 	 * Is this the first result?
 	 *
-	 * @return <tt>true</tt> if this is the first row of results
+	 * @return {@code true} if this is the first row of results, otherwise {@code false}
-	 * @throws HibernateException
 	 */
-	public boolean isFirst() throws HibernateException;
+	public boolean isFirst();
+
 	/**
 	 * Is this the last result?
 	 *
-	 * @return <tt>true</tt> if this is the last row of results
+	 * @return {@code true} if this is the last row of results.
-	 * @throws HibernateException
 	 */
-	public boolean isLast() throws HibernateException;
+	public boolean isLast();
+
+	/**
+	 * Get the current position in the results. The first position is number 0 (unlike JDBC).
+	 *
+	 * @return The current position number, numbered from 0; -1 indicates that there is no current row
+	 */
+	public int getRowNumber();
+
+	/**
+	 * Set the current position in the result set.  Can be numbered from the first position (positive number) or
+	 * the last row (negative number).
+	 *
+	 * @param rowNumber the row number.  A positive number indicates a value numbered from the first row; a
+	 * negative number indicates a value numbered from the last row.
+	 *
+	 * @return true if there is a row at that row number
+	 */
+	public boolean setRowNumber(int rowNumber);
+
 	/**
 	 * Release resources immediately.
 	 */
-	public void close() throws HibernateException;
+	public void close();
+
 	/**
-	 * Get the current row of results
+	 * Get the current row of results.
-	 * @return an object or array
+	 *
+	 * @return The array of results
 	 */
-	public Object[] get() throws HibernateException;
+	public Object[] get();
+
 	/**
 	 * Get the <tt>i</tt>th object in the current row of results, without
 	 * initializing any other results in the row. This method may be used
 	 * safely, regardless of the type of the column (ie. even for scalar
 	 * results).
+	 *
 	 * @param i the column, numbered from zero
-	 * @return an object of any Hibernate type or <tt>null</tt>
+	 *
+	 * @return The requested result object; may return {@code null}
+	 *
+	 * @throws IndexOutOfBoundsException If i is an invalid index.
 	 */
-	public Object get(int i) throws HibernateException;
+	public Object get(int i);
 
 	/**
-	 * Get the type of the <tt>i</tt>th column of results
+	 * Get the type of the <tt>i</tt>th column of results.
+	 *
 	 * @param i the column, numbered from zero
+	 *
 	 * @return the Hibernate type
+	 *
+	 * @throws IndexOutOfBoundsException If i is an invalid index.
 	 */
 	public Type getType(int i);
 
 	/**
-	 * Convenience method to read an <tt>integer</tt>
+	 * Convenience method to read an integer.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as an integer
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Integer getInteger(int col) throws HibernateException;
+	public Integer getInteger(int col);
+
 	/**
-	 * Convenience method to read a <tt>long</tt>
+	 * Convenience method to read a long.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a long
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Long getLong(int col) throws HibernateException;
+	public Long getLong(int col);
+
 	/**
-	 * Convenience method to read a <tt>float</tt>
+	 * Convenience method to read a float.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a float
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Float getFloat(int col) throws HibernateException;
+	public Float getFloat(int col);
+
 	/**
-	 * Convenience method to read a <tt>boolean</tt>
+	 * Convenience method to read a boolean.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a boolean
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Boolean getBoolean(int col) throws HibernateException;
+	public Boolean getBoolean(int col);
+
 	/**
-	 * Convenience method to read a <tt>double</tt>
+	 * Convenience method to read a double.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a double
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Double getDouble(int col) throws HibernateException;
+	public Double getDouble(int col);
+
 	/**
-	 * Convenience method to read a <tt>short</tt>
+	 * Convenience method to read a short.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a short
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Short getShort(int col) throws HibernateException;
+	public Short getShort(int col);
+
 	/**
-	 * Convenience method to read a <tt>byte</tt>
+	 * Convenience method to read a byte.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a byte
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Byte getByte(int col) throws HibernateException;
+	public Byte getByte(int col);
+
 	/**
-	 * Convenience method to read a <tt>character</tt>
+	 * Convenience method to read a char.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a char
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Character getCharacter(int col) throws HibernateException;
+	public Character getCharacter(int col);
+
 	/**
-	 * Convenience method to read a <tt>binary</tt>
+	 * Convenience method to read a binary (byte[]).
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a binary (byte[])
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public byte[] getBinary(int col) throws HibernateException;
+	public byte[] getBinary(int col);
+
 	/**
-	 * Convenience method to read <tt>text</tt>
+	 * Convenience method to read a String using streaming.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a String
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public String getText(int col) throws HibernateException;
+	public String getText(int col);
+
 	/**
-	 * Convenience method to read a <tt>blob</tt>
+	 * Convenience method to read a blob.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a Blob
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Blob getBlob(int col) throws HibernateException;
+	public Blob getBlob(int col);
+
 	/**
-	 * Convenience method to read a <tt>clob</tt>
+	 * Convenience method to read a clob.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a Clob
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Clob getClob(int col) throws HibernateException;
+	public Clob getClob(int col);
+
 	/**
-	 * Convenience method to read a <tt>string</tt>
+	 * Convenience method to read a string.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a String
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public String getString(int col) throws HibernateException;
+	public String getString(int col);
+
 	/**
-	 * Convenience method to read a <tt>big_decimal</tt>
+	 * Convenience method to read a BigDecimal.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a BigDecimal
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public BigDecimal getBigDecimal(int col) throws HibernateException;
+	public BigDecimal getBigDecimal(int col);
+
 	/**
-	 * Convenience method to read a <tt>big_integer</tt>
+	 * Convenience method to read a BigInteger.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a BigInteger
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public BigInteger getBigInteger(int col) throws HibernateException;
+	public BigInteger getBigInteger(int col);
+
 	/**
-	 * Convenience method to read a <tt>date</tt>, <tt>time</tt> or <tt>timestamp</tt>
+	 * Convenience method to read a Date.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a Date
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Date getDate(int col) throws HibernateException;
+	public Date getDate(int col);
+
 	/**
-	 * Convenience method to read a <tt>locale</tt>
+	 * Convenience method to read a Locale.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a Locale
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Locale getLocale(int col) throws HibernateException;
+	public Locale getLocale(int col);
+
 	/**
-	 * Convenience method to read a <tt>calendar</tt> or <tt>calendar_date</tt>
+	 * Convenience method to read a Calendar.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a Calendar
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	public Calendar getCalendar(int col) throws HibernateException;
+	public Calendar getCalendar(int col);
+
 	/**
-	 * Convenience method to read a <tt>currency</tt>
+	 * Convenience method to read a TimeZone.
+	 *
+	 * @param col The column, numbered from zero
+	 *
+	 * @return The column value as a TimeZone
+	 *
+	 * @throws IndexOutOfBoundsException If col is an invalid index.
 	 */
-	//public Currency getCurrency(int col) throws HibernateException;
+	public TimeZone getTimeZone(int col);
-	/**
-	 * Convenience method to read a <tt>timezone</tt>
-	 */
-	public TimeZone getTimeZone(int col) throws HibernateException;
-	/**
-	 * Get the current location in the result set. The first
-	 * row is number <tt>0</tt>, contrary to JDBC.
-	 * @return the row number, numbered from <tt>0</tt>, or <tt>-1</tt> if
-	 * there is no current row
-	 */
-	public int getRowNumber() throws HibernateException;
-	/**
-	 * Set the current location in the result set, numbered from either the
-	 * first row (row number <tt>0</tt>), or the last row (row
-	 * number <tt>-1</tt>).
-	 * @param rowNumber the row number, numbered from the last row, in the
-	 * case of a negative row number
-	 * @return true if there is a row at that row number
-	 */
-	public boolean setRowNumber(int rowNumber) throws HibernateException;
 }
 
 

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

@@ -565,6 +565,7 @@ public interface Session extends SharedSessionContract {
 	 * with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
 	 * instances if the association is mapped with <tt>cascade="lock"</tt>.
 	 *
+	 * @param entityName The name of the entity
 	 * @param object a persistent or transient instance
 	 * @param lockMode the lock level
 	 *
@@ -771,7 +772,7 @@ public interface Session extends SharedSessionContract {
 	public Object get(String entityName, Serializable id, LockOptions lockOptions);
 
 	/**
-	 * Return the entity name for a persistent entity
+	 * Return the entity name for a persistent entity.
 	 *   
 	 * @param object a persistent entity
 	 *
@@ -932,6 +933,7 @@ public interface Session extends SharedSessionContract {
 	 * execution returns the result of the {@link ReturningWork#execute} call.
 	 *
 	 * @param work The work to be performed.
+	 * @param <T> The type of the result returned from the work
 	 *
 	 * @return the result from calling {@link ReturningWork#execute}.
 	 *
@@ -1020,7 +1022,15 @@ public interface Session extends SharedSessionContract {
 	 * Contains locking details (LockMode, Timeout and Scope).
 	 */
 	public interface LockRequest {
+		/**
+		 * Constant usable as a time out value that indicates no wait semantics should be used in
+		 * attempting to acquire locks.
+		 */
 		static final int PESSIMISTIC_NO_WAIT = 0;
+		/**
+		 * Constant usable as a time out value that indicates that attempting to acquire locks should be allowed to
+		 * wait forever (apply no timeout).
+		 */
 		static final int PESSIMISTIC_WAIT_FOREVER = -1;
 
 		/**
@@ -1073,8 +1083,19 @@ public interface Session extends SharedSessionContract {
 		 */
 		LockRequest setScope(boolean scope);
 
-		void lock(String entityName, Object object) throws HibernateException;
+		/**
+		 * Perform the requested locking.
+		 *
+		 * @param entityName The name of the entity to lock
+		 * @param object The instance of the entity to lock
+		 */
+		void lock(String entityName, Object object);
 
-		public void lock(Object object) throws HibernateException;
+		/**
+		 * Perform the requested locking.
+		 *
+		 * @param object The instance of the entity to lock
+		 */
+		void lock(Object object);
 	}
 }

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

@@ -39,7 +39,7 @@ public interface SessionBuilder {
 	public Session openSession();
 
 	/**
-	 * Adds a specific interceptor to the session options
+	 * Adds a specific interceptor to the session options.
 	 *
 	 * @param interceptor The interceptor to use.
 	 *
@@ -61,7 +61,7 @@ public interface SessionBuilder {
 	public SessionBuilder noInterceptor();
 
 	/**
-	 * Adds a specific connection to the session options
+	 * Adds a specific connection to the session options.
 	 *
 	 * @param connection The connection to use.
 	 *
@@ -70,7 +70,7 @@ public interface SessionBuilder {
 	public SessionBuilder connection(Connection connection);
 
 	/**
-	 * Use a specific connection release mode for these session options
+	 * Use a specific connection release mode for these session options.
 	 *
 	 * @param connectionReleaseMode The connection release mode to use.
 	 *
@@ -79,7 +79,7 @@ public interface SessionBuilder {
 	public SessionBuilder connectionReleaseMode(ConnectionReleaseMode connectionReleaseMode);
 
 	/**
-	 * Should the session built automatically join in any ongoing JTA transactions
+	 * Should the session built automatically join in any ongoing JTA transactions.
 	 *
 	 * @param autoJoinTransactions Should JTA transactions be automatically joined
 	 *
@@ -88,7 +88,7 @@ public interface SessionBuilder {
 	public SessionBuilder autoJoinTransactions(boolean autoJoinTransactions);
 
 	/**
-	 * Should the session be automatically closed after transaction completion
+	 * Should the session be automatically closed after transaction completion.
 	 *
 	 * @param autoClose Should the session be automatically closed
 	 *

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

@@ -54,13 +54,37 @@ import org.hibernate.stat.Statistics;
  * @author Steve Ebersole
  */
 public interface SessionFactory extends Referenceable, Serializable {
-
+	/**
+	 * Aggregator of special options used to build the SessionFactory.
+	 */
 	public interface SessionFactoryOptions {
+		/**
+		 * The service registry to use in building the factory.
+		 *
+		 * @return The service registry to use.
+		 */
 		public StandardServiceRegistry getServiceRegistry();
+
+		/**
+		 * Get the interceptor to use by default for all sessions opened from this factory.
+		 *
+		 * @return The interceptor to use factory wide.  May be {@code null}
+		 */
 		public Interceptor getInterceptor();
+
+		/**
+		 * Get the delegate for handling entity-not-found exception conditions.
+		 *
+		 * @return The specific EntityNotFoundDelegate to use,  May be {@code null}
+		 */
 		public EntityNotFoundDelegate getEntityNotFoundDelegate();
 	}
 
+	/**
+	 * Get the special options used to build the factory.
+	 *
+	 * @return The special options used to build the factory.
+	 */
 	public SessionFactoryOptions getSessionFactoryOptions();
 
 	/**
@@ -172,7 +196,7 @@ public interface SessionFactory extends Referenceable, Serializable {
 	public Map<String,ClassMetadata> getAllClassMetadata();
 
 	/**
-	 * Get the {@link CollectionMetadata} for all mapped collections
+	 * Get the {@link CollectionMetadata} for all mapped collections.
 	 *
 	 * @return a map from <tt>String</tt> to <tt>CollectionMetadata</tt>
 	 *
@@ -372,7 +396,7 @@ public interface SessionFactory extends Referenceable, Serializable {
 	public boolean containsFetchProfileDefinition(String name);
 
 	/**
-	 * Retrieve this factory's {@link TypeHelper}
+	 * Retrieve this factory's {@link TypeHelper}.
 	 *
 	 * @return The factory's {@link TypeHelper}
 	 */

hibernate-core/src/main/java/org/hibernate/SessionFactoryObserver.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;
 
 /**

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

@@ -26,41 +26,41 @@ package org.hibernate;
 import java.sql.Connection;
 
 /**
- * Specialized {@link SessionBuilder} with access to stuff from another session
+ * Specialized {@link SessionBuilder} with access to stuff from another session.
  *
  * @author Steve Ebersole
  */
 public interface SharedSessionBuilder extends SessionBuilder {
 	/**
-	 * Signifies the interceptor from the original session should be used to create the new session
+	 * Signifies the interceptor from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public SharedSessionBuilder interceptor();
 
 	/**
-	 * Signifies that the connection from the original session should be used to create the new session
+	 * Signifies that the connection from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public SharedSessionBuilder connection();
 
 	/**
-	 * Signifies that the connection release mode from the original session should be used to create the new session
+	 * Signifies that the connection release mode from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public SharedSessionBuilder connectionReleaseMode();
 
 	/**
-	 * Signifies that the autoJoinTransaction flag from the original session should be used to create the new session
+	 * Signifies that the autoJoinTransaction flag from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public SharedSessionBuilder autoJoinTransactions();
 
 	/**
-	 * Signifies that the autoClose flag from the original session should be used to create the new session
+	 * Signifies that the autoClose flag from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 *
@@ -71,14 +71,14 @@ public interface SharedSessionBuilder extends SessionBuilder {
 	public SharedSessionBuilder autoClose();
 
 	/**
-	 * Signifies that the flushBeforeCompletion flag from the original session should be used to create the new session
+	 * Signifies that the flushBeforeCompletion flag from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	public SharedSessionBuilder flushBeforeCompletion();
 
 	/**
-	 * Signifies that the transaction context from the original session should be used to create the new session
+	 * Signifies that the transaction context from the original session should be used to create the new session.
 	 *
 	 * @return {@code this}, for method chaining
 	 */

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

@@ -28,7 +28,7 @@ import java.io.Serializable;
 import org.hibernate.procedure.ProcedureCall;
 
 /**
- * Contract methods shared between {@link Session} and {@link StatelessSession}
+ * Contract methods shared between {@link Session} and {@link StatelessSession}.
  * 
  * @author Steve Ebersole
  */
@@ -107,7 +107,7 @@ public interface SharedSessionContract extends Serializable {
 	public ProcedureCall createStoredProcedureCall(String procedureName, Class... resultClasses);
 
 	/**
-	 * Creates a call to a stored procedure with specific result set entity mappings
+	 * Creates a call to a stored procedure with specific result set entity mappings.
 	 *
 	 * @param procedureName The name of the procedure.
 	 * @param resultSetMappings The explicit result set mapping(s) to use for mapping the results
@@ -117,7 +117,7 @@ public interface SharedSessionContract extends Serializable {
 	public ProcedureCall createStoredProcedureCall(String procedureName, String... resultSetMappings);
 
 	/**
-	 * Create {@link Criteria} instance for the given class (entity or subclasses/implementors)
+	 * Create {@link Criteria} instance for the given class (entity or subclasses/implementors).
 	 *
 	 * @param persistentClass The class, which is an entity, or has entity subclasses/implementors
 	 *

hibernate-core/src/main/java/org/hibernate/SimpleNaturalIdLoadAccess.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/StaleObjectStateException.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,16 @@
  * 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;
 
 /**
- * A <tt>StaleStateException</tt> that carries information 
+ * A specialized StaleStateException that carries information about the particular entity
- * about a particular entity instance that was the source
+ * instance that was the source of the failure.
- * of the failure.
  *
  * @author Gavin King
  */
@@ -38,9 +37,15 @@ public class StaleObjectStateException extends StaleStateException {
 	private final String entityName;
 	private final Serializable identifier;
 
-	public StaleObjectStateException(String persistentClass, Serializable identifier) {
+	/**
+	 * Constructs a StaleObjectStateException using the supplied information
+	 *
+	 * @param entityName The name of the entity
+	 * @param identifier The identifier of the entity
+	 */
+	public StaleObjectStateException(String entityName, Serializable identifier) {
 		super("Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect)");
-		this.entityName = persistentClass;
+		this.entityName = entityName;
 		this.identifier = identifier;
 	}
 
@@ -53,8 +58,7 @@ public class StaleObjectStateException extends StaleStateException {
 	}
 
 	public String getMessage() {
-		return super.getMessage() + ": " +
+		return super.getMessage() + " : " + MessageHelper.infoString( entityName, identifier );
-			MessageHelper.infoString(entityName, identifier);
 	}
 
 }

hibernate-core/src/main/java/org/hibernate/StaleStateException.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,26 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
- * Thrown when a version number or timestamp check failed, indicating that the
+ * Thrown when a version number or timestamp check failed, indicating that the Session contained
- * <tt>Session</tt> contained stale data (when using long transactions
+ * stale data (when using long transactions with versioning). Also occurs if we try delete or update
- * with versioning). Also occurs if we try delete or update a row that does
+ * a row that does not exist.
- * not exist.<br>
+ *
- * <br>
+ * Note that this exception often indicates that the user failed to specify the correct
- * Note that this exception often indicates that the user failed to specify the
+ * {@code unsaved-value} strategy for an entity
- * correct <tt>unsaved-value</tt> strategy for a class!
  *
- * @see StaleObjectStateException
  * @author Gavin King
  */
 public class StaleStateException extends HibernateException {
-
+	/**
-	public StaleStateException(String s) {
+	 * Constructs a StaleStateException using the supplied message.
-		super(s);
+	 *
+	 * @param message The message explaining the exception condition
+	 */
+	public StaleStateException(String message) {
+		super(message);
 	}
 }

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

@@ -52,6 +52,8 @@ public interface StatelessSession extends SharedSessionContract {
 	 * Insert a row.
 	 *
 	 * @param entity a new transient instance
+	 *
+	 * @return The identifier of the inserted entity
 	 */
 	public Serializable insert(Object entity);
 
@@ -60,6 +62,7 @@ public interface StatelessSession extends SharedSessionContract {
 	 *
 	 * @param entityName The entityName for the entity to be inserted
 	 * @param entity a new transient instance
+	 *
 	 * @return the identifier of the instance
 	 */
 	public Serializable insert(String entityName, Object entity);
@@ -97,6 +100,9 @@ public interface StatelessSession extends SharedSessionContract {
 	/**
 	 * Retrieve a row.
 	 *
+	 * @param entityName The name of the entity to retrieve
+	 * @param id The id of the entity to retrieve
+	 *
 	 * @return a detached entity instance
 	 */
 	public Object get(String entityName, Serializable id);
@@ -104,6 +110,9 @@ public interface StatelessSession extends SharedSessionContract {
 	/**
 	 * Retrieve a row.
 	 *
+	 * @param entityClass The class of the entity to retrieve
+	 * @param id The id of the entity to retrieve
+	 *
 	 * @return a detached entity instance
 	 */
 	public Object get(Class entityClass, Serializable id);
@@ -111,6 +120,10 @@ public interface StatelessSession extends SharedSessionContract {
 	/**
 	 * Retrieve a row, obtaining the specified lock mode.
 	 *
+	 * @param entityName The name of the entity to retrieve
+	 * @param id The id of the entity to retrieve
+	 * @param lockMode The lock mode to apply to the entity
+	 *
 	 * @return a detached entity instance
 	 */
 	public Object get(String entityName, Serializable id, LockMode lockMode);
@@ -118,6 +131,10 @@ public interface StatelessSession extends SharedSessionContract {
 	/**
 	 * Retrieve a row, obtaining the specified lock mode.
 	 *
+	 * @param entityClass The class of the entity to retrieve
+	 * @param id The id of the entity to retrieve
+	 * @param lockMode The lock mode to apply to the entity
+	 *
 	 * @return a detached entity instance
 	 */
 	public Object get(Class entityClass, Serializable id, LockMode lockMode);
@@ -164,6 +181,8 @@ public interface StatelessSession extends SharedSessionContract {
 	 * application should not close the connection.
 	 *
 	 * @deprecated just missed when deprecating same method from {@link Session}
+	 *
+	 * @return The connection associated with this stateless session
 	 */
 	@Deprecated
 	public Connection connection();

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

@@ -39,7 +39,7 @@ public interface StatelessSessionBuilder {
 	public StatelessSession openStatelessSession();
 
 	/**
-	 * Adds a specific connection to the session options
+	 * Adds a specific connection to the session options.
 	 *
 	 * @param connection The connection to use.
 	 *

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

@@ -26,26 +26,30 @@ package org.hibernate;
 import java.util.Collection;
 
 /**
+ * A unifying interface for queries which can define tables (query spaces) to synchronize on.
+ *
+ * These query spaces affect the process of auto-flushing by determining which entities will be
+ * processed by auto-flush based on the table to which those entities are mapped and which are
+ * determined to have pending state changes.
+ *
+ * In a similar manner, these query spaces also affect how query result caching can recognize invalidated results.
+ *
  * @author Steve Ebersole
  */
 public interface SynchronizeableQuery {
 	/**
-	 * Obtain the list of query spaces (table names) the query is synchronized on.  These spaces affect the process
+	 * Obtain the list of query spaces the query is synchronized on.
-	 * of auto-flushing by determining which entities will be processed by auto-flush based on the table to
-	 * which those entities are mapped and which are determined to have pending state changes.
 	 *
 	 * @return The list of query spaces upon which the query is synchronized.
 	 */
 	public Collection<String> getSynchronizedQuerySpaces();
 
 	/**
-	 * Adds a query space (table name) for (a) auto-flush checking and (b) query result cache invalidation checking
+	 * Adds a query space.
 	 *
 	 * @param querySpace The query space to be auto-flushed for this query.
 	 *
-	 * @return this, for method chaining
+	 * @return {@code this}, for method chaining
-	 *
-	 * @see #getSynchronizedQuerySpaces()
 	 */
 	public SynchronizeableQuery addSynchronizedQuerySpace(String querySpace);
 
@@ -55,11 +59,9 @@ public interface SynchronizeableQuery {
 	 *
 	 * @param entityName The name of the entity upon whose defined query spaces we should additionally synchronize.
 	 *
-	 * @return this, for method chaining
+	 * @return {@code this}, for method chaining
 	 *
 	 * @throws MappingException Indicates the given name could not be resolved as an entity
-	 *
-	 * @see #getSynchronizedQuerySpaces()
 	 */
 	public SynchronizeableQuery addSynchronizedEntityName(String entityName) throws MappingException;
 
@@ -69,11 +71,9 @@ public interface SynchronizeableQuery {
 	 *
 	 * @param entityClass The class of the entity upon whose defined query spaces we should additionally synchronize.
 	 *
-	 * @return this, for method chaining
+	 * @return {@code this}, for method chaining
 	 *
 	 * @throws MappingException Indicates the given class could not be resolved as an entity
-	 *
-	 * @see #getSynchronizedQuerySpaces()
 	 */
 	public SynchronizeableQuery addSynchronizedEntityClass(Class entityClass) throws MappingException;
 }

hibernate-core/src/main/java/org/hibernate/TransactionException.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,25 +20,31 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
 
-
 /**
  * Indicates that a transaction could not be begun, committed
  * or rolled back.
  *
- * @see Transaction
  * @author Anton van Straaten
  */
-
 public class TransactionException extends HibernateException {
-
+	/**
-	public TransactionException(String message, Throwable root) {
+	 * Constructs a TransactionException using the specified information.
-		super(message,root);
+	 *
+	 * @param message The message explaining the exception condition
+	 * @param cause The underlying cause
+	 */
+	public TransactionException(String message, Throwable cause) {
+		super(message,cause);
 	}
 
+	/**
+	 * Constructs a TransactionException using the specified information.
+	 *
+	 * @param message The message explaining the exception condition
+	 */
 	public TransactionException(String message) {
 		super(message);
 	}

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

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

@@ -82,18 +82,9 @@ public class TransientPropertyValueException extends TransientObjectException {
 		return propertyName;
 	}
 
-
-	/**
-	 * Return the exception message.
-	 * @return the exception message.
-	 */
 	@Override
 	public String getMessage() {
-		return new StringBuilder( super.getMessage() )
+		return super.getMessage() + " : "
-				.append( ": " )
+				+ StringHelper.qualify( propertyOwnerEntityName, propertyName ) + " -> " + transientEntityName;
-				.append( StringHelper.qualify( propertyOwnerEntityName, propertyName ) )
-				.append( " -> " )
-				.append( transientEntityName )
-				.toString();
 	}
 }

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

@@ -107,5 +107,13 @@ public interface TypeHelper {
 	 */
 	public Type custom(Class userTypeClass, Properties properties);
 
+	/**
+	 * Retrieve the type representing an ANY mapping.
+	 *
+	 * @param metaType The meta type for the ANY
+	 * @param identifierType The identifier type for the ANY
+	 *
+	 * @return The type, or null
+	 */
 	public Type any(Type metaType, Type identifierType);
 }

hibernate-core/src/main/java/org/hibernate/TypeMismatchException.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,21 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
-package org.hibernate;
+package org.hibernate;
-
 
 /**
- * Used when a user provided type does not match the expected one
+ * Used when a user provided type does not match the expected one.
  *
  * @author Emmanuel Bernard
  */
 public class TypeMismatchException extends HibernateException {
-	public TypeMismatchException(Throwable root) {
+	/**
-		super( root );
+	 * Constructs a TypeMismatchException using the supplied message.
-	}
+	 *
-
+	 * @param message The message explaining the exception condition
-	public TypeMismatchException(String s) {
+	 */
-		super( s );
+	public TypeMismatchException(String message) {
-	}
+		super( message );
-
-	public TypeMismatchException(String string, Throwable root) {
-		super( string, root );
 	}
 }

hibernate-core/src/main/java/org/hibernate/UnknownProfileException.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) 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;
 
-
 /**
  * Used to indicate a request against an unknown profile name.
  *
@@ -33,6 +31,11 @@ package org.hibernate;
 public class UnknownProfileException extends HibernateException {
 	private final String name;
 
+	/**
+	 * Constructs an UnknownProfileException for the given name.
+	 *
+	 * @param name The profile name that was unknown.
+	 */
 	public UnknownProfileException(String name) {
 		super( "Unknow fetch profile [" + name + "]" );
 		this.name = name;

hibernate-core/src/main/java/org/hibernate/UnresolvableObjectException.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) 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;
 
 import org.hibernate.pretty.MessageHelper;
@@ -34,34 +34,53 @@ import org.hibernate.pretty.MessageHelper;
  * @author Gavin King
  */
 public class UnresolvableObjectException extends HibernateException {
-
 	private final Serializable identifier;
 	private final String entityName;
 
-	public UnresolvableObjectException(Serializable identifier, String clazz) {
+	/**
-		this("No row with the given identifier exists", identifier, clazz);
+	 * Constructs an UnresolvableObjectException using the specified information.
+	 *
+	 * @param identifier The identifier of the entity which could not be resolved
+	 * @param entityName The name of the entity which could not be resolved
+	 */
+	public UnresolvableObjectException(Serializable identifier, String entityName) {
+		this( "No row with the given identifier exists", identifier, entityName );
 	}
-	UnresolvableObjectException(String message, Serializable identifier, String clazz) {
+
+	protected UnresolvableObjectException(String message, Serializable identifier, String clazz) {
 		super(message);
 		this.identifier = identifier;
 		this.entityName = clazz;
 	}
-	public Serializable getIdentifier() {
+
-		return identifier;
+	/**
+	 * Factory method for building and throwing an UnresolvableObjectException if the entity is null.
+	 *
+	 * @param entity The entity to check for nullness
+	 * @param identifier The identifier of the entity
+	 * @param entityName The name of the entity
+	 *
+	 * @throws UnresolvableObjectException Thrown if entity is null
+	 */
+	public static void throwIfNull(Object entity, Serializable identifier, String entityName)
+			throws UnresolvableObjectException {
+		if ( entity == null ) {
+			throw new UnresolvableObjectException( identifier, entityName );
+		}
 	}
 
-	public String getMessage() {
+	public Serializable getIdentifier() {
-		return super.getMessage() + ": " +
+		return identifier;
-			MessageHelper.infoString(entityName, identifier);
 	}
 
 	public String getEntityName() {
 		return entityName;
 	}
 
-	public static void throwIfNull(Object o, Serializable id, String clazz)
+	@Override
-	throws UnresolvableObjectException {
+	public String getMessage() {
-		if (o==null) throw new UnresolvableObjectException(id, clazz);
+		return super.getMessage() + ": " +
+			MessageHelper.infoString(entityName, identifier);
 	}
 
 }

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

@@ -33,14 +33,33 @@ import org.hibernate.internal.CoreMessageLogger;
  * @author Steve Ebersole
  */
 public class Version {
+	private Version() {
+	}
+
+	/**
+	 * Access to the Hibernate version.
+	 *
+	 * IMPL NOTE : Real value is injected by the build.
+	 *
+	 * @return The Hibernate version
+	 */
 	public static String getVersionString() {
 		return "[WORKING]";
 	}
 
+	/**
+	 * Logs the Hibernate version (using {@link #getVersionString()}) to the logging system.
+	 */
 	public static void logVersion() {
 		Logger.getMessageLogger( CoreMessageLogger.class, Version.class.getName() ).version( getVersionString() );
 	}
 
+	/**
+	 * Prints the Hibernate version (using {@link #getVersionString()}) to SYSOUT.  Defined as the main-class in
+	 * the hibernate-core jar
+	 *
+	 * @param args n/a
+	 */
 	public static void main(String[] args) {
 		System.out.println( "Hibernate Core {" + getVersionString() + "}" );
 	}

hibernate-core/src/main/java/org/hibernate/WrongClassException.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,50 +20,47 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 
 /**
- * Thrown when <tt>Session.load()</tt> selects a row with
+ * Thrown when loading an entity (by identifier) results in a value that cannot be treated as the subclass
- * the given primary key (identifier value) but the row's
+ * type requested by the caller.
- * discriminator value specifies a subclass that is not
- * assignable to the class requested by the user.
  *
  * @author Gavin King
  */
 public class WrongClassException extends HibernateException {
-
 	private final Serializable identifier;
 	private final String entityName;
 
-	public WrongClassException(String msg, Serializable identifier, String clazz) {
+	/**
-		super(msg);
+	 * Constructs a WrongClassException using the supplied information.
+	 *
+	 * @param message A message explaining the exception condition
+	 * @param identifier The identifier of the entity
+	 * @param entityName The entity-type requested
+	 */
+	public WrongClassException(String message, Serializable identifier, String entityName) {
+		super(
+				String.format(
+						"Object [id=%s] was not of the specified subclass [%s] : %s",
+						identifier,
+						entityName,
+						message
+				)
+		);
 		this.identifier = identifier;
-		this.entityName = clazz;
+		this.entityName = entityName;
-	}
-	public Serializable getIdentifier() {
-		return identifier;
-	}
-
-	public String getMessage() {
-		return "Object with id: " +
-			identifier +
-			" was not of the specified subclass: " +
-			entityName +
-			" (" + super.getMessage() + ")" ;
 	}
 
 	public String getEntityName() {
 		return entityName;
 	}
 
+	public Serializable getIdentifier() {
+		return identifier;
+	}
 }
 
-
-
-
-
-
-

hibernate-core/src/main/java/org/hibernate/hql/internal/ast/util/ASTAppender.java

@@ -36,16 +36,28 @@ public class ASTAppender {
 	private AST last;
 	private ASTFactory factory;
 
+	/**
+	 * Builds an appender using the given factory and parent
+	 *
+	 * @param factory The AST factory
+	 * @param parent The AST parent
+	 */
 	public ASTAppender(ASTFactory factory, AST parent) {
-		this( parent );
 		this.factory = factory;
-	}
-
-	public ASTAppender(AST parent) {
 		this.parent = parent;
 		this.last = ASTUtil.getLastChild( parent );
 	}
 
+	/**
+	 * Append a new child to parent using the given node type and text, but only if the
+	 * text is non-empty
+	 *
+	 * @param type The node type
+	 * @param text The node text
+	 * @param appendIfEmpty Should we do the append if the text is empty?
+	 *
+	 * @return The generated AST node; may return {@code null}
+	 */
 	public AST append(int type, String text, boolean appendIfEmpty) {
 		if ( text != null && ( appendIfEmpty || text.length() > 0 ) ) {
 			return append( factory.create( type, text ) );
@@ -55,6 +67,13 @@ public class ASTAppender {
 		}
 	}
 
+	/**
+	 * Append the given AST node as a child of parent.
+	 *
+	 * @param child The child to append
+	 *
+	 * @return Returns what was passed in.
+	 */
 	public AST append(AST child) {
 		if ( last == null ) {
 			parent.setFirstChild( child );

hibernate-core/src/main/java/org/hibernate/hql/internal/ast/util/ASTIterator.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.hql.internal.ast.util;
+
 import java.util.Iterator;
 import java.util.LinkedList;
 
@@ -37,23 +37,37 @@ public class ASTIterator implements Iterator {
 	private AST next, current;
 	private LinkedList parents = new LinkedList();
 
-	public void remove() {
+	/**
-		throw new UnsupportedOperationException( "remove() is not supported" );
+	 * Constructs an Iterator for depth-first iteration of an AST
-	}
+	 *
-
+	 * @param tree THe tree whose nodes are to be iterated
-	public boolean hasNext() {
+	 */
-		return next != null;
-	}
-
-	public Object next() {
-		return nextNode();
-	}
-
 	public ASTIterator(AST tree) {
 		next = tree;
 		down();
 	}
 
+	@Override
+	public void remove() {
+		throw new UnsupportedOperationException( "remove() is not supported" );
+	}
+
+	@Override
+	public boolean hasNext() {
+		return next != null;
+	}
+
+	@Override
+	public Object next() {
+		return nextNode();
+	}
+
+
+	/**
+	 * Get the next node to be returned from iteration.
+	 *
+	 * @return The next node.
+	 */
 	public AST nextNode() {
 		current = next;
 		if ( next != null ) {

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

@@ -29,7 +29,6 @@ import java.sql.Blob;
 import java.sql.Clob;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
-import java.sql.SQLException;
 import java.util.Calendar;
 import java.util.Date;
 import java.util.Locale;
@@ -48,14 +47,16 @@ import org.hibernate.type.StandardBasicTypes;
 import org.hibernate.type.Type;
 
 /**
- * Implementation of the <tt>ScrollableResults</tt> interface
+ * Base implementation of the ScrollableResults interface.
  *
  * @author Steve Ebersole
  */
 public abstract class AbstractScrollableResults implements ScrollableResults {
 
-    private static final CoreMessageLogger LOG = Logger.getMessageLogger(CoreMessageLogger.class,
+    private static final CoreMessageLogger LOG = Logger.getMessageLogger(
-                                                                       AbstractScrollableResults.class.getName());
+			CoreMessageLogger.class,
+			AbstractScrollableResults.class.getName()
+	);
 
 	private final ResultSet resultSet;
 	private final PreparedStatement ps;
@@ -65,14 +66,14 @@ public abstract class AbstractScrollableResults implements ScrollableResults {
 	private final Type[] types;
 	private HolderInstantiator holderInstantiator;
 
-	public AbstractScrollableResults(
+	protected AbstractScrollableResults(
 	        ResultSet rs,
 	        PreparedStatement ps,
 	        SessionImplementor sess,
 			Loader loader,
 			QueryParameters queryParameters,
 	        Type[] types,
-	        HolderInstantiator holderInstantiator) throws MappingException {
+	        HolderInstantiator holderInstantiator) {
 		this.resultSet=rs;
 		this.ps=ps;
 		this.session = sess;
@@ -114,7 +115,8 @@ public abstract class AbstractScrollableResults implements ScrollableResults {
 		return holderInstantiator;
 	}
 
-	public final void close() throws HibernateException {
+	@Override
+	public final void close() {
 		// not absolutely necessary, but does help with aggressive release
 		//session.getJDBCContext().getConnectionManager().closeQueryStatement( ps, resultSet );
 		session.getTransactionCoordinator().getJdbcCoordinator().release( ps );
@@ -129,10 +131,12 @@ public abstract class AbstractScrollableResults implements ScrollableResults {
 		}
 	}
 
+	@Override
 	public final Object[] get() throws HibernateException {
 		return getCurrentRow();
 	}
 
+	@Override
 	public final Object get(int col) throws HibernateException {
 		return getCurrentRow()[col];
 	}
@@ -179,86 +183,102 @@ public abstract class AbstractScrollableResults implements ScrollableResults {
 		}
 	}
 
+	@Override
 	public final BigDecimal getBigDecimal(int col) throws HibernateException {
 		return (BigDecimal) getFinal(col, StandardBasicTypes.BIG_DECIMAL);
 	}
 
+	@Override
 	public final BigInteger getBigInteger(int col) throws HibernateException {
 		return (BigInteger) getFinal(col, StandardBasicTypes.BIG_INTEGER);
 	}
 
+	@Override
 	public final byte[] getBinary(int col) throws HibernateException {
 		return (byte[]) getFinal(col, StandardBasicTypes.BINARY);
 	}
 
+	@Override
 	public final String getText(int col) throws HibernateException {
 		return (String) getFinal(col, StandardBasicTypes.TEXT);
 	}
 
+	@Override
 	public final Blob getBlob(int col) throws HibernateException {
 		return (Blob) getNonFinal(col, StandardBasicTypes.BLOB);
 	}
 
+	@Override
 	public final Clob getClob(int col) throws HibernateException {
 		return (Clob) getNonFinal(col, StandardBasicTypes.CLOB);
 	}
 
+	@Override
 	public final Boolean getBoolean(int col) throws HibernateException {
 		return (Boolean) getFinal(col, StandardBasicTypes.BOOLEAN);
 	}
 
+	@Override
 	public final Byte getByte(int col) throws HibernateException {
 		return (Byte) getFinal(col, StandardBasicTypes.BYTE);
 	}
 
+	@Override
 	public final Character getCharacter(int col) throws HibernateException {
 		return (Character) getFinal(col, StandardBasicTypes.CHARACTER);
 	}
 
+	@Override
 	public final Date getDate(int col) throws HibernateException {
 		return (Date) getNonFinal(col, StandardBasicTypes.TIMESTAMP);
 	}
 
+	@Override
 	public final Calendar getCalendar(int col) throws HibernateException {
 		return (Calendar) getNonFinal(col, StandardBasicTypes.CALENDAR);
 	}
 
+	@Override
 	public final Double getDouble(int col) throws HibernateException {
 		return (Double) getFinal(col, StandardBasicTypes.DOUBLE);
 	}
 
+	@Override
 	public final Float getFloat(int col) throws HibernateException {
 		return (Float) getFinal(col, StandardBasicTypes.FLOAT);
 	}
 
+	@Override
 	public final Integer getInteger(int col) throws HibernateException {
 		return (Integer) getFinal(col, StandardBasicTypes.INTEGER);
 	}
 
+	@Override
 	public final Long getLong(int col) throws HibernateException {
 		return (Long) getFinal(col, StandardBasicTypes.LONG);
 	}
 
+	@Override
 	public final Short getShort(int col) throws HibernateException {
 		return (Short) getFinal(col, StandardBasicTypes.SHORT);
 	}
 
+	@Override
 	public final String getString(int col) throws HibernateException {
 		return (String) getFinal(col, StandardBasicTypes.STRING);
 	}
 
+	@Override
 	public final Locale getLocale(int col) throws HibernateException {
 		return (Locale) getFinal(col, StandardBasicTypes.LOCALE);
 	}
 
-	/*public final Currency getCurrency(int col) throws HibernateException {
+	@Override
-		return (Currency) get(col);
-	}*/
-
 	public final TimeZone getTimeZone(int col) throws HibernateException {
 		return (TimeZone) getNonFinal(col, StandardBasicTypes.TIMEZONE);
 	}
 
+	@Override
 	public final Type getType(int i) {
 		return types[i];
 	}

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

@@ -22,12 +22,12 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.internal;
+
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
 import org.hibernate.HibernateException;
-import org.hibernate.MappingException;
 import org.hibernate.engine.spi.QueryParameters;
 import org.hibernate.engine.spi.SessionImplementor;
 import org.hibernate.hql.internal.HolderInstantiator;
@@ -40,7 +40,21 @@ import org.hibernate.type.Type;
  * @author Steve Ebersole
  */
 public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
+	private Object[] currentRow;
+	private int currentPosition;
+	private Integer maxPosition;
 
+	/**
+	 * Constructs a FetchingScrollableResultsImpl.
+	 *
+	 * @param rs The scrollable result set
+	 * @param ps The prepared statement used to obtain the result set
+	 * @param sess The originating session
+	 * @param loader The loader
+	 * @param queryParameters query parameters
+	 * @param types The result types
+	 * @param holderInstantiator Ugh
+	 */
 	public FetchingScrollableResultsImpl(
 	        ResultSet rs,
 	        PreparedStatement ps,
@@ -48,25 +62,17 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 	        Loader loader,
 	        QueryParameters queryParameters,
 	        Type[] types,
-	        HolderInstantiator holderInstantiator) throws MappingException {
+	        HolderInstantiator holderInstantiator) {
 		super( rs, ps, sess, loader, queryParameters, types, holderInstantiator );
 	}
 
-	private Object[] currentRow = null;
-	private int currentPosition = 0;
-	private Integer maxPosition = null;
-
 	@Override
     protected Object[] getCurrentRow() {
 		return currentRow;
 	}
 
-	/**
+	@Override
-	 * Advance to the next result
+	public boolean next() {
-	 *
-	 * @return <tt>true</tt> if there is another result
-	 */
-	public boolean next() throws HibernateException {
 		if ( maxPosition != null && maxPosition <= currentPosition ) {
 			currentRow = null;
 			currentPosition = maxPosition + 1;
@@ -79,7 +85,7 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 			return false;
 		}
 
-		Object row = getLoader().loadSequentialRowsForward(
+		final Object row = getLoader().loadSequentialRowsForward(
 				getResultSet(),
 				getSession(),
 				getQueryParameters(),
@@ -87,7 +93,7 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		);
 
 
-		boolean afterLast;
+		final boolean afterLast;
 		try {
 			afterLast = getResultSet().isAfterLast();
 		}
@@ -95,7 +101,7 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 			        e,
 			        "exception calling isAfterLast()"
-				);
+			);
 		}
 
 		currentPosition++;
@@ -113,19 +119,15 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		return true;
 	}
 
-	/**
+	@Override
-	 * Retreat to the previous result
+	public boolean previous() {
-	 *
-	 * @return <tt>true</tt> if there is a previous result
-	 */
-	public boolean previous() throws HibernateException {
 		if ( currentPosition <= 1 ) {
 			currentPosition = 0;
 			currentRow = null;
 			return false;
 		}
 
-		Object loadResult = getLoader().loadSequentialRowsReverse(
+		final Object loadResult = getLoader().loadSequentialRowsReverse(
 				getResultSet(),
 				getSession(),
 				getQueryParameters(),
@@ -139,17 +141,10 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		afterScrollOperation();
 
 		return true;
-
 	}
 
-	/**
+	@Override
-	 * Scroll an arbitrary number of locations
+	public boolean scroll(int positions) {
-	 *
-	 * @param positions a positive (forward) or negative (backward) number of rows
-	 *
-	 * @return <tt>true</tt> if there is a result at the new location
-	 */
-	public boolean scroll(int positions) throws HibernateException {
 		boolean more = false;
 		if ( positions > 0 ) {
 			// scroll ahead
@@ -178,12 +173,8 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		return more;
 	}
 
-	/**
+	@Override
-	 * Go to the last result
+	public boolean last() {
-	 *
-	 * @return <tt>true</tt> if there are any results
-	 */
-	public boolean last() throws HibernateException {
 		boolean more = false;
 		if ( maxPosition != null ) {
 			if ( currentPosition > maxPosition ) {
@@ -209,7 +200,7 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 				throw getSession().getFactory().getSQLExceptionHelper().convert(
 						e,
 						"exception calling isAfterLast()"
-					);
+				);
 			}
 		}
 
@@ -218,12 +209,8 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		return more;
 	}
 
-	/**
+	@Override
-	 * Go to the first result
+	public boolean first() {
-	 *
-	 * @return <tt>true</tt> if there are any results
-	 */
-	public boolean first() throws HibernateException {
 		beforeFirst();
 		boolean more = next();
 
@@ -232,10 +219,8 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		return more;
 	}
 
-	/**
+	@Override
-	 * Go to a location just before first result (this is the initial location)
+	public void beforeFirst() {
-	 */
-	public void beforeFirst() throws HibernateException {
 		try {
 			getResultSet().beforeFirst();
 		}
@@ -243,16 +228,14 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 			        e,
 			        "exception calling beforeFirst()"
-				);
+			);
 		}
 		currentRow = null;
 		currentPosition = 0;
 	}
 
-	/**
+	@Override
-	 * Go to a location just after the last result
+	public void afterLast() {
-	 */
-	public void afterLast() throws HibernateException {
 		// TODO : not sure the best way to handle this.
 		// The non-performant way :
 		last();
@@ -260,52 +243,23 @@ public class FetchingScrollableResultsImpl extends AbstractScrollableResults {
 		afterScrollOperation();
 	}
 
-	/**
+	@Override
-	 * Is this the first result?
+	public boolean isFirst() {
-	 *
-	 * @return <tt>true</tt> if this is the first row of results
-	 *
-	 * @throws org.hibernate.HibernateException
-	 */
-	public boolean isFirst() throws HibernateException {
 		return currentPosition == 1;
 	}
 
-	/**
+	@Override
-	 * Is this the last result?
+	public boolean isLast() {
-	 *
+		return maxPosition != null && currentPosition == maxPosition;
-	 * @return <tt>true</tt> if this is the last row of results
-	 *
-	 * @throws org.hibernate.HibernateException
-	 */
-	public boolean isLast() throws HibernateException {
-		if ( maxPosition == null ) {
-			// we have not yet hit the last result...
-			return false;
-		}
-		else {
-			return currentPosition == maxPosition;
-		}
 	}
 
-	/**
+	@Override
-	 * Get the current location in the result set. The first row is number <tt>0</tt>, contrary to JDBC.
+	public int getRowNumber() {
-	 *
-	 * @return the row number, numbered from <tt>0</tt>, or <tt>-1</tt> if there is no current row
-	 */
-	public int getRowNumber() throws HibernateException {
 		return currentPosition;
 	}
 
-	/**
+	@Override
-	 * Set the current location in the result set, numbered from either the first row (row number <tt>0</tt>), or the last
+	public boolean setRowNumber(int rowNumber) {
-	 * row (row number <tt>-1</tt>).
-	 *
-	 * @param rowNumber the row number, numbered from the last row, in the case of a negative row number
-	 *
-	 * @return true if there is a row at that row number
-	 */
-	public boolean setRowNumber(int rowNumber) throws HibernateException {
 		if ( rowNumber == 1 ) {
 			return first();
 		}

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

@@ -22,12 +22,12 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.internal;
+
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
 import org.hibernate.HibernateException;
-import org.hibernate.MappingException;
 import org.hibernate.ScrollableResults;
 import org.hibernate.engine.spi.QueryParameters;
 import org.hibernate.engine.spi.SessionImplementor;
@@ -36,33 +36,43 @@ import org.hibernate.loader.Loader;
 import org.hibernate.type.Type;
 
 /**
- * Implementation of the <tt>ScrollableResults</tt> interface
+ * Standard ScrollableResults implementation.
+ *
  * @author Gavin King
  */
 public class ScrollableResultsImpl extends AbstractScrollableResults implements ScrollableResults {
-
 	private Object[] currentRow;
 
+	/**
+	 * Constructs a ScrollableResultsImpl using the specified information.
+	 *
+	 * @param rs The scrollable result set
+	 * @param ps The prepared statement used to obtain the result set
+	 * @param sess The originating session
+	 * @param loader The loader
+	 * @param queryParameters query parameters
+	 * @param types The result types
+	 * @param holderInstantiator Ugh
+	 */
 	public ScrollableResultsImpl(
 	        ResultSet rs,
 	        PreparedStatement ps,
 	        SessionImplementor sess,
 	        Loader loader,
 	        QueryParameters queryParameters,
-	        Type[] types, HolderInstantiator holderInstantiator) throws MappingException {
+	        Type[] types, HolderInstantiator holderInstantiator) {
 		super( rs, ps, sess, loader, queryParameters, types, holderInstantiator );
 	}
 
+	@Override
 	protected Object[] getCurrentRow() {
 		return currentRow;
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#scroll(int)
+	public boolean scroll(int i) {
-	 */
-	public boolean scroll(int i) throws HibernateException {
 		try {
-			boolean result = getResultSet().relative(i);
+			final boolean result = getResultSet().relative(i);
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -70,16 +80,14 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using scroll()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#first()
+	public boolean first() {
-	 */
-	public boolean first() throws HibernateException {
 		try {
-			boolean result = getResultSet().first();
+			final boolean result = getResultSet().first();
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -87,16 +95,14 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using first()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#last()
+	public boolean last() {
-	 */
-	public boolean last() throws HibernateException {
 		try {
-			boolean result = getResultSet().last();
+			final boolean result = getResultSet().last();
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -104,16 +110,14 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using last()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#next()
+	public boolean next() {
-	 */
-	public boolean next() throws HibernateException {
 		try {
-			boolean result = getResultSet().next();
+			final boolean result = getResultSet().next();
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -121,16 +125,14 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using next()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#previous()
+	public boolean previous() {
-	 */
-	public boolean previous() throws HibernateException {
 		try {
-			boolean result = getResultSet().previous();
+			final boolean result = getResultSet().previous();
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -138,14 +140,12 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using previous()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#afterLast()
+	public void afterLast() {
-	 */
-	public void afterLast() throws HibernateException {
 		try {
 			getResultSet().afterLast();
 		}
@@ -153,14 +153,12 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"exception calling afterLast()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#beforeFirst()
+	public void beforeFirst() {
-	 */
-	public void beforeFirst() throws HibernateException {
 		try {
 			getResultSet().beforeFirst();
 		}
@@ -168,14 +166,12 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"exception calling beforeFirst()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#isFirst()
+	public boolean isFirst() {
-	 */
-	public boolean isFirst() throws HibernateException {
 		try {
 			return getResultSet().isFirst();
 		}
@@ -183,14 +179,12 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"exception calling isFirst()"
-				);
+			);
 		}
 	}
 
-	/**
+	@Override
-	 * @see org.hibernate.ScrollableResults#isLast()
+	public boolean isLast() {
-	 */
-	public boolean isLast() throws HibernateException {
 		try {
 			return getResultSet().isLast();
 		}
@@ -198,10 +192,11 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"exception calling isLast()"
-				);
+			);
 		}
 	}
 
+	@Override
 	public int getRowNumber() throws HibernateException {
 		try {
 			return getResultSet().getRow()-1;
@@ -210,14 +205,18 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"exception calling getRow()"
-				);
+			);
 		}
 	}
 
+	@Override
 	public boolean setRowNumber(int rowNumber) throws HibernateException {
-		if (rowNumber>=0) rowNumber++;
+		if ( rowNumber >= 0 ) {
+			rowNumber++;
+		}
+
 		try {
-			boolean result = getResultSet().absolute(rowNumber);
+			final boolean result = getResultSet().absolute(rowNumber);
 			prepareCurrentRow(result);
 			return result;
 		}
@@ -225,19 +224,17 @@ public class ScrollableResultsImpl extends AbstractScrollableResults implements
 			throw getSession().getFactory().getSQLExceptionHelper().convert(
 					sqle,
 					"could not advance using absolute()"
-				);
+			);
 		}
 	}
 
-	private void prepareCurrentRow(boolean underlyingScrollSuccessful) 
+	private void prepareCurrentRow(boolean underlyingScrollSuccessful) {
-	throws HibernateException {
+		if ( !underlyingScrollSuccessful ) {
-		
-		if (!underlyingScrollSuccessful) {
 			currentRow = null;
 			return;
 		}
 
-		Object result = getLoader().loadSingleRow(
+		final Object result = getLoader().loadSingleRow(
 				getResultSet(),
 				getSession(),
 				getQueryParameters(),

hibernate-core/src/main/java/org/hibernate/package.html

@@ -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
-  ~
   -->
 
 <html>

hibernate-core/src/main/java/org/hibernate/sql/ANSICaseFragment.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,33 +20,31 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate.sql;
-import java.util.Iterator;
+
 import java.util.Map;
 
 /**
- An ANSI SQL CASE expression.
+ * An ANSI SQL CASE expression : {@code case when ... then ... end as ..}
- <br>
+ *
- <code>case when ... then ... end as ...</code>
+ * @author Gavin King
- <br>
+ * @author Simon Harris
- @author Gavin King, Simon Harris
  */
 public class ANSICaseFragment extends CaseFragment {
 
+	@Override
 	public String toFragmentString() {
 		
-		StringBuilder buf = new StringBuilder( cases.size() * 15 + 10 )
+		final StringBuilder buf = new StringBuilder( cases.size() * 15 + 10 )
 			.append("case");
 
-		Iterator iter = cases.entrySet().iterator();
+		for ( Object o : cases.entrySet() ) {
-		while ( iter.hasNext() ) {
+			Map.Entry me = (Map.Entry) o;
-			Map.Entry me = (Map.Entry) iter.next();
+			buf.append( " when " )
-			buf.append(" when ")
+					.append( me.getKey() )
-				.append( me.getKey() )
+					.append( " is not null then " )
-				.append(" is not null then ")
+					.append( me.getValue() );
-				.append( me.getValue() );
 		}
 		
 		buf.append(" end");
@@ -59,4 +57,4 @@ public class ANSICaseFragment extends CaseFragment {
 		return buf.toString();
 	}
 	
-}
+}

hibernate-core/src/main/java/org/hibernate/sql/ANSIJoinFragment.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,27 +20,45 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate.sql;
+
 import org.hibernate.AssertionFailure;
 
 /**
- * An ANSI-style join
+ * An ANSI-style join.
  *
  * @author Gavin King
  */
 public class ANSIJoinFragment extends JoinFragment {
-
 	private StringBuilder buffer = new StringBuilder();
 	private StringBuilder conditions = new StringBuilder();
 
+	/**
+	 * Adds a join, represented by the given information, to the fragment.
+	 *
+	 * @param tableName The name of the table being joined.
+	 * @param alias The alias applied to the table being joined.
+	 * @param fkColumns The columns (from the table being joined) used to define the join-restriction (the ON)
+	 * @param pkColumns The columns (from the table being joined to) used to define the join-restriction (the ON)
+	 * @param joinType The type of join to produce (INNER, etc).
+	 */
 	public void addJoin(String tableName, String alias, String[] fkColumns, String[] pkColumns, JoinType joinType) {
-		addJoin(tableName, alias, fkColumns, pkColumns, joinType, null);
+		addJoin( tableName, alias, fkColumns, pkColumns, joinType, null );
 	}
 
+	/**
+	 * Adds a join, represented by the given information, to the fragment.
+	 *
+	 * @param tableName The name of the table being joined.
+	 * @param alias The alias applied to the table being joined.
+	 * @param fkColumns The columns (from the table being joined) used to define the join-restriction (the ON)
+	 * @param pkColumns The columns (from the table being joined to) used to define the join-restriction (the ON)
+	 * @param joinType The type of join to produce (INNER, etc).
+	 * @param on Any extra join restrictions
+	 */
 	public void addJoin(String tableName, String alias, String[] fkColumns, String[] pkColumns, JoinType joinType, String on) {
-		String joinString;
+		final String joinString;
 		switch (joinType) {
 			case INNER_JOIN:
 				joinString = " inner join ";
@@ -58,7 +76,7 @@ public class ANSIJoinFragment extends JoinFragment {
 				throw new AssertionFailure("undefined join type");
 		}
 
-		buffer.append(joinString)
+		this.buffer.append(joinString)
 			.append(tableName)
 			.append(' ')
 			.append(alias)
@@ -66,74 +84,87 @@ public class ANSIJoinFragment extends JoinFragment {
 
 
 		for ( int j=0; j<fkColumns.length; j++) {
-			/*if ( fkColumns[j].indexOf('.')<1 ) {
+			this.buffer.append( fkColumns[j] )
-				throw new AssertionFailure("missing alias");
-			}*/
-			buffer.append( fkColumns[j] )
 				.append('=')
 				.append(alias)
 				.append('.')
 				.append( pkColumns[j] );
-			if ( j<fkColumns.length-1 ) buffer.append(" and ");
+			if ( j < fkColumns.length-1 ) {
+				this.buffer.append( " and " );
+			}
 		}
 
-		addCondition(buffer, on);
+		addCondition( buffer, on );
 
 	}
 
+	@Override
 	public String toFromFragmentString() {
-		return buffer.toString();
+		return this.buffer.toString();
 	}
 
+	@Override
 	public String toWhereFragmentString() {
-		return conditions.toString();
+		return this.conditions.toString();
 	}
 
+	@Override
 	public void addJoins(String fromFragment, String whereFragment) {
-		buffer.append(fromFragment);
+		this.buffer.append( fromFragment );
 		//where fragment must be empty!
 	}
 
+	@Override
 	public JoinFragment copy() {
-		ANSIJoinFragment copy = new ANSIJoinFragment();
+		final ANSIJoinFragment copy = new ANSIJoinFragment();
-		copy.buffer = new StringBuilder( buffer.toString() );
+		copy.buffer = new StringBuilder( this.buffer.toString() );
 		return copy;
 	}
 
+	/**
+	 * Adds a condition to the join fragment.  For each given column a predicate is built in the form:
+	 * {@code [alias.[column] = [condition]}
+	 *
+	 * @param alias The alias to apply to column(s)
+	 * @param columns The columns to apply restriction
+	 * @param condition The restriction condition
+	 */
 	public void addCondition(String alias, String[] columns, String condition) {
-		for ( int i=0; i<columns.length; i++ ) {
+		for ( String column : columns ) {
-			conditions.append(" and ")
+			this.conditions.append( " and " )
-				.append(alias)
+					.append( alias )
-				.append('.')
+					.append( '.' )
-				.append( columns[i] )
+					.append( column )
-				.append(condition);
+					.append( condition );
 		}
 	}
 
+	@Override
 	public void addCrossJoin(String tableName, String alias) {
-		buffer.append(", ")
+		this.buffer.append(", ")
 			.append(tableName)
 			.append(' ')
 			.append(alias);
 	}
 
+	@Override
 	public void addCondition(String alias, String[] fkColumns, String[] pkColumns) {
 		throw new UnsupportedOperationException();
 
 	}
 
+	@Override
 	public boolean addCondition(String condition) {
 		return addCondition(conditions, condition);
 	}
 
+	/**
+	 * Adds an externally built join fragment.
+	 *
+	 * @param fromFragmentString The join fragment string
+	 */
 	public void addFromFragmentString(String fromFragmentString) {
-		buffer.append(fromFragmentString);
+		this.buffer.append(fromFragmentString);
 	}
 
 }
-
-
-
-
-
-

shared/config/checkstyle/checkstyle.xml

@@ -27,9 +27,9 @@
 
     <!--
         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
+        the checks fail.
-        is just not practical given how we use the plugin.
 
+        Note also that some checks apply a warning severity, rather than error.
         The commented-out checks are ones I would ultimately like to (re)enable.
     -->
 
@@ -65,9 +65,6 @@
         <module name="MissingSwitchDefault" />
         <module name="DefaultComesLast" />
         <module name="FallThrough" />
-<!--
-        <module name="RequireThis" />
--->
         <module name="OneStatementPerLine" />
 
         <!-- Import checks : http://checkstyle.sourceforge.net/config_imports.html -->
@@ -76,6 +73,9 @@
         <module name="UnusedImports" />
 
         <!-- Javadoc checks : http://checkstyle.sourceforge.net/config_javadoc.html -->
+        <module name="JavadocPackage">
+            <property name="allowLegacy" value="true" />
+        </module>
         <module name="JavadocType">
             <property name="scope" value="public"/>
             <property name="allowUnknownTags" value="true" />
@@ -90,6 +90,7 @@
         </module>
         <module name="JavadocStyle">
             <property name="scope" value="public" />
+            <property name="checkEmptyJavadoc" value="true" />
         </module>
 
         <!-- Metric checks : http://checkstyle.sourceforge.net/config_metrics.html -->
@@ -99,10 +100,19 @@
         <module name="UpperEll" />
         <module name="ArrayTypeStyle" />
 <!--
-        <module name="FinalParameters" />
+        <module name="FinalParameters">
-        <module name="TrailingComment" />
+            <property name="severity" value="info" />
+        </module>
+-->
+        <module name="TrailingComment">
+            <property name="severity" value="warning" />
+        </module>
+<!--
+        <module name="TodoComment">
+            <property name="format" value="[Tt][Oo][Dd][Oo]"/>
+            <property name="severity" value="info" />
+        </module>
 -->
-
         <!-- Modifier checks : http://checkstyle.sourceforge.net/config_modifier.html -->
         <module name="ModifierOrder"/>