javadoc for @IdGeneratorType and @ValueGenerationType

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

@@ -6,9 +6,7 @@
  */
 package org.hibernate.annotations;
 
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.hibernate.Session;
@@ -16,6 +14,10 @@ import org.hibernate.tuple.AnnotationValueGeneration;
 import org.hibernate.tuple.ValueGenerator;
 import org.hibernate.tuple.VmValueGeneration;
 
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Marks a field or property of an entity as automatically generated by
  * code written in Java, before any SQL statement to {@code insert} or
@@ -42,8 +44,8 @@ import org.hibernate.tuple.VmValueGeneration;
  *             now provide a much more powerful and typesafe alternative
  */
 @ValueGenerationType( generatedBy = VmValueGeneration.class )
-@Retention( RetentionPolicy.RUNTIME )
-@Target( value = { ElementType.FIELD, ElementType.METHOD } )
+@Retention(RUNTIME)
+@Target({FIELD, METHOD})
 @Deprecated(since = "6.0")
 public @interface GeneratorType {
 

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

@@ -13,17 +13,66 @@ import java.lang.annotation.Target;
 
 import org.hibernate.id.IdentifierGenerator;
 
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Meta-annotation used to mark another annotation as providing configuration
- * for a custom {@link IdentifierGenerator}.
+ * for a custom {@link IdentifierGenerator}. This is the best way to work with
+ * customized identifier generation in Hibernate.
+ * <p>
+ * For example, if we have a custom identifier generator:
+ * <pre>{@code
+ * public class CustomSequenceGenerator implements IdentifierGenerator {
+ *     public CustomSequenceGenerator(CustomSequence config, Member annotatedMember,
+ *                                    CustomIdGeneratorCreationContext context) {
+ *         ...
+ *     }
+ *     ...
+ * }
+ * }</pre>
+ * Then we may also define an annotation which associates this generator with
+ * an entity and supplies configuration parameters:
+ * <pre>{@code
+ * @IdGeneratorType(CustomSequenceGenerator.class)
+ * @Retention(RUNTIME) @Target({METHOD,FIELD})
+ * public @interface CustomSequence {
+ *     String name();
+ *     int startWith() default 1;
+ *     int incrementBy() default 50;
+ * }
+ * }</pre>
+ * and we may use it as follows:
+ * <pre>{@code
+ * @Id @CustomSequence(name = "mysequence", startWith = 0)
+ * private Integer id;
+ * }</pre>
+ * We did not use the JPA-defined {@link jakarta.persistence.GeneratedValue}
+ * here, since that API is designed around the use of stringly-typed names.
+ * The {@code @CustomSequence} annotation itself implies that {@code id} is
+ * a generated value.
+ * <p>
+ * For a more complete example, see the annotation {@link UuidGenerator} and
+ * the corresponding generator class {@link org.hibernate.id.uuid.UuidGenerator}.
+ * <p>
+ * A {@code @IdGeneratorType} annotation must have retention policy
+ * {@link RetentionPolicy#RUNTIME}.
  *
  * @since 6.0
  */
-@Target( value = ElementType.ANNOTATION_TYPE )
-@Retention( RetentionPolicy.RUNTIME )
+@Target(ANNOTATION_TYPE)
+@Retention(RUNTIME)
 public @interface IdGeneratorType {
 	/**
-	 * The {@link IdentifierGenerator} being configured
+	 * A class that implements {@link IdentifierGenerator} and has a
+	 * constructor with the signature:
+	 * <pre>{@code
+	 * public GeneratorType(AnnotationType config, Member idMember,
+	 *                      CustomIdGeneratorCreationContext creationContext)
+	 * }</pre>
+	 * where {@code GeneratorType} is the class that implements
+	 * {@code IdentifierGenerator}, and {@code AnnotationType} is the
+	 * annotation type to which this annotation was applied.
 	 */
 	Class<? extends IdentifierGenerator> value();
 }

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

@@ -12,27 +12,54 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 import org.hibernate.tuple.AnnotationValueGeneration;
+import org.hibernate.tuple.ValueGeneration;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Marks an annotation type as a generator annotation type.
+ * Meta-annotation used to mark another annotation as providing configuration
+ * for a custom {@linkplain ValueGeneration value generation strategy}. This
+ * is the best way to work with customized value generation in Hibernate.
  * <p>
- * Adding a generator annotation to an entity property causes the value of the property to be generated upon insert
- * or update of the owning entity. Not more than one generator annotation may be placed on a given property.
+ * For example, if we have a custom value generator:
+ * <pre>{@code
+ * public class SKUGeneration implements AnnotationValueGeneration<SKU>, ValueGenerator<String> {
+ *     ...
+ * }
+ * }</pre>
+ * Then we may also define an annotation which associates this generator with
+ * a field or property of an entity and supplies configuration parameters:
+ * <pre>{@code
+ * @ValueGenerationType(generatedBy = SKUGeneration.class)
+ * @Retention(RUNTIME) @Target({METHOD,FIELD})
+ * public @interface SKU {}
+ * }</pre>
+ * and we may use it as follows:
+ * <pre>{@code @SKU String sku;}</pre>
+ * No more than one generator annotation may be placed on a given property.
  * <p>
- * Each generator annotation type is associated with a {@link AnnotationValueGeneration} which implements the strategy
- * for generating the value. Generator annotation types may define arbitrary custom attributes, e.g. allowing the
- * client to configure the generation timing (if applicable) or other settings taking an effect on the value generation.
- * The corresponding implementation can retrieve these settings from the annotation instance passed to
- * {@link AnnotationValueGeneration#initialize(java.lang.annotation.Annotation, Class)}.
+ * Adding a generator annotation to an entity property causes the value of the
+ * property to be generated when any SQL statement to {@code insert} or
+ * {@code update} the entity is executed.
  * <p>
- * Custom generator annotation types must have retention policy {@link RetentionPolicy#RUNTIME}.
-
+ * Each generator annotation type has an {@link AnnotationValueGeneration}
+ * implementation which is responsible for generating values. The generator
+ * annotation may have members, which are used to configure the generator,
+ * when {@link AnnotationValueGeneration#initialize} is called.
+ * <p>
+ * There are several excellent examples of the use of this machinery right
+ * here in this package. {@link TenantId} and its corresponding generator
+ * {@link org.hibernate.tuple.TenantIdGeneration} are a good place to start.
+ * <p>
+ * A {@code @ValueGenerationType} annotation must have retention policy
+ * {@link RetentionPolicy#RUNTIME}.
+ *
  * @author Gunnar Morling
  */
-@Target( value = ElementType.ANNOTATION_TYPE )
-@Retention( RetentionPolicy.RUNTIME )
+@Target(ANNOTATION_TYPE)
+@Retention(RUNTIME)
 public @interface ValueGenerationType {
-
 	/**
 	 * The type of value generation associated with the annotated value generator annotation type. The referenced
 	 * generation type must be parameterized with the type of the given generator annotation.