[Hibernate-commits] Hibernate Code SVN: r10022 - trunk/Hibernate3/src/org/hibernate/engine

[<hib...@li...>]

Author: ste...@jb...
Date: 2006-06-15 15:41:25 -0400 (Thu, 15 Jun 2006)
New Revision: 10022

Modified:
   trunk/Hibernate3/src/org/hibernate/engine/BatchFetchQueue.java
Log:
javadocs

Modified: trunk/Hibernate3/src/org/hibernate/engine/BatchFetchQueue.java
===================================================================
--- trunk/Hibernate3/src/org/hibernate/engine/BatchFetchQueue.java	2006-06-15 19:07:03 UTC (rev 10021)
+++ trunk/Hibernate3/src/org/hibernate/engine/BatchFetchQueue.java	2006-06-15 19:41:25 UTC (rev 10022)
@@ -23,49 +23,70 @@
  */
 public class BatchFetchQueue {
 
-	public static final Object MARKER = new MarkerObject("MARKER");
+	public static final Object MARKER = new MarkerObject( "MARKER" );
 
-	// A set of entity keys that we predict we might need to load soon
-	// TODO: this would be better as a SequencedReferenceSet, but no such beast exists!
-	private final Map batchLoadableEntityKeys = new SequencedHashMap(8); //actually, a Set
+	/**
+	 * Defines a sequence of {@link EntityKey} elements that are currently
+	 * elegible for batch-fetching.
+	 * <p/>
+	 * Even though this is a map, we only use the keys.  A map was chosen in
+	 * order to utilize a {@link SequencedHashMap} to maintain sequencing
+	 * as well as uniqueness.
+	 * <p/>
+	 * TODO : this would be better as a SequencedReferenceSet, but no such beast exists!
+	 */
+	private final Map batchLoadableEntityKeys = new SequencedHashMap(8);
 
-	// The subqueries that were used to load the entity with the given key
-	private final Map subselectsByEntityKey = new HashMap(8); //new ReferenceMap(ReferenceMap.HARD, ReferenceMap.SOFT);
+	/**
+	 * A map of {@link SubselectFetch subselect-fetch descriptors} keyed by the
+	 * {@link EntityKey) against which the descriptor is registered.
+	 */
+	private final Map subselectsByEntityKey = new HashMap(8);
 
-	// The owning persistence context
+	/**
+	 * The owning persistence context.
+	 */
 	private final PersistenceContext context;
 
+	/**
+	 * Constructs a queue for the given context.
+	 *
+	 * @param context The owning context.
+	 */
 	public BatchFetchQueue(PersistenceContext context) {
 		this.context = context;
 	}
 
+	/**
+	 * Clears all entries from this fetch queue.
+	 */
 	public void clear() {
 		batchLoadableEntityKeys.clear();
 		subselectsByEntityKey.clear();
 	}
 
+	/**
+	 * Retrieve the fetch descriptor associated with the given entity key.
+	 *
+	 * @param key The entity key for which to locate any defined subselect fetch.
+	 * @return The fetch descriptor; may return null if no subselect fetch queued for
+	 * this entity key.
+	 */
 	public SubselectFetch getSubselect(EntityKey key) {
 		return (SubselectFetch) subselectsByEntityKey.get(key);
 	}
 
+	/**
+	 * Adds a subselect fetch decriptor for the given entity key.
+	 *
+	 * @param key The entity for which to register the subselect fetch.
+	 * @param subquery The fetch descriptor.
+	 */
 	public void addSubselect(EntityKey key, SubselectFetch subquery) {
 		subselectsByEntityKey.put(key, subquery);
 	}
 
-	public void clearSubselects() {
-		subselectsByEntityKey.clear();
-	}
-
 	/**
-	 * After evicting or deleting or loading an entity, we don't
-	 * need to batch fetch it anymore, remove it from the queue
-	 * if necessary
-	 */
-	public void removeBatchLoadableEntityKey(EntityKey key) {
-		if ( key.isBatchLoadable() ) batchLoadableEntityKeys.remove(key);
-	}
-
-	/**
 	 * After evicting or deleting an entity, we don't need to
 	 * know the query that was used to load it anymore (don't
 	 * call this after loading the entity, since we might still
@@ -76,14 +97,40 @@
 	}
 
 	/**
+	 * Clears all pending subselect fetches from the queue.
+	 * <p/>
+	 * Called after flushing.
+	 */
+	public void clearSubselects() {
+		subselectsByEntityKey.clear();
+	}
+
+	/**
 	 * If an EntityKey represents a batch loadable entity, add
 	 * it to the queue.
+	 * <p/>
+	 * Note that the contract here is such that any key passed in should
+	 * previously have been been checked for existence within the
+	 * {@link PersistenceContext}; failure to do so may cause the
+	 * referenced entity to be included in a batch even though it is
+	 * already associated with the {@link PersistenceContext}.
 	 */
 	public void addBatchLoadableEntityKey(EntityKey key) {
-		if ( key.isBatchLoadable() ) batchLoadableEntityKeys.put(key, MARKER);
+		if ( key.isBatchLoadable() ) {
+			batchLoadableEntityKeys.put( key, MARKER );
+		}
 	}
 
 	/**
+	 * After evicting or deleting or loading an entity, we don't
+	 * need to batch fetch it anymore, remove it from the queue
+	 * if necessary
+	 */
+	public void removeBatchLoadableEntityKey(EntityKey key) {
+		if ( key.isBatchLoadable() ) batchLoadableEntityKeys.remove(key);
+	}
+
+	/**
 	 * Get a batch of uninitialized collection keys for a given role
 	 *
 	 * @param collectionPersister The persister for the collection role.