From 3bab26739d13b7380e5e1e261183ba916e047153 Mon Sep 17 00:00:00 2001 From: Gavin Date: Tue, 29 Nov 2022 22:29:29 +0100 Subject: [PATCH] javadoc for @GeneratorType and @GenericGenerator --- .../hibernate/annotations/GeneratorType.java | 41 ++++++++++++---- .../annotations/GenericGenerator.java | 47 ++++++++++++++++--- 2 files changed, 73 insertions(+), 15 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GeneratorType.java b/hibernate-core/src/main/java/org/hibernate/annotations/GeneratorType.java index 29667cb17e..a07875d739 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/GeneratorType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/GeneratorType.java @@ -11,18 +11,35 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import org.hibernate.Session; import org.hibernate.tuple.AnnotationValueGeneration; import org.hibernate.tuple.ValueGenerator; import org.hibernate.tuple.VmValueGeneration; /** - * Marks a property as generated, specifying the {@link ValueGenerator} type to be used for generating the value. It is - * the responsibility of the client to ensure that a generator type is specified which matches the data type of the - * annotated property. + * Marks a field or property of an entity as automatically generated by + * code written in Java, before any SQL statement to {@code insert} or + * {@code update} the entity is executed, specifying an implementation + * of {@link ValueGenerator} used for generating its values. + *

+ * It is the responsibility of the client to ensure that a specified + * {@linkplain #type generator type} produces values which are assignable + * to the annotated property. + *

+ * This annotation is only useful for values generated in the Java code, + * and it is not used for generating the values of entity identifiers: + *

* * @author Gunnar Morling * - * @deprecated Most uses can be changed to use {@link ValueGenerationType} + {@link AnnotationValueGeneration} + * @deprecated {@link ValueGenerationType} and {@link AnnotationValueGeneration} + * now provide a much more powerful and typesafe alternative */ @ValueGenerationType( generatedBy = VmValueGeneration.class ) @Retention( RetentionPolicy.RUNTIME ) @@ -31,16 +48,24 @@ import org.hibernate.tuple.VmValueGeneration; public @interface GeneratorType { /** - * The value generator type + * A class that implements {@link ValueGenerator}, which will be called to + * {@linkplain ValueGenerator#generateValue(Session, Object) generate values} + * of the annotated field or property. * * @return the value generator type */ Class> type(); /** - * When to generate the value, either only during insert or during insert and update of the hosting entity. - * - * @return the time of generation + * Specifies when values should be generated: + * */ GenerationTime when() default GenerationTime.ALWAYS; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java index 6b1bb35dc3..d1f4b1c542 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java @@ -5,6 +5,7 @@ * See the lgpl.txt file in the root directory or . */ package org.hibernate.annotations; + import java.lang.annotation.Repeatable; import java.lang.annotation.Retention; import java.lang.annotation.Target; @@ -16,11 +17,34 @@ import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; /** - * Generator annotation describing any kind of Hibernate generator in a - * generic (de-typed) manner. + * Defines a named identifier generator, an instance of the interface + * {@link org.hibernate.id.IdentifierGenerator}. A named generator may be + * associated with an entity class by: + * + * For example, if we define a generator using: + * 
{@code
+ * @GenericGenerator(name = "custom-generator",
+ *                   strategy = "org.hibernate.eg.CustomStringGenerator")
+ * }
+ * Then we may make use of it by annotating an identifier field as follows: + * 
{@code
+ * @Id @GeneratedValue(generator = "custom-generator")
+ * private String id;
+ * }
*

- * For a more type-safe way to specify generators in annotations, see - * {@link IdGeneratorType} + * The disadvantage of this approach is the use of stringly-typed names. An + * alternative, completely typesafe, way to declare a generator and associate + * it with an entity is provided by the {@link IdGeneratorType} meta-annotation. + * + * @see jakarta.persistence.GeneratedValue * * @author Emmanuel Bernard */ @@ -29,15 +53,24 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Repeatable(GenericGenerators.class) public @interface GenericGenerator { /** - * unique generator name. + * The name of the identifier generator. This is the name that may be specified by + * the {@link jakarta.persistence.GeneratedValue#generator() generator} member of + * the {@code @GeneratedValue} annotation. + * + * @see jakarta.persistence.GeneratedValue#generator */ String name(); /** - * Generator strategy either a predefined Hibernate strategy or a fully qualified class name. + * The type of identifier generator, either: + *

*/ String strategy(); /** - * Optional generator parameters. + * Parameters to be passed to {@link org.hibernate.id.IdentifierGenerator#configure} + * when the identifier generator is instantiated. */ Parameter[] parameters() default {}; }