From d08498109b07420ec645bc6df1df54acad70b570 Mon Sep 17 00:00:00 2001 From: Gavin Date: Wed, 7 Dec 2022 23:55:59 +0100 Subject: [PATCH] jdoc for schema management Action + for JDBC_TIME_ZONE --- .../org/hibernate/cfg/AvailableSettings.java | 16 +++- .../org/hibernate/tool/schema/Action.java | 80 +++++++++++++------ 2 files changed, 67 insertions(+), 29 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java index 7e9edc34d4..20cc9fcea6 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java +++ b/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)} - * when binding parameters. + * {@link java.sql.PreparedStatement#setTime(int, java.sql.Time, java.util.Calendar)}, + * {@link java.sql.ResultSet#getTimestamp(int, Calendar)}, and + * {@link java.sql.ResultSet#getTime(int, Calendar)} when binding parameters. *

+ * The time zone may be given as: + *

* 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}. *

* Interpreted in combination with {@link #JAKARTA_HBM2DDL_DATABASE_ACTION} and * {@link #JAKARTA_HBM2DDL_SCRIPTS_ACTION}. If no value is specified, the default diff --git a/hibernate-core/src/main/java/org/hibernate/tool/schema/Action.java b/hibernate-core/src/main/java/org/hibernate/tool/schema/Action.java index 7779898d7c..cf9b226baa 100644 --- a/hibernate-core/src/main/java/org/hibernate/tool/schema/Action.java +++ b/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 - * cases. + * Enumerates the actions that may be performed by the + * {@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. + *

* * @author Steve Ebersole */ public enum Action { /** - * No action will be performed. Valid in JPA; compatible with Hibernate's - * hbm2ddl action of the same name. + * No action. + *

+ * 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 - * legacy hbm2ddl had no such action - its "create" action is actually equivalent to {@link #CREATE} + * Create the schema. *

- * 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. *

- * 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. - *

- * Corresponds to a call to {@link org.hibernate.tool.schema.spi.SchemaDropper} - * followed immediately by a call to {@link org.hibernate.tool.schema.spi.SchemaCreator} + * Drop and then recreate the schema. + * + * @see org.hibernate.tool.schema.spi.SchemaDropper + * @see org.hibernate.tool.schema.spi.SchemaCreator */ CREATE( "drop-and-create", "create" ), /** - * Drop the schema and recreate it on SessionFactory startup. Additionally, drop the - * schema on SessionFactory shutdown. + * Drop the schema and then recreate it on {@code SessionFactory} startup. + * Additionally, drop the schema on {@code SessionFactory} shutdown. *

- * Has no corresponding call to a SchemaManagementTool delegate. It is equivalent to a - * + * This action is not defined by JPA. *

- * While this is a valid option for auto schema tooling, it is not a valid action to pass to - * SchemaManagementTool; instead it would be expected that the caller to SchemaManagementTool - * would split this into 2 separate requests for:

    - *
  1. {@link #CREATE}
    2. - *
  2. {@link #DROP}
    3. + * While this is a valid option for auto schema tooling, it's not a + * valid action for the {@code SchemaManagementTool}; instead the + * caller of {@code SchemaManagementTool} must split this into two + * separate requests to: + *
      + *
    1. {@linkplain #CREATE drop and create} the schema, and then
      2. + *
    2. later, {@linkplain #DROP drop} the schema again.
      3. *
    + * + * @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. + *

    + * 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. + *

    + * This action is not defined by JPA. + * + * @see org.hibernate.tool.schema.spi.SchemaMigrator */ UPDATE( null, "update" ), /** * Truncate the tables in the schema. + *

    + * 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);