remove obsolete APIs and clean up warnings

rewrite the incorrect javadoc for the class Hibernate

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

@@ -10,7 +10,6 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.HashSet;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -29,7 +28,6 @@ import org.hibernate.collection.spi.PersistentSet;
 import org.hibernate.collection.spi.PersistentSortedMap;
 import org.hibernate.collection.spi.PersistentSortedSet;
 import org.hibernate.collection.spi.PersistentCollection;
-import org.hibernate.engine.HibernateIterator;
 import org.hibernate.engine.jdbc.LobCreator;
 import org.hibernate.engine.jdbc.spi.JdbcServices;
 import org.hibernate.engine.spi.PersistentAttributeInterceptable;
@@ -42,12 +40,15 @@ import org.hibernate.proxy.HibernateProxy;
 import org.hibernate.proxy.LazyInitializer;
 
 /**
- * <ul>
+ * Various utility functions for working with proxies and lazy collection references,
- * <li>Provides access to the full range of Hibernate built-in types. {@code Type}
+ * along with factory methods for obtaining a {@link LobCreator}.
- * instances may be used to bind values to query parameters.
+ * <p>
- * <li>A factory for new {@link java.sql.Blob}s and {@link java.sql.Clob}s.
+ * Operations like {@link #isInitialized(Object)} and {@link #initialize(Object)} are
- * <li>Defines static methods for manipulation of proxies.
+ * of general purpose. But {@link #createDetachedProxy(SessionFactory, Class, Object)}
- * </ul>
+ * and {@link CollectionInterface#createDetachedProxy(SessionFactory, Class, Object)}
+ * are intended for use by generic code that must materialize an "amputated" graph of
+ * Hibernate entities. (For example, a library which deserializes entities from JSON.)
+ *
  *
  * @author Gavin King
  * @see java.sql.Clob
@@ -65,13 +66,14 @@ public final class Hibernate {
 
 
 	/**
-	 * Force initialization of a proxy or persistent collection.
+	 * Force initialization of a proxy or persistent collection. In the case of a
-	 * <p/>
+	 * many-valued association, only the collection itself is initialized. It is not
-	 * Note: This only ensures initialization of a proxy object or collection;
+	 * guaranteed that the associated entities held within the collection will be
-	 * it is not guaranteed that the elements INSIDE the collection will be initialized/materialized.
+	 * initialized.
 	 *
 	 * @param proxy a persistable object, proxy, persistent collection or {@code null}
-	 * @throws HibernateException if we can't initialize the proxy at this time, eg. the {@code Session} was closed
+	 * @throws HibernateException if the proxy cannot be initialized at this time,
+	 * for example, if the {@code Session} was closed
 	 */
 	public static void initialize(Object proxy) throws HibernateException {
 		if ( proxy == null ) {
@@ -82,7 +84,7 @@ public final class Hibernate {
 			( (HibernateProxy) proxy ).getHibernateLazyInitializer().initialize();
 		}
 		else if ( proxy instanceof PersistentCollection ) {
-			( (PersistentCollection) proxy ).forceInitialization();
+			( (PersistentCollection<?>) proxy ).forceInitialization();
 		}
 		else if ( proxy instanceof PersistentAttributeInterceptable ) {
 			final PersistentAttributeInterceptable interceptable = (PersistentAttributeInterceptable) proxy;
@@ -106,13 +108,10 @@ public final class Hibernate {
 		}
 		else if ( proxy instanceof PersistentAttributeInterceptable ) {
 			final PersistentAttributeInterceptor interceptor = ( (PersistentAttributeInterceptable) proxy ).$$_hibernate_getInterceptor();
-			if ( interceptor instanceof EnhancementAsProxyLazinessInterceptor ) {
+			return !(interceptor instanceof EnhancementAsProxyLazinessInterceptor);
-				return false;
-			}
-			return true;
 		}
 		else if ( proxy instanceof PersistentCollection ) {
-			return ( (PersistentCollection) proxy ).wasInitialized();
+			return ( (PersistentCollection<?>) proxy ).wasInitialized();
 		}
 		else {
 			return true;
@@ -121,21 +120,23 @@ public final class Hibernate {
 
 	/**
 	 * Get the true, underlying class of a proxied persistent class. This operation
-	 * will initialize a proxy by side-effect.
+	 * will initialize a proxy by side effect.
 	 *
-	 * @param proxy a persistable object or proxy
+	 * @param proxy an entity instance or proxy
 	 * @return the true class of the instance
-	 * @throws HibernateException
 	 */
-	public static Class getClass(Object proxy) {
+	@SuppressWarnings("unchecked")
+	public static <T> Class<? extends T> getClass(T proxy) {
+		Class<?> result;
 		if ( proxy instanceof HibernateProxy ) {
-			return ( (HibernateProxy) proxy ).getHibernateLazyInitializer()
+			result = ( (HibernateProxy) proxy ).getHibernateLazyInitializer()
 					.getImplementation()
 					.getClass();
 		}
 		else {
-			return proxy.getClass();
+			result = proxy.getClass();
 		}
+		return (Class<? extends T>) result;
 	}
 
 	/**
@@ -178,32 +179,13 @@ public final class Hibernate {
 	}
 
 	/**
-	 * Close an {@link Iterator} instances obtained from {@link org.hibernate.Query#iterate()} immediately
+	 * Check if the property is initialized. If the named property does not exist or
-	 * instead of waiting until the session is closed or disconnected.
+	 * is not persistent, this method always returns {@code true}.
-	 *
-	 * @param iterator an Iterator created by iterate()
-	 *
-	 * @throws HibernateException Indicates a problem closing the Hibernate iterator.
-	 * @throws IllegalArgumentException If the Iterator is not a "Hibernate Iterator".
-	 *
-	 * @see Query#iterate()
-	 */
-	public static void close(Iterator iterator) throws HibernateException {
-		if ( iterator instanceof HibernateIterator ) {
-			( (HibernateIterator) iterator ).close();
-		}
-		else {
-			throw new IllegalArgumentException( "not a Hibernate iterator" );
-		}
-	}
-
-	/**
-	 * Check if the property is initialized. If the named property does not exist
-	 * or is not persistent, this method always returns {@code true}.
 	 *
 	 * @param proxy The potential proxy
 	 * @param propertyName the name of a persistent attribute of the object
-	 * @return true if the named property of the object is not listed as uninitialized; false otherwise
+	 * @return true if the named property of the object is not listed as uninitialized;
+	 *         false otherwise
 	 */
 	public static boolean isPropertyInitialized(Object proxy, String propertyName) {
 		final Object entity;
@@ -231,11 +213,15 @@ public final class Hibernate {
 	}
 
     /**
-     * Unproxies a {@link HibernateProxy}. If the proxy is uninitialized, it automatically triggers an initialization.
+     * If the given object is not a proxy, return it. But, if it is a proxy, ensure
-     * In case the supplied object is null or not a proxy, the object will be returned as-is.
+	 * that the proxy is initialized, and return a direct reference to its proxied
-     *
+	 * entity object.
-     * @param proxy the {@link HibernateProxy} to be unproxied
+	 *
-     * @return the proxy's underlying implementation object, or the supplied object otherwise
+	 * @param proxy an object which might be a proxy for an entity
+	 * @return a reference that is never proxied
+	 *
+	 * @throws LazyInitializationException if this operation is called on an
+	 * uninitialized proxy that is not associated with an open session.
      */
 	public static Object unproxy(Object proxy) {
 		if ( proxy instanceof HibernateProxy ) {
@@ -249,23 +235,28 @@ public final class Hibernate {
 	}
 
 	/**
-	 * Unproxies a {@link HibernateProxy}. If the proxy is uninitialized, it automatically triggers an initialization.
+	 * If the given object is not a proxy, cast it to the given type, and return it.
-	 * In case the supplied object is null or not a proxy, the object will be returned as-is.
+	 * But, if it is a proxy, ensure that the proxy is initialized, and return a
+	 * direct reference to its proxied entity object, after casting to the given type.
 	 *
-	 * @param proxy the {@link HibernateProxy} to be unproxied
+	 * @param proxy an object which might be a proxy for an entity
-	 * @param entityClass the entity type
+	 * @param entityClass an entity type to cast to
-	 * @return the proxy's underlying implementation object, or the supplied object otherwise
+	 * @return a reference that is never proxied
+	 *
+	 * @throws LazyInitializationException if this operation is called on an
+	 * uninitialized proxy that is not associated with an open session.
 	 */
 	public static <T> T unproxy(T proxy, Class<T> entityClass) {
 		return entityClass.cast( unproxy( proxy ) );
 	}
 
 	/**
-	 * Obtain a detached, uninitialized reference (a proxy) for a persistent entity with the given identifier.
+	 * Obtain a detached, uninitialized reference (a proxy) for a persistent entity with
+	 * the given identifier.
 	 *
-	 * The returned proxy is not associated with any session, and cannot be initialized by calling
+	 * The returned proxy is not associated with any session, and cannot be initialized
-	 * {@link #initialize(Object)}. It can be used to represent a reference to the entity when working with
+	 * by calling {@link #initialize(Object)}. It can be used to represent a reference to
-	 * a detached object graph.
+	 * the entity when working with a detached object graph.
 	 *
 	 * @param sessionFactory the session factory with which the entity is associated
 	 * @param entityClass the entity class
@@ -273,6 +264,7 @@ public final class Hibernate {
 	 *
 	 * @return a detached uninitialized proxy
 	 */
+	@SuppressWarnings("unchecked")
 	public static <E> E createDetachedProxy(SessionFactory sessionFactory, Class<E> entityClass, Object id) {
 		EntityPersister persister =
 				sessionFactory.unwrap(SessionFactoryImplementor.class).getMetamodel()
@@ -298,11 +290,12 @@ public final class Hibernate {
 		}
 
 		/**
-		 * Obtain a detached, uninitialized persistent collection of the type represented by this object.
+		 * Obtain a detached, uninitialized persistent collection of the type represented
+		 * by this object.
 		 *
-		 * The returned wrapper object is not associated with any session, and cannot be initialized by calling
+		 * The returned wrapper object is not associated with any session, and cannot be
-		 * {@link #initialize(Object)}. It can be used to represent an uninitialized collection when working with
+		 * initialized by calling {@link #initialize(Object)}. It can be used to represent
-		 * a detached object graph.
+		 * an uninitialized collection when working with a detached object graph.
 		 *
 		 * @return an uninitialized persistent collection
 		 */

hibernate-core/src/main/java/org/hibernate/engine/HibernateIterator.java

@@ -1,29 +0,0 @@
-/*
- * Hibernate, Relational Persistence for Idiomatic Java
- *
- * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
- * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
- */
-package org.hibernate.engine;
-
-import java.io.Closeable;
-import java.util.Iterator;
-
-import org.hibernate.JDBCException;
-
-/**
- * Hibernate-specific iterator that may be closed
- *
- * @see org.hibernate.Query#iterate()
- * @see org.hibernate.Hibernate#close(Iterator)
- *
- * @author Gavin King
- */
-public interface HibernateIterator extends Iterator, AutoCloseable, Closeable {
-	/**
-	 * Close the Hibernate query result iterator
-	 *
-	 * @throws JDBCException Indicates a problem releasing the underlying JDBC resources.
-	 */
-	void close() throws JDBCException;
-}