- * By default, the timestamp is generated by {@linkplain java.time.Clock#instant() in memory}, + * By default, the timestamp is generated by {@linkplain java.time.Clock#instant in memory}, * but this may be changed by explicitly specifying the {@link #source}. * Otherwise, this annotation is a synonym for * {@link CurrentTimestamp @CurrentTimestamp(timing=INSERT,source=VM)}. - * - * @author Gunnar Morling + *
+ * The annotated property may be of any one of the following types: + * {@link java.util.Date}, + * {@link java.util.Calendar}, + * {@link java.sql.Date}, + * {@link java.sql.Time}, + * {@link java.sql.Timestamp}, + * {@link java.time.Instant}, + * {@link java.time.LocalDate}, + * {@link java.time.LocalDateTime}, + * {@link java.time.LocalTime}, + * {@link java.time.MonthDay}, + * {@link java.time.OffsetDateTime}, + * {@link java.time.OffsetTime}, + * {@link java.time.Year}, + * {@link java.time.YearMonth}, or + * {@link java.time.ZonedDateTime}. + *
+ * A field annotated {@code @CreationTimestamp} may not be directly set by the application + * program. * * @see CurrentTimestamp + * @see UpdateTimestamp + * + * @author Gunnar Morling */ @ValueGenerationType(generatedBy = CurrentTimestampGeneration.class) @Retention(RUNTIME) @@ -32,7 +53,8 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration; public @interface CreationTimestamp { /** * Specifies how the timestamp is generated. By default, it is generated - * in memory, which saves a round trip to the database. + * in memory, which might save a round trip to the database, depending on + * the capabilities of the database and JDBC driver. */ SourceType source() default SourceType.VM; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java b/hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java index a464f6cd2d..2a02f5be66 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/CurrentTimestamp.java @@ -19,18 +19,20 @@ import static org.hibernate.generator.EventType.UPDATE; /** * Specifies that the annotated field of property is a generated timestamp, - * and also specifies the {@linkplain #event() timing} of the timestamp + * and also specifies the {@linkplain #event timing} of the timestamp * generation, and whether it is generated in Java or by the database: *
- * By default, the timestamp is generated by the database, which requires - * an extra round trip to the database to fetch the generated value. + * By default, the timestamp is generated by the database, which might + * require an extra round trip to the database to fetch the generated + * value, depending on the capabilities of the + * {@linkplain org.hibernate.dialect.Dialect#supportsInsertReturning database} and + * {@linkplain org.hibernate.dialect.Dialect#supportsInsertReturningGeneratedKeys driver}. *
* This annotation may be used in combination with the JPA-defined * {@link jakarta.persistence.Version} annotation. @@ -51,6 +53,9 @@ import static org.hibernate.generator.EventType.UPDATE; * {@link java.time.Year}, * {@link java.time.YearMonth}, or * {@link java.time.ZonedDateTime}. + *
+ * A field annotated {@code @CurrentTimestamp} may not be directly set + * by the application program. * * @see UpdateTimestamp * @see CreationTimestamp @@ -74,7 +79,10 @@ public @interface CurrentTimestamp { /** * Specifies how the timestamp is generated. By default, it is generated - * by the database, and fetched using a subsequent {@code select} statement. + * by the database. Depending on the capabilities of the database and JDBC + * driver, this might require that the value be fetched using a subsequent + * {@code select} statement. Setting {@code source = VM} guarantees that + * this additional {@code select} never occurs. */ SourceType source() default SourceType.DB; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/TenantId.java b/hibernate-core/src/main/java/org/hibernate/annotations/TenantId.java index abaded6ff7..770b124999 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/TenantId.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/TenantId.java @@ -15,9 +15,17 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Identifies a field of an entity that holds a tenant id - * in discriminator-based multitenancy. + * Identifies a field of an entity that holds a tenant id in discriminator-based multitenancy. + *
+ * A field annotated {@code @TenantId} is automatically set to the + * {@linkplain org.hibernate.SharedSessionContract#getTenantIdentifierValue current tenant id} + * when the entity is first made persistent. The {@code @TenantId} field may not be directly + * set by the application program. + *
+ * If a {@code @TenantId} field is also annotated {@link jakarta.persistence.Id @Id}, it forms + * part of the composite primary key of the of an entity. * + * @see org.hibernate.SharedSessionContract#getTenantIdentifierValue * @see org.hibernate.context.spi.CurrentTenantIdentifierResolver * * @since 6.0 diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/UpdateTimestamp.java b/hibernate-core/src/main/java/org/hibernate/annotations/UpdateTimestamp.java index e3cce198fd..4a2a866667 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/UpdateTimestamp.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/UpdateTimestamp.java @@ -17,12 +17,33 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration; * Specifies that the annotated field of property is a generated update timestamp. * The timestamp is regenerated every time an entity instance is updated in the database. *
- * By default, the timestamp is generated {@linkplain java.time.Clock#instant() in memory}, + * By default, the timestamp is generated {@linkplain java.time.Clock#instant in memory}, * but this may be changed by explicitly specifying the {@link #source}. * Otherwise, this annotation is a synonym for * {@link CurrentTimestamp @CurrentTimestamp(source=VM)}. + *
+ * The annotated property may be of any one of the following types: + * {@link java.util.Date}, + * {@link java.util.Calendar}, + * {@link java.sql.Date}, + * {@link java.sql.Time}, + * {@link java.sql.Timestamp}, + * {@link java.time.Instant}, + * {@link java.time.LocalDate}, + * {@link java.time.LocalDateTime}, + * {@link java.time.LocalTime}, + * {@link java.time.MonthDay}, + * {@link java.time.OffsetDateTime}, + * {@link java.time.OffsetTime}, + * {@link java.time.Year}, + * {@link java.time.YearMonth}, or + * {@link java.time.ZonedDateTime}. + *
+ * A field annotated {@code @UpdateTimestamp} may not be directly set by the application + * program. * * @see CurrentTimestamp + * @see CreationTimestamp * * @author Gunnar Morling */ @@ -32,7 +53,8 @@ import org.hibernate.generator.internal.CurrentTimestampGeneration; public @interface UpdateTimestamp { /** * Specifies how the timestamp is generated. By default, it is generated - * in memory, which saves a round trip to the database. + * in memory, which might save a round trip to the database, depending on + * the capabilities of the database and JDBC driver. */ SourceType source() default SourceType.VM; }