From 3381ac28872aa944bad5300152f6dc36fc12974f Mon Sep 17 00:00:00 2001 From: Gavin Date: Fri, 30 Dec 2022 16:04:17 +0100 Subject: [PATCH] document natural ids and generators in annotations package --- .../org/hibernate/annotations/Cascade.java | 2 +- .../hibernate/annotations/Nationalized.java | 4 +- .../hibernate/annotations/package-info.java | 69 +++++++++++++++++-- .../org/hibernate/cfg/AvailableSettings.java | 1 + 4 files changed, 67 insertions(+), 9 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java b/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java index ea07bac27d..f1f6783032 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java @@ -22,7 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * {@link jakarta.persistence.OneToMany#cascade()}. The only * good reason to use it over the standard JPA approach is * to enable {@linkplain CascadeType#LOCK lock cascading}, - * by writing, for example, {@code Cascade(LOCK)}. + * by writing, for example, {@code @Cascade(LOCK)}. *

* If an association specified cascade types using both the * JPA association mapping annotations and this annotation, diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Nationalized.java b/hibernate-core/src/main/java/org/hibernate/annotations/Nationalized.java index 90cf36027e..085c8e2a39 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Nationalized.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Nationalized.java @@ -18,16 +18,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; /** * Specifies that the annotated character data should be stored with * nationalization support. The effect of this annotation depends on - * {@link Dialect#getNationalizationSupport() the SQL dialect}. + * {@linkplain Dialect#getNationalizationSupport() the SQL dialect}. *

* diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java index 43ad669e9b..d122396ccc 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java @@ -7,6 +7,9 @@ /** * A set of mapping annotations which extend the O/R mapping annotations defined by JPA. + *

+ * The JPA specification perfectly nails many aspects of the O/R persistence problem, but + * here we address some areas where it falls short. * *

Basic value type mappings

* @@ -76,14 +79,16 @@ * * *

- * JPA provides only {@linkplain jakarta.persistence.AttributeConverter converters} as a - * solution when the built-in types are insufficient. + * JPA does provide {@linkplain jakarta.persistence.AttributeConverter converters} as an + * extensibility mechanism, but its converters are only useful for classes which have an + * equivalent representation as one of the types listed above. *

* By contrast, Hibernate has an embarrassingly rich set of abstractions for modelling - * basic types, which can be initially confusing. Note that the venerable interface - * {@link org.hibernate.type.Type} abstracts over all sorts of field and property types, - * not only basic types. In modern Hibernate, programs should avoid directly implementing - * this interface. + * basic types, which can be initially confusing. + *

+ * Note that the venerable interface {@link org.hibernate.type.Type} abstracts over all + * sorts of field and property types, not only basic types. In modern Hibernate, programs + * should avoid direct use of this interface. *

* Instead, a program should use either a "compositional" basic type, or in more extreme * cases, a {@code UserType}. @@ -124,6 +129,7 @@ * interface and associate it with a field or property explicitly using the * {@link org.hibernate.annotations.Type @Type} annotation, or implicitly using the * {@link org.hibernate.annotations.TypeRegistration @TypeRegistration} annotation. + *

* There are some specialized flavors of the {@code @Type} annotation too. * * @@ -135,7 +141,7 @@ * {@link org.hibernate.type.descriptor.jdbc} contain the built-in implementations of * {@code JavaType} and {@code JdbcType}, respectively. *

- * Please see the User Guide or the package {@link org.hibernate.type} for further + * See the User Guide or the package {@link org.hibernate.type} for further * discussion. * *

Second level cache

@@ -170,6 +176,55 @@ * {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices * advocated above. * + *

Generated values

+ * + * JPA supports {@linkplain jakarta.persistence.GeneratedValue generated} identifiers, + * that is, surrogate primary keys, with four useful built-in + * {@linkplain jakarta.persistence.GenerationType types} of id generation. + *

+ * In JPA, an id generator is identified on the basis of a stringly-typed name, and + * this provides a reasonably natural way to integrate + * {@linkplain org.hibernate.annotations.GenericGenerator custom generators}. + *

+ * JPA does not define any way to generate the values of other fields or properties + * of the entity. + *

+ * Hibernate 6 takes a different route, which is both more typesafe, and much more + * extensible. + *

    + *
  1. The interfaces {@link org.hibernate.generator.BeforeExecutionGenerator} + * and {@link org.hibernate.generator.OnExecutionGenerator} provide an extremely + * open-ended way to incorporate custom generators. + *
  2. The meta-annotations {@link org.hibernate.annotations.IdGeneratorType} and + * {@link org.hibernate.annotations.ValueGenerationType} may be used to associate + * a generator with a user-defined annotation. This annotation is an indirection + * between the generator itself, and the persistent attributes it generates. + *
  3. This generator annotation may then by used to annotate {@code @Id} + * attributes, {@code @Version} attributes, and other {@code @Basic} attributes to + * specify how their values are generated. + *
+ *

+ * This package includes a number built-in generator annotations, including + * {@link org.hibernate.annotations.UuidGenerator}, + * {@link org.hibernate.annotations.CurrentTimestamp}, + * {@link org.hibernate.annotations.TenantId}, + * {@link org.hibernate.annotations.Generated}, and + * {@link org.hibernate.annotations.GeneratedColumn}. + * + *

Natural ids

+ * + * The use of surrogate keys is highly recommended, making it much easier to evolve + * a database schema over time. But every entity should also have a "natural" unique + * key: a subset of fields which, taken together, uniquely identify an instance of + * the entity in the business or scientific domain. + *

+ * The {@link org.hibernate.annotations.NaturalId} annotation is used to identify + * the natural key of an entity, and urge its use. + *

+ * The {@link org.hibernate.annotations.NaturalIdCache} annotation enables the use + * of the second-level cache for when an entity is loaded by natural id. Retrieval + * by natural id is a very common thing to do, and so the cache can often be helpful. + * *

Filters

* * Filters are an extremely powerful feature of Hibernate, allowing the definition of 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 9bbf6963b9..5018a24cdb 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java @@ -747,6 +747,7 @@ public interface AvailableSettings { * type when no column type is explicitly specified using * {@link jakarta.persistence.Column#columnDefinition()}. * + *

* This setting is disabled by default, and so Unicode character data * may not be persisted correctly for databases with explicit nationalization * support.