improve javadoc of "pooled" optimizers

Author: gavinking

hibernate-core/src/main/java/org/hibernate/id/enhanced/PooledLoOptimizer.java

@@ -17,12 +17,27 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * Variation of {@link PooledOptimizer} which interprets the incoming database
- * value as the lo value, rather than the hi value.
+ * Optimizer which uses a pool of values, backed by a <em>logical sequence</em>.
+ * A logical sequence is usually just an unpooled sequence or table generator.
+ * <p>
+ * The pool size is controlled by the {@code allocationSize} of a
+ * {@linkplain jakarta.persistence.SequenceGenerator sequence generator} or
+ * {@linkplain jakarta.persistence.TableGenerator sequence generator}.
+ * <p>
+ * From time to time, the optimizer allocates a range of values to itself,
+ * interpreting the next value retrieved from the logical sequence as the
+ * lower bound on the range of newly allocated ids. Thus, the generated ids
+ * begin with the value retrieved from the logical sequence.
+ * <p>
+ * The {@link PooledOptimizer} is similar, but interprets the current value
+ * of the logical sequence as an upper bound on the range of already-allocated
+ * ids.
  *
  * @author Steve Ebersole
  *
  * @see PooledOptimizer
+ * @see jakarta.persistence.SequenceGenerator#allocationSize
+ * @see jakarta.persistence.TableGenerator#allocationSize
  */
 public class PooledLoOptimizer extends AbstractOptimizer {
 

hibernate-core/src/main/java/org/hibernate/id/enhanced/PooledOptimizer.java

@@ -20,18 +20,33 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * Optimizer which uses a pool of values, storing the next low value of the range
- * in the database.
+ * Optimizer which uses a pool of values, backed by a <em>logical sequence</em>.
+ * A logical sequence is usually just an unpooled sequence or table generator.
  * <p>
- * This optimizer works essentially the same as the {@link HiLoOptimizer}, except
- * that here the bucket ranges are actually encoded into the database structures.
+ * The pool size is controlled by the {@code allocationSize} of a
+ * {@linkplain jakarta.persistence.SequenceGenerator sequence generator} or
+ * {@linkplain jakarta.persistence.TableGenerator sequence generator}.
  * <p>
- * If you prefer that the database value be interpreted as the bottom end of our
- * current range, then use the {@link PooledLoOptimizer} strategy.
+ * This optimizer interprets the current value held by its underlying logical
+ * sequence (that is, the last value generated by a database sequence, or the
+ * current value of a table row emulating a sequence) as an upper bound on the
+ * range of already-allocated ids. From time to time, the optimizer allocates
+ * a range of values to itself, interpreting the next value retrieved from the
+ * logical sequence as an upper bound on the range of newly allocated ids.
+ * <p>
+ * The {@link PooledLoOptimizer} is similar, but interprets the current value
+ * of the logical sequence as a lower bound on the range of already-allocated
+ * ids.
+ * <p>
+ * This optimizer has similar performance characteristics to the
+ * {@link HiLoOptimizer}, but here the range bounds are stored directly by the
+ * underlying database structures.
  *
  * @author Steve Ebersole
  *
  * @see PooledLoOptimizer
+ * @see jakarta.persistence.SequenceGenerator#allocationSize
+ * @see jakarta.persistence.TableGenerator#allocationSize
  */
 public class PooledOptimizer extends AbstractOptimizer implements InitialValueAwareOptimizer {