javadoc for @GeneratorType and @GenericGenerator

hibernate-core/src/main/java/org/hibernate/annotations/GeneratorType.java

@@ -11,18 +11,35 @@
 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.
+ * <p>
+ * 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.
+ * <p>
+ * This annotation is only useful for values generated in the Java code,
+ * and it is not used for generating the values of entity identifiers:
+ * <ul>
+ * <li>For identifier generators, use {@link GenericGenerator} or
+ *     {@link IdGeneratorType}.
+ * <li>If the value of a field or property is generated by the database
+ *     when an {@code insert} or {@code update} statement is executed,
+ *     use the {@link Generated} annotation.
+ * </ul>
  *
  * @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 @@
 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<? extends ValueGenerator<?>> 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:
+	 * <ul>
+	 * <li>If {@link GenerationTime#INSERT}, the value will be generated before
+	 *     each SQL {@code insert} statement is executed.
+	 * <li>If {@link GenerationTime#UPDATE}, the value will be generated before
+	 *     each SQL {@code update} statement is executed.
+	 * <li>If {@link GenerationTime#ALWAYS}, the value will be generated before
+	 *     each SQL {@code insert} or {@code update} statement is executed.
+	 * </ul>
 	 */
 	GenerationTime when() default GenerationTime.ALWAYS;
 }

hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java

@@ -5,6 +5,7 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 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.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:
+ * <ul>
+ * <li>defining a named generator using this annotation, then
+ * <li>annotating the identifier property of the entity with the JPA-defined
+ *     {@link jakarta.persistence.GeneratedValue @GeneratedValue} annotation,
+ *     and
+ * <li>using {@link jakarta.persistence.GeneratedValue#generator() generator}
+ *     to specify the {@link #name()} of the generator defined using this
+ *     annotation.
+ * </ul>
+ * For example, if we define a generator using:
+ * <pre>{@code
+ * @GenericGenerator(name = "custom-generator",
+ *                   strategy = "org.hibernate.eg.CustomStringGenerator")
+ * }</pre>
+ * Then we may make use of it by annotating an identifier field as follows:
+ * <pre>{@code
+ * @Id @GeneratedValue(generator = "custom-generator")
+ * private String id;
+ * }</pre>
  * <p>
- * 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 @@
 @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:
+	 * <ul>
+ *     <li>the name of a built-in Hibernate id generator, or
+	 * <li>a custom class implementing {@link org.hibernate.id.IdentifierGenerator}.
+	 * </ul>
 	 */
 	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 {};
 }