jdoc for schema management Action + for JDBC_TIME_ZONE

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

@@ -6,6 +6,7 @@
  */
 package org.hibernate.cfg;
 
+import java.util.Calendar;
 import java.util.function.Supplier;
 
 import org.hibernate.CustomEntityDirtinessStrategy;
@@ -1025,11 +1026,18 @@ public interface AvailableSettings {
 	String BATCH_VERSIONED_DATA = "hibernate.jdbc.batch_versioned_data";
 
 	/**
-	 * Specify a {@linkplain java.util.TimeZone time zone} that should be passed to
+	 * Specifies a {@linkplain java.util.TimeZone time zone} that should be passed to
 	 * {@link java.sql.PreparedStatement#setTimestamp(int, java.sql.Timestamp, java.util.Calendar)}
-	 * and {@link java.sql.PreparedStatement#setTime(int, java.sql.Time, java.util.Calendar)}
+	 * {@link java.sql.PreparedStatement#setTime(int, java.sql.Time, java.util.Calendar)},
-	 * when binding parameters.
+	 * {@link java.sql.ResultSet#getTimestamp(int, Calendar)}, and
+	 * {@link java.sql.ResultSet#getTime(int, Calendar)} when binding parameters.
 	 * <p>
+	 * The time zone may be given as:
+	 * <ul>
+	 *     <li>an instance of {@link java.util.TimeZone},
+	 *     <li>an instance of {@link java.time.ZoneId}, or
+	 *     <li>a time zone ID string to be passed to {@link java.time.ZoneId#of(String)}.
+	 * </ul>
 	 * By default, the {@linkplain java.util.TimeZone#getDefault() JVM default time zone}
 	 * is assumed by the JDBC driver.
 	 *
@@ -1505,7 +1513,7 @@ public interface AvailableSettings {
 	/**
 	 * Setting to perform {@link org.hibernate.tool.schema.spi.SchemaManagementTool}
 	 * actions automatically as part of the {@link org.hibernate.SessionFactory}
-	 * lifecycle. Valid options are enumeratd by {@link org.hibernate.tool.schema.Action}.
+	 * lifecycle. Valid options are enumerated by {@link org.hibernate.tool.schema.Action}.
 	 * <p>
 	 * Interpreted in combination with {@link #JAKARTA_HBM2DDL_DATABASE_ACTION} and
 	 * {@link #JAKARTA_HBM2DDL_SCRIPTS_ACTION}. If no value is specified, the default

hibernate-core/src/main/java/org/hibernate/tool/schema/Action.java

@@ -7,64 +7,94 @@
 package org.hibernate.tool.schema;
 
 /**
- * The allowable actions in terms of schema tooling.  Covers the unified JPA and HBM2DDL
+ * Enumerates the actions that may be performed by the
- * cases.
+ * {@linkplain org.hibernate.tool.schema.spi.SchemaManagementTool schema management tooling}.
+ * Covers the actions defined by JPA, those defined by Hibernate's legacy HBM2DDL tool, and
+ * several useful actions supported by Hibernate which are not covered by the JPA specification.
+ * <ul>
+ * <li>An action to be executed against the database may be specified using the configuration
+ *     property {@value org.hibernate.cfg.AvailableSettings#JAKARTA_HBM2DDL_DATABASE_ACTION}
+ *     or using the property {@value org.hibernate.cfg.AvailableSettings#HBM2DDL_AUTO}.
+ * <li>An action to be written to a script may be specified using the configuration property
+ *     {@value org.hibernate.cfg.AvailableSettings#JAKARTA_HBM2DDL_SCRIPTS_ACTION}.
+ * </ul>
  *
  * @author Steve Ebersole
  */
 public enum Action {
 	/**
-	 * No action will be performed.  Valid in JPA; compatible with Hibernate's
+	 * No action.
-	 * hbm2ddl action of the same name.
+	 * <p>
+	 * Valid in JPA; compatible with Hibernate's HBM2DDL action of the same name.
 	 */
 	NONE( "none" ),
 	/**
-	 * Database creation will be generated.  This is an action introduced by JPA.  Hibernate's
+	 * Create the schema.
-	 * legacy hbm2ddl had no such action - its "create" action is actually equivalent to {@link #CREATE}
 	 * <p>
-	 * Corresponds to a call to {@link org.hibernate.tool.schema.spi.SchemaCreator}
+	 * This is an action introduced by JPA; Hibernate's legacy HBM2DDL had no such
+	 * action. Its "create" action was actually equivalent to {@link #CREATE}.
+	 *
+	 * @see org.hibernate.tool.schema.spi.SchemaCreator
 	 */
 	CREATE_ONLY( "create", "create-only" ),
 	/**
-	 * Database dropping will be generated.
+	 * Drop the schema.
 	 * <p>
-	 * Corresponds to a call to {@link org.hibernate.tool.schema.spi.SchemaDropper}
+	 * Valid in JPA; compatible with Hibernate's HBM2DDL action of the same name.
+	 *
+	 * @see org.hibernate.tool.schema.spi.SchemaDropper
 	 */
 	DROP( "drop" ),
 	/**
-	 * Database dropping will be generated followed by database creation.
+	 * Drop and then recreate the schema.
-	 * <p>
+	 *
-	 * Corresponds to a call to {@link org.hibernate.tool.schema.spi.SchemaDropper}
+	 * @see org.hibernate.tool.schema.spi.SchemaDropper
-	 * followed immediately by a call to {@link org.hibernate.tool.schema.spi.SchemaCreator}
+	 * @see org.hibernate.tool.schema.spi.SchemaCreator
 	 */
 	CREATE( "drop-and-create", "create" ),
 	/**
-	 * Drop the schema and recreate it on SessionFactory startup.  Additionally, drop the
+	 * Drop the schema and then recreate it on {@code SessionFactory} startup.
-	 * schema on SessionFactory shutdown.
+	 * Additionally, drop the schema on {@code SessionFactory} shutdown.
 	 * <p>
-	 * Has no corresponding call to a SchemaManagementTool delegate.  It is equivalent to a
+	 * This action is not defined by JPA.
-	 *
 	 * <p>
-	 * While this is a valid option for auto schema tooling, it is not a valid action to pass to
+	 * While this is a valid option for auto schema tooling, it's not a
-	 * SchemaManagementTool; instead it would be expected that the caller to SchemaManagementTool
+	 * valid action for the {@code SchemaManagementTool}; instead the
-	 * would split this into 2 separate requests for:<ol>
+	 * caller of {@code SchemaManagementTool} must split this into two
-	 *     <li>{@link #CREATE}</li>
+	 * separate requests to:
-	 *     <li>{@link #DROP}</li>
+	 * <ol>
+	 *     <li>{@linkplain #CREATE drop and create} the schema, and then</li>
+	 *     <li>later, {@linkplain #DROP drop} the schema again.</li>
 	 * </ol>
+	 *
+	 * @see org.hibernate.tool.schema.spi.SchemaDropper
+	 * @see org.hibernate.tool.schema.spi.SchemaCreator
 	 */
 	CREATE_DROP( null, "create-drop" ),
 	/**
-	 * "validate" (Hibernate only) - validate the database schema
+	 * Validate the database schema.
+	 * <p>
+	 * This action is not defined by JPA.
+	 *
+	 * @see org.hibernate.tool.schema.spi.SchemaValidator
 	 */
 	VALIDATE( null, "validate" ),
 	/**
-	 * "update" (Hibernate only) - update (alter) the database schema
+	 * Update (alter) the database schema.
+	 * <p>
+	 * This action is not defined by JPA.
+	 *
+	 * @see org.hibernate.tool.schema.spi.SchemaMigrator
 	 */
 	UPDATE( null, "update" ),
 	/**
 	 * Truncate the tables in the schema.
+	 * <p>
+	 * This action is not defined by JPA.
 	 *
-	 * Corresponds to a call to {@link org.hibernate.tool.schema.spi.SchemaTruncator}.
+	 * @see org.hibernate.tool.schema.spi.SchemaTruncator
+	 *
+	 * @since 6.2
 	 */
 	TRUNCATE( null, null);