improve javadoc of "pooled" optimizers

Author: gavinking

hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java

@@ -118,12 +118,20 @@ public interface MappingSettings {
 	String KEYWORD_AUTO_QUOTING_ENABLED = "hibernate.auto_quote_keyword";
 
 	/**
-	 * When a generator specifies an increment size and an optimizer was not explicitly
-	 * specified, which of the "pooled" optimizers should be preferred? Can specify an
-	 * optimizer short name or the name of a class which implements
-	 * {@link org.hibernate.id.enhanced.Optimizer}.
+	 * Specifies an {@linkplain org.hibernate.id.enhanced.Optimizer optimizer}
+	 * which should be used when a generator specifies an {@code allocationSize}
+	 * and no optimizer is not explicitly specified, either:
+	 * <ul>
+	 * <li>a class implementing {@link org.hibernate.id.enhanced.Optimizer},
+	 * <li>the name of a class implementing {@code Optimizer}, or</li>
+	 * <li>an {@linkplain StandardOptimizerDescriptor optimizer short name}.
+	 * </ul>
 	 *
 	 * @settingDefault {@link StandardOptimizerDescriptor#POOLED}
+	 *
+	 * @see org.hibernate.id.enhanced.PooledOptimizer
+	 * @see org.hibernate.id.enhanced.PooledLoOptimizer
+	 * @see org.hibernate.id.enhanced.HiLoOptimizer
 	 */
 	String PREFERRED_POOLED_OPTIMIZER = "hibernate.id.optimizer.pooled.preferred";
 

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

@@ -15,13 +15,18 @@
  * this optimization takes the form of trying to ensure we do not have to
  * hit the database on each and every request to get an identifier value.
  * <p>
+ * An optimizer may be selected by setting the configuration property
+ * {@value org.hibernate.cfg.MappingSettings#PREFERRED_POOLED_OPTIMIZER}.
+ * <p>
  * Optimizers work on constructor injection. They should provide a
  * constructor accepting the following arguments:
  * <ol>
  * <li>{@code java.lang.Class} - The return type for the generated values</li>
  * <li>{@code int} - The increment size</li>
  * </ol>
  *
+ * @see org.hibernate.cfg.MappingSettings#PREFERRED_POOLED_OPTIMIZER
+ *
  * @author Steve Ebersole
  */
 public interface Optimizer {

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 {