refresh javadoc for exception types

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

@@ -13,7 +13,7 @@ package org.hibernate;
  */
 public class AnnotationException extends MappingException {
 	/**
-	 * Constructs an AnnotationException using the given message and cause.
+	 * Constructs an {@code AnnotationException} using the given message and cause.
 	 *
 	 * @param msg The message explaining the reason for the exception.
 	 * @param cause The underlying cause.
@@ -23,7 +23,7 @@ public class AnnotationException extends MappingException {
 	}
 
 	/**
-	 * Constructs an AnnotationException using the given message.
+	 * Constructs an {@code AnnotationException} using the given message.
 	 *
 	 * @param msg The message explaining the reason for the exception.
 	 */

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

@@ -7,10 +7,11 @@
 package org.hibernate;
 
 /**
- * Intended to be thrown from {@link org.hibernate.classic.Lifecycle} and {@link Interceptor} callbacks.
+ * Intended to be thrown from {@link org.hibernate.classic.Lifecycle}
- * <p>
+ * and {@link Interceptor} callbacks.
- * IMPL NOTE : This is a legacy exception type from back in the day before Hibernate moved to a untyped (runtime)
+ *
- * exception strategy.
+ * @implNote This is a legacy exception type from back in the day before
+ * Hibernate moved to an unchecked exception strategy.
  *
  * @author Gavin King
  */

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

@@ -7,7 +7,8 @@
 package org.hibernate;
 
 /**
- * Raised whenever a duplicate for a certain type occurs.  Duplicate class, table, property name etc.
+ * Raised whenever a duplicate for a certain type occurs,
+ * such as a duplicate class, table, or property name.
  * 
  * @author Max Rydahl Andersen
  * @author Steve Ebersole
@@ -69,7 +70,7 @@ public class DuplicateMappingException extends MappingException {
 	private final String type;
 
 	/**
-	 * Creates a DuplicateMappingException using the given type and name.
+	 * Creates a {@code DuplicateMappingException} using the given type and name.
 	 *
 	 * @param type The type of the duplicated thing.
 	 * @param name The name of the duplicated thing.
@@ -79,7 +80,7 @@ public class DuplicateMappingException extends MappingException {
 	}
 
 	/**
-	 * Creates a DuplicateMappingException using the given customMessage, type and name.
+	 * Creates a {@code DuplicateMappingException} using the given customMessage, type and name.
 	 *
 	 * @param customMessage A custom exception message explaining the exception condition
 	 * @param type The type of the duplicated thing.

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

@@ -10,7 +10,7 @@ import java.util.Locale;
 import jakarta.persistence.EntityNotFoundException;
 
 /**
- * Exception for {@link org.hibernate.annotations.NotFoundAction#EXCEPTION}
+ * Exception for {@link org.hibernate.annotations.NotFoundAction#EXCEPTION}.
  *
  * @see org.hibernate.annotations.NotFound
  *

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

@@ -13,7 +13,7 @@ package org.hibernate;
  */
 public class HibernateError extends HibernateException {
 	/**
-	 * Constructs HibernateError with the condition message.
+	 * Constructs {@code HibernateError} with the condition message.
 	 *
 	 * @param message Message explaining the exception/error condition
 	 */
@@ -22,7 +22,7 @@ public class HibernateError extends HibernateException {
 	}
 
 	/**
-	 * Constructs HibernateError with the condition message and cause.
+	 * Constructs {@code HibernateError} with the condition message and cause.
 	 *
 	 * @param message Message explaining the exception/error condition
 	 * @param cause The underlying cause.

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

@@ -18,7 +18,7 @@ import jakarta.persistence.PersistenceException;
  */
 public class HibernateException extends PersistenceException {
 	/**
-	 * Constructs a HibernateException using the given exception message.
+	 * Constructs a {@code HibernateException} using the given exception message.
 	 *
 	 * @param message The message explaining the reason for the exception
 	 */
@@ -27,7 +27,7 @@ public class HibernateException extends PersistenceException {
 	}
 
 	/**
-	 * Constructs a HibernateException using the given message and underlying cause.
+	 * Constructs a {@code HibernateException} using the given message and underlying cause.
 	 *
 	 * @param cause The underlying cause.
 	 */
@@ -36,7 +36,7 @@ public class HibernateException extends PersistenceException {
 	}
 
 	/**
-	 * Constructs a HibernateException using the given message and underlying cause.
+	 * Constructs a {@code HibernateException} using the given message and underlying cause.
 	 *
 	 * @param message The message explaining the reason for the exception.
 	 * @param cause The underlying cause.

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

@@ -15,7 +15,7 @@ public class InstantiationException extends HibernateException {
 	private final Class<?> clazz;
 
 	/**
-	 * Constructs a InstantiationException.
+	 * Constructs a {@code InstantiationException}.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param clazz The Class we are attempting to instantiate

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

@@ -10,9 +10,9 @@ import org.hibernate.boot.jaxb.Origin;
 
 /**
  * Thrown when a mapping is found to be invalid.
- *
+ * <p>
- * Similar to MappingException, but this contains more info about the path and type of
+ * Similar to {@link MappingException}, but contains more information
- * mapping (e.g. file, resource or url)
+ * about the path and type of mapping (e.g. file, resource or URL).
  * 
  * @author Max Rydahl Andersen
  * @author Steve Ebersole
@@ -36,7 +36,7 @@ public class InvalidMappingException extends MappingException {
 	}
 
 	/**
-	 * Constructs an InvalidMappingException using the given information.
+	 * Constructs an {@code InvalidMappingException} using the given information.
 	 *
 	 * @param customMessage The custom message explaining the exception condition
 	 * @param type The type of invalid mapping document
@@ -49,7 +49,7 @@ public class InvalidMappingException extends MappingException {
 	}
 
 	/**
-	 * Constructs an InvalidMappingException using the given information.
+	 * Constructs an {@code InvalidMappingException} using the given information.
 	 *
 	 * @param customMessage The custom message explaining the exception condition
 	 * @param origin The origin of the invalid mapping document

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

@@ -11,9 +11,11 @@ import org.hibernate.internal.CoreMessageLogger;
 import org.jboss.logging.Logger;
 
 /**
- * Indicates an attempt to access not-yet-fetched data outside of a session context.
+ * Indicates an attempt to access unfetched data outside the context
- *
+ * of an open stateful {@link Session}.
- * For example, when an uninitialized proxy or collection is accessed after the session was closed.
+ * <p>
+ * For example, this exception occurs when an uninitialized proxy or
+ * collection is accessed after the session was closed.
  *
  * @see Hibernate#initialize(Object)
  * @see Hibernate#isInitialized(Object)
@@ -27,7 +29,7 @@ public class LazyInitializationException extends HibernateException {
 	);
 
 	/**
-	 * Constructs a LazyInitializationException using the given message.
+	 * Constructs a {@code LazyInitializationException} using the given message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -7,14 +7,15 @@
 package org.hibernate;
 
 /**
- * An exception that occurs while reading mapping sources (xml/annotations),
+ * An exception that occurs while reading mapping sources, either
- * usually as a result of something screwy in the O-R mappings.
+ * XML or annotations, usually as a result of something screwy in
+ * the O/R mappings.
  *
  * @author Gavin King
  */
 public class MappingException extends HibernateException {
 	/**
-	 * Constructs a MappingException using the given information.
+	 * Constructs a {@code MappingException} using the given information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param cause The underlying cause
@@ -24,7 +25,7 @@ public class MappingException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a MappingException using the given information.
+	 * Constructs a {@code MappingException} using the given information.
 	 *
 	 * @param cause The underlying cause
 	 */
@@ -33,7 +34,7 @@ public class MappingException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a MappingException using the given information.
+	 * Constructs a {@code MappingException} using the given information.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -10,7 +10,7 @@ import java.util.Optional;
 
 /**
  * Loads an entity by its natural identifier.
- *
+ * <p>
  * This is a generic form of load-by-natural-id covering both a single attribute
  * and multiple attributes as the natural-id.  For natural-ids defined by a single
  * attribute, {@link SimpleNaturalIdLoadAccess} offers simplified access.

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

@@ -9,9 +9,9 @@ package org.hibernate;
 import org.hibernate.pretty.MessageHelper;
 
 /**
- * This exception is thrown when an operation would break session-scoped identity. This occurs if the
+ * This exception is thrown when an operation would break session-scoped identity.
- * user tries to associate two different instances of the same Java class with a particular identifier,
+ * This occurs if the user tries to associate two different instances of the same
- * in the scope of a single Session.
+ * Java class with a particular identifier, in the scope of a single Session.
  *
  * @author Gavin King
  */
@@ -20,8 +20,9 @@ public class NonUniqueObjectException extends HibernateException {
 	private final String entityName;
 
 	/**
-	 * Constructs a NonUniqueObjectException using the given information.
+	 * Constructs a {@code NonUniqueObjectException} using the given information.
-	 *  @param message A message explaining the exception condition
+	 *
+	 * @param message A message explaining the exception condition
 	 * @param entityId The identifier of the entity
 	 * @param entityName The name of the entity
 	 */
@@ -32,8 +33,10 @@ public class NonUniqueObjectException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a NonUniqueObjectException using the given information, using a standard message.
+	 * Constructs a {@code NonUniqueObjectException} using the given information,
-	 *  @param entityId The identifier of the entity
+	 * and using a standard message.
+	 *
+	 * @param entityId The identifier of the entity
 	 * @param entityName The name of the entity
 	 */
 	public NonUniqueObjectException(Object entityId, String entityName) {

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

@@ -9,15 +9,16 @@ package org.hibernate;
 import org.hibernate.query.Query;
 
 /**
- * Thrown when the application calls {@link Query#uniqueResult()}
+ * Thrown when the application calls {@link Query#getSingleResult()} or
- * and the query returned more than one result.  Unlike all other Hibernate exceptions,
+ * {@link Query#uniqueResult()} and the query returns more than one row
+ * from the database. Unlike every other exception thrown by Hibernate,
  * this one is recoverable!
  *
  * @author Gavin King
  */
 public class NonUniqueResultException extends HibernateException {
 	/**
-	 * Constructs a NonUniqueResultException.
+	 * Constructs a {@code NonUniqueResultException}.
 	 *
 	 * @param resultCount The number of actual results.
 	 */

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

@@ -13,7 +13,8 @@ package org.hibernate;
  */
 public class ObjectDeletedException extends UnresolvableObjectException {
 	/**
-	 * Constructs an ObjectDeletedException using the given information.
+	 * Constructs an {@code ObjectDeletedException} using the given information.
+	 *
 	 *  @param message A message explaining the exception condition
 	 * @param identifier The identifier of the entity
 	 * @param entityName The name of the entity

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

@@ -7,21 +7,23 @@
 package org.hibernate;
 
 /**
- * Thrown when {@code Session.load()} fails to select a row with
+ * Thrown when {@link Session#find(Class, Object)} fails to select a row
- * the given primary key (identifier value). This exception might not
+ * with the given primary key (identifier value).
- * be thrown when {@code load()} is called, even if there was no
- * row on the database, because {@code load()} returns a proxy if
- * possible. Applications should use {@code Session.get()} to test if
- * a row exists in the database.
  * <p>
- * Like all Hibernate exceptions, this exception is considered 
+ * On the other hand, this exception might not be thrown immediately by
- * unrecoverable.
+ * {@link Session#getReference(Class, Object)} is called, even when there
+ * was no row on the database, because {@code getReference()} returns a
+ * proxy if possible. Programs should use {@code Session.find()} to test
+ * if a row exists in the database.
+ * <p>
+ * Like all Hibernate exceptions, this one is considered unrecoverable.
  *
  * @author Gavin King
  */
 public class ObjectNotFoundException extends UnresolvableObjectException {
 	/**
-	 * Constructs a ObjectNotFoundException using the given information.
+	 * Constructs a {@code ObjectNotFoundException} using the given information.
+	 * 
 	 *  @param identifier The identifier of the entity
 	 * @param entityName The name of the entity
 	 */

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

@@ -7,14 +7,14 @@
 package org.hibernate;
 
 /**
- * Thrown when the user passes a persistent instance to a {@code Session}
+ * Thrown when the user passes a persistent instance to a {@link Session}
  * method that expects a transient instance.
  *
  * @author Gavin King
  */
 public class PersistentObjectException extends HibernateException {
 	/**
-	 * Constructs a PersistentObjectException using the given message.
+	 * Constructs a {@code PersistentObjectException} using the given message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -15,11 +15,11 @@ import java.sql.SQLException;
  */
 public class PessimisticLockException extends JDBCException {
 	/**
-	 * Constructs a PessimisticLockException using the specified information.
+	 * Constructs a {@code PessimisticLockException} using the specified information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param sqlException The underlying SQL exception
-	 * @param sql The sql that led to the exception (may be null, though usually should not be)
+	 * @param sql The sql that led to the exception (possibly null, but usually not)
 	 */
 	public PessimisticLockException(String message, SQLException sqlException, String sql) {
 		super( message, sqlException, sql );

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

@@ -11,13 +11,16 @@ import org.hibernate.internal.util.StringHelper;
 /**
  * A problem occurred accessing a property of an instance of a
  * persistent class by reflection, or via enhanced entities.
- * There are a number of possible underlying causes, including
+ * There are a number of possible underlying causes, including:
  * <ul>
- * <li>failure of a security check
+ * <li>failure of a security check,
- * <li>an exception occurring inside the getter or setter method
+ * <li>an exception occurring inside the getter or setter method,
- * <li>a nullable database column was mapped to a primitive-type property
+ * <li>a nullable database column was mapped to a primitive-type
- * <li>the Hibernate type was not castable to the property type (or vice-versa)
+ *     property, or
+ * <li>the Hibernate type was not castable to the property type
+ *     (or vice-versa)
  * </ul>
+ *
  * @author Gavin King
  */
 public class PropertyAccessException extends HibernateException {
@@ -26,7 +29,7 @@ public class PropertyAccessException extends HibernateException {
 	private final boolean wasSetter;
 
 	/**
-	 * Constructs a PropertyAccessException using the specified information.
+	 * Constructs a {@code PropertyAccessException} using the specified information.
 	 *
 	 * @param cause The underlying cause
 	 * @param message A message explaining the exception condition

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

@@ -14,7 +14,7 @@ package org.hibernate;
  */
 public class PropertyNotFoundException extends MappingException {
 	/**
-	 * Constructs a PropertyNotFoundException given the specified message.
+	 * Constructs a {@code PropertyNotFoundException} given the specified message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */

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

@@ -13,7 +13,7 @@ import java.util.Collection;
  */
 public class PropertySetterAccessException extends PropertyAccessException {
 	/**
-	 * Constructs a PropertyAccessException using the specified information.
+	 * Constructs a {@code PropertyAccessException} using the specified information.
 	 *
 	 * @param cause The underlying cause
 	 * @param persistentClass The class which is supposed to contain the property in question

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

@@ -12,8 +12,10 @@ import org.hibernate.internal.util.StringHelper;
  * Thrown when the (illegal) value of a property can not be persisted.
  * There are two main causes:
  * <ul>
- * <li>a property declared {@code not-null="true"} is null
+ * <li>a property declared
- * <li>an association references an unsaved transient instance
+ *     {@link jakarta.persistence.Basic#optional() @Basic(optional=false)}
+ *     is null, or
+ * <li>an association references an unsaved transient instance.
  * </ul>
  * @author Gavin King
  */
@@ -22,7 +24,7 @@ public class PropertyValueException extends HibernateException {
 	private final String propertyName;
 
 	/**
-	 * Constructs a PropertyValueException using the specified information.
+	 * Constructs a {@code PropertyValueException} using the specified information.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param entityName The name of the entity, containing the property

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

@@ -7,13 +7,14 @@
 package org.hibernate;
 
 /**
- * A problem occurred translating a Hibernate query to SQL due to invalid query syntax, etc.
+ * A problem occurred translating a Hibernate query to SQL
+ * due to invalid query syntax, or some similar problem.
  */
 public class QueryException extends HibernateException {
 	private final String queryString;
 
 	/**
-	 * Constructs a QueryException using the specified exception message.
+	 * Constructs a {@code QueryException} using the specified exception message.
 	 *
 	 * @param message A message explaining the exception condition
 	 */
@@ -22,7 +23,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified exception message and cause.
+	 * Constructs a {@code QueryException} using the specified exception message and cause.
 	 *
 	 * @param message A message explaining the exception condition
 	 * @param cause The underlying cause
@@ -32,7 +33,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified exception message and query-string.
+	 * Constructs a {@code 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
@@ -42,7 +43,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified exception message and query-string.
+	 * Constructs a {@code 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
@@ -54,7 +55,7 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a QueryException using the specified cause.
+	 * Constructs a {@code QueryException} using the specified cause.
 	 *
 	 * @param cause The underlying cause
 	 */
@@ -63,7 +64,8 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Retrieve the query being evaluated when the exception occurred.  May be null, but generally should not.
+	 * Retrieve the query being evaluated when the exception occurred.
+	 * May be null, but generally should not be.
 	 *
 	 * @return The query string
 	 */
@@ -85,16 +87,19 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Wraps this exception with another, of same kind, with the specified queryString.  If this exception already
+	 * Wraps this exception with another, of same kind, with the specified query string.
-	 * has a queryString defined, the same exception ({@code this}) is returned.  Otherwise the protected
+	 * If this exception already has a query string defined, the same exception ({@code this})
-	 * {@link #generateQueryException(String)} is called, to allow subclasses to properly create the correct
+	 * is returned. Otherwise, the protected {@link #generateQueryException(String)} is called,
-	 * subclass for return.
+	 * to allow subclasses to properly create the correct subclass for return.
 	 *
 	 * @param queryString The query string that led to the QueryException
 	 *
-	 * @return {@code this}, if {@code this} has {@code null} for {@link #getQueryString()}; otherwise a new
+	 * @return {@code this}, if {@code this} has {@code null} for {@link #getQueryString()};
-	 * QueryException (or subclass) is returned.
+	 *         otherwise a new {@code QueryException} (or subclass) is returned.
+	 *
+	 * @deprecated This method is no longer used
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
 	public final QueryException wrapWithQueryString(String queryString) {
 		if ( this.getQueryString() != null ) {
 			return this;
@@ -104,15 +109,15 @@ public class QueryException extends HibernateException {
 	}
 
 	/**
-	 * Called from {@link #wrapWithQueryString(String)} when we really need to generate a new QueryException
+	 * Called from {@link #wrapWithQueryString(String)} when we really need to
-	 * (or subclass).
+	 * generate a new {@code QueryException} (or subclass).
 	 * <p>
-	 * NOTE : implementors should take care to use {@link #getOriginalMessage()} for the message, not
+	 * NOTE : implementors should take care to use {@link #getOriginalMessage()}
-	 * {@link #getMessage()}
+	 *        for the message, not {@link #getMessage()}
 	 *
 	 * @param queryString The query string
 	 *
-	 * @return The generated QueryException (or subclass)
+	 * @return The generated {@code QueryException} (or subclass)
 	 *
 	 * @see #getOriginalMessage()
 	 */

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

@@ -13,7 +13,7 @@ package org.hibernate;
  */
 public class QueryParameterException extends QueryException {
 	/**
-	 * Constructs a QueryParameterException using the supplied exception message.
+	 * Constructs a {@code QueryParameterException} using the supplied exception message.
 	 *
 	 * @param message The message explaining the exception condition
 	 */
@@ -22,7 +22,7 @@ public class QueryParameterException extends QueryException {
 	}
 
 	/**
-	 * Constructs a QueryParameterException
+	 * Constructs a {@code QueryParameterException}
 	 *
 	 * @param message The message explaining the exception condition
 	 * @param queryString The query that led to the exception

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

@@ -15,7 +15,7 @@ import java.sql.SQLException;
  */
 public class QueryTimeoutException extends JDBCException {
 	/**
-	 * Constructs a QueryTimeoutException using the supplied information.
+	 * Constructs a {@code QueryTimeoutException} using the supplied information.
 	 *
 	 * @param message The message explaining the exception condition
 	 * @param sqlException The underlying SQLException

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

@@ -7,7 +7,8 @@
 package org.hibernate;
 
 /**
- * Indicates an attempt was made to use a closed resource (Session, SessionFactory, etc).
+ * Indicates an attempt was made to use a closed resource, such as
+ * a closed {@link Session} or {@link SessionFactory}.
  *
  * @author Steve Ebersole
  */

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

@@ -7,14 +7,15 @@
 package org.hibernate;
 
 /**
- * Thrown when the user calls a method of a {@link Session} that is in an inappropriate state for the given call (for
+ * Thrown when the user calls a method of a {@link Session} that is
- * example, the session is closed or disconnected).
+ * in an inappropriate state for the given call (for example, the
+ * session is closed or disconnected).
  *
  * @author Gavin King
  */
 public class SessionException extends HibernateException {
 	/**
-	 * Constructs a new SessionException with the given message.
+	 * Constructs a new {@code SessionException} with the given message.
 	 *
 	 * @param message The message indicating the specific problem.
 	 */
@@ -23,7 +24,7 @@ public class SessionException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a new SessionException with the given message.
+	 * Constructs a new {@code SessionException} with the given message.
 	 *
 	 * @param message The message indicating the specific problem.
 	 * @param cause An exception which caused this exception to be created.

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

@@ -9,8 +9,8 @@ package org.hibernate;
 import org.hibernate.pretty.MessageHelper;
 
 /**
- * A specialized StaleStateException that carries information about the particular entity
+ * A specialized {@link StaleStateException} that carries information about
- * instance that was the source of the failure.
+ * the particular entity instance that was the source of the failure.
  *
  * @author Gavin King
  */
@@ -19,7 +19,7 @@ public class StaleObjectStateException extends StaleStateException {
 	private final Object identifier;
 
 	/**
-	 * Constructs a StaleObjectStateException using the supplied information.
+	 * Constructs a {@code StaleObjectStateException} using the supplied information.
 	 *  @param entityName The name of the entity
 	 * @param identifier The identifier of the entity
 	 */

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

@@ -7,18 +7,19 @@
 package org.hibernate;
 
 /**
- * Thrown when a version number or timestamp check failed, indicating that the Session contained
+ * Thrown when a version number or timestamp check failed, indicating that
- * stale data (when using long transactions with versioning). Also occurs if we try to delete or update
+ * the {@link Session} contained stale data (when using long transactions
- * a row that does not exist.
+ * with versioning). Also occurs if we try to delete or update a row that
- *
+ * does not exist.
- * Note that this exception often indicates that the user failed to specify the correct
+ * <p>
- * {@code unsaved-value} strategy for an entity
+ * Note that this exception sometimes indicates that the user failed to
+ * specify the correct {@code unsaved-value} strategy for an entity.
  *
  * @author Gavin King
  */
 public class StaleStateException extends HibernateException {
 	/**
-	 * Constructs a StaleStateException using the supplied message.
+	 * Constructs a {@code StaleStateException} using the supplied message.
 	 *
 	 * @param message The message explaining the exception condition
 	 */

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

@@ -14,7 +14,7 @@ package org.hibernate;
  */
 public class TransactionException extends HibernateException {
 	/**
-	 * Constructs a TransactionException using the specified information.
+	 * Constructs a {@code TransactionException} using the specified information.
 	 *
 	 * @param message The message explaining the exception condition
 	 * @param cause The underlying cause
@@ -24,7 +24,7 @@ public class TransactionException extends HibernateException {
 	}
 
 	/**
-	 * Constructs a TransactionException using the specified information.
+	 * Constructs a {@code TransactionException} using the specified information.
 	 *
 	 * @param message The message explaining the exception condition
 	 */

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

@@ -7,13 +7,14 @@
 package org.hibernate;
 
 /**
- * Thrown when the user passes a transient instance to a Session method that expects a persistent instance.
+ * Thrown when the user passes a transient instance to a {@link Session}
+ * method that expects a persistent instance.
  *
  * @author Gavin King
  */
 public class TransientObjectException extends HibernateException {
 	/**
-	 * Constructs a TransientObjectException using the supplied message.
+	 * Constructs a {@code TransientObjectException} using the supplied message.
 	 *
 	 * @param message The message explaining the exception condition
 	 */

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

@@ -20,7 +20,7 @@ public class TransientPropertyValueException extends TransientObjectException {
 	private final String propertyName;
 
 	/**
-	 * Constructs a {@link TransientPropertyValueException} instance.
+	 * Constructs a {@code TransientPropertyValueException} instance.
 	 *
 	 * @param message - the exception message;
 	 * @param transientEntityName - the entity name for the transient entity
@@ -50,6 +50,7 @@ public class TransientPropertyValueException extends TransientObjectException {
 	/**
 	 * Returns the entity name for entity that owns the association
 	 * property.
+	 *
 	 * @return the entity name for entity that owns the association
 	 * property
 	 */
@@ -59,6 +60,7 @@ public class TransientPropertyValueException extends TransientObjectException {
 
 	/**
 	 * Returns the property name.
+	 *
 	 * @return the property name.
 	 */
 	public String getPropertyName() {

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

@@ -13,7 +13,7 @@ package org.hibernate;
  */
 public class TypeMismatchException extends HibernateException {
 	/**
-	 * Constructs a TypeMismatchException using the supplied message.
+	 * Constructs a {@code TypeMismatchException} using the supplied message.
 	 *
 	 * @param message The message explaining the exception condition
 	 */

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

@@ -7,11 +7,11 @@
 package org.hibernate;
 
 /**
- * Indicates an attempt was made to refer to an unknown entity name/class.
+ * Indicates an attempt was made to refer to an unknown entity name or class.
  * <p>
- * NOTE : extends MappingException because that's what core used to do and that's how
+ * @implNote This class extends {@link MappingException} for legacy reasons.
- * HEM expects it.  Longer term I think it makes more sense to have a different
+ * Longer term I think it makes more sense to have a different hierarchy for
- * hierarchy for runtime-"mapping" exceptions.
+ * runtime-"mapping" exceptions.
  *
  * @author Steve Ebersole
  */

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

@@ -15,7 +15,7 @@ public class UnknownProfileException extends HibernateException {
 	private final String name;
 
 	/**
-	 * Constructs an UnknownProfileException for the given name.
+	 * Constructs an {@code UnknownProfileException} for the given name.
 	 *
 	 * @param name The profile name that was unknown.
 	 */

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

@@ -19,7 +19,8 @@ public class UnresolvableObjectException extends HibernateException {
 	private final String entityName;
 
 	/**
-	 * Constructs an UnresolvableObjectException using the specified information.
+	 * Constructs an {@code 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
 	 */
@@ -34,7 +35,7 @@ public class UnresolvableObjectException extends HibernateException {
 	}
 
 	/**
-	 * Factory method for building and throwing an UnresolvableObjectException if the entity is null.
+	 * Factory method for building and throwing an {@code UnresolvableObjectException} if the entity is null.
 	 *
 	 * @param entity The entity to check for nullness
 	 * @param identifier The identifier of the entity

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

@@ -7,8 +7,7 @@
 package org.hibernate;
 
 /**
- * This exception is thrown when an invalid LockMode is selected for an entity. This occurs if the
+ * This exception is thrown when an invalid {@link LockMode} is selected for an entity.
- * user tries to set an inappropriate LockMode for an entity.
  *
  * @author John O'Hara
  */

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

@@ -9,8 +9,8 @@ package org.hibernate;
 import java.util.Locale;
 
 /**
- * Thrown when loading an entity (by identifier) results in a value that cannot be treated as the subclass
+ * Thrown when loading an entity (by identifier) results in a value that
- * type requested by the caller.
+ * cannot be treated as the subclass type requested by the caller.
  *
  * @author Gavin King
  */
@@ -19,7 +19,7 @@ public class WrongClassException extends HibernateException {
 	private final String entityName;
 
 	/**
-	 * Constructs a WrongClassException using the supplied information.
+	 * Constructs a {@code 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