package-level @SequenceGenerator and @TableGenerator

api/src/main/java/jakarta/persistence/SequenceGenerator.java

@@ -22,6 +22,7 @@
 import java.lang.annotation.Retention;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -39,6 +40,16 @@
  * on an entity class or primary key attribute of an entity class,
  * then the name defaults to the name of the entity.
  *
+ * <p>If no name is explicitly specified, and the annotation occurs
+ * on a package descriptor, then the annotation defines a recipe for
+ * producing a default generator when a {@link GeneratedValue}
+ * annotation of any program element in the annotated package has
+ * {@link GeneratedValue#strategy strategy=SEQUENCE} and a defaulted
+ * {@linkplain GeneratedValue#generator generator name}. The name of
+ * this default generator is the defaulted generator name, and its
+ * other properties are determined by the members of the package
+ * {@code SequenceGenerator} annotation.
+ *
  * <p>Example:
  * <pre>
  *   &#064;SequenceGenerator(name="EMP_SEQ", allocationSize=25)
@@ -47,7 +58,7 @@
  * @since 1.0
  */
 @Repeatable(SequenceGenerators.class)
-@Target({TYPE, METHOD, FIELD}) 
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface SequenceGenerator {
 

api/src/main/java/jakarta/persistence/SequenceGenerators.java

@@ -17,6 +17,7 @@
 
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -29,7 +30,7 @@
  * @see SequenceGenerator
  * @since 2.2
  */
-@Target({TYPE, METHOD, FIELD}) 
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface SequenceGenerators {
 

api/src/main/java/jakarta/persistence/TableGenerator.java

@@ -22,6 +22,7 @@
 import java.lang.annotation.Retention;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -41,6 +42,16 @@
  * entity class, then the name defaults to the name of the
  * entity.
  *
+ * <p>If no name is explicitly specified, and the annotation occurs
+ * on a package descriptor, then the annotation defines a recipe for
+ * producing a default generator when a {@link GeneratedValue}
+ * annotation of any program element in the annotated package has
+ * {@link GeneratedValue#strategy strategy=TABLE} and a defaulted
+ * {@linkplain GeneratedValue#generator generator name}. The name of
+ * this default generator is the defaulted generator name, and its
+ * other properties are determined by the members of the package
+ * {@code TableGenerator} annotation.
+ *
  * <p>Example 1:
  * <pre>
  *    &#064;Entity public class Employee {
@@ -80,7 +91,7 @@
  * @since 1.0
  */
 @Repeatable(TableGenerators.class)
-@Target({TYPE, METHOD, FIELD}) 
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface TableGenerator {
 

api/src/main/java/jakarta/persistence/TableGenerators.java

@@ -17,6 +17,7 @@
 
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
@@ -29,7 +30,7 @@
  * @see TableGenerator
  * @since 2.2
  */
-@Target({TYPE, METHOD, FIELD}) 
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface TableGenerators {
 

spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc

@@ -1914,23 +1914,21 @@ the provider must not generate a foreign key constraint.
 
 ==== GeneratedValue Annotation [[a14790]]
 
-The _GeneratedValue_ annotation provides for
-the specification of generation strategies for the values of primary
-keys. The _GeneratedValue_ annotation may be applied to a primary key
-property or field of an entity or mapped superclass in conjunction with
-the _Id_ annotation.footnote:[Portable
-applications should not use the _GeneratedValue_ annotation on other
-persistent fields or properties.] The use of the
-_GeneratedValue_ annotation is only required to be supported for simple
-primary keys. Use of the _GeneratedValue_ annotation is not supported
-for derived primary keys.
-
-<<a14806>> lists the annotation elements that
-may be specified for the _GeneratedValue_ annotation and their default
-values.
+The _GeneratedValue_ annotation specifies a generation strategy for the
+values of primary keys. The _GeneratedValue_ annotation may be applied
+to a primary key property or field of an entity or mapped superclass in
+conjunction with the _Id_ annotation.footnote:[Portable applications
+should not use the _GeneratedValue_ annotation on other persistent
+fields or properties.] The persistence provider is only required to
+support the use of the _GeneratedValue_ annotation for simple primary
+keys. Use of the _GeneratedValue_ annotation for derived primary keys
+is not supported.
+
+<<a14806>> lists the annotation elements that may be specified for the
+_GeneratedValue_ annotation and their default values.
 
-The types of primary key generation are
-defined by the _GenerationType_ enum:
+The types of primary key generation are defined by the _GenerationType_
+enum:
 
 [source,java]
 ----
@@ -1952,8 +1950,8 @@ A _TABLE_, _SEQUENCE_, or _IDENTITY_ generator may be used to generate
 values for a primary key property or field of type _java.lang.Long_,
 _java.lang.Integer_, _long_, or _int_.
 
-The _UUID_ value indicates that the persistence provider should
-assign an RFC 4122 Universally Unique IDentifier.
+The _UUID_ value indicates that the persistence provider should assign
+an RFC 4122 Universally Unique IDentifier.
 
 A _UUID_ generator may be used to generate values for a primary key
 property or field of type _java.util.UUID_ or _java.lang.String_.
@@ -1971,15 +1969,20 @@ or it may attempt to create one. A vendor may provide documentation on
 how to create such resources in the event that it does not support
 schema generation or cannot create the schema resource at runtime.
 
-This specification does not define the exact
-behavior of these strategies.
+This specification does not define the exact behavior of these strategies.
 
 However, if the persistence provider stores a value generated according
 to the _UUID_ strategy in a column of type _VARCHAR_ or equivalent, the
 value must be stored in its canonical representation, unless the
 application explicitly indicates that some other representation is
 preferred.
 
+The _name_ member specifies the name of a generator to use, and defaults
+to the entity name of the entity in which the _GeneratedValue_ annotation
+occurs. If the _name_ is not specified, and if there is no generator with
+the defaulted name, then the persistence provider supplies a default id
+generator, of a type compatible with the value of the _strategy_ member.
+
 [source,java]
 ----
 @Target({METHOD, FIELD})
@@ -1997,17 +2000,16 @@ public @interface GeneratedValue {
 
 |GenerationType
 |strategy
-|(Optional) The primary key generation
-strategy that the persistence provider must use to generate the
-annotated entity primary key.
+|(Optional) The primary key generation strategy that the persistence
+provider must use to generate the annotated entity primary key.
 |GenerationType.AUTO
 
 |String
 |generator
-|(Optional) The name of the primary key
-generator to use as specified in the SequenceGenerator or TableGenerator
-annotation.
-|Default primary key generator supplied by persistence provider.
+|(Optional) The name of the primary key generator to use as specified
+in the _SequenceGenerator_ or _TableGenerator_ annotation which
+declares the generator.
+|The entity name of the entity in which the annotation occurs.
 |===
 
 *Example 1:*
@@ -4898,13 +4900,21 @@ and the annotation occurs on an entity class or primary key attribute of
 an entity class, then the name defaults to the name of the entity.
 Otherwise, if the annotation occurs elsewhere, the behavior is undefined.
 
-<<a16179>> lists the annotation elements
-that may be specified for the _SequenceGenerator_ annotation and their
-default values.
+If no name is explicitly specified by the _SequenceGenerator_ annotation,
+and the annotation occurs on a package descriptor, then the annotation
+defines a recipe for producing a default generator when a _GeneratedValue_
+annotation of any program element in the annotated package has
+_strategy=SEQUENCE_ and a defaulted _generator_ name. The name of this
+default generator is the defaulted generator name, and its other properties
+are determined by the members of the package-level _SequenceGenerator_
+annotation.
+
+<<a16179>> lists the annotation elements that may be specified for the
+_SequenceGenerator_ annotation and their default values.
 
 [source,java]
 ----
-@Target({TYPE, METHOD, FIELD})
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 @Repeatable(SequenceGenerators.class)
 public @interface SequenceGenerator {
@@ -4925,16 +4935,15 @@ public @interface SequenceGenerator {
 
 |String
 |name
-|(Required) A unique generator name that can
-be referenced by one or more classes to be the generator for primary key
-values.
-|
+|(Optional) A unique generator name that can be referenced by one or more
+classes to be the generator for primary key values.
+|See text above
 
 |String
 |sequenceName
-|(Optional) The name of the database sequence
-object from which to obtain primary key values.
-|A provider- chosen value
+|(Optional) The name of the database sequence object from which to obtain
+primary key values.
+|A provider-chosen sequence name
 
 |String
 |catalog
@@ -4978,7 +4987,7 @@ to specify multiple sequence generators.
 
 [source,java]
 ----
-@Target({TYPE, METHOD, FIELD})
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface SequenceGenerators {
     SequenceGenerator[] value();
@@ -5106,9 +5115,17 @@ and the annotation occurs on an entity class or primary key attribute
 of an entity class, then the name defaults to the name of the entity.
 Otherwise, if the annotation occurs elsewhere, the behavior is undefined.
 
-<<a162771>> lists the annotation elements that
-may be specified for the _TableGenerator_ annotation and their default
-values.
+If no name is explicitly specified by the _TableGenerator_ annotation,
+and the annotation occurs on a package descriptor, then the annotation
+defines a recipe for producing a default generator when a _GeneratedValue_
+annotation of any program element in the annotated package has
+_strategy=TABLE_ and a defaulted _generator_ name. The name of this
+default generator is the defaulted generator name, and its other properties
+are determined by the members of the package-level _TableGenerator_
+annotation.
+
+<<a162771>> lists the annotation elements that may be specified for the
+_TableGenerator_ annotation and their default values.
 
 The _table_ element specifies the name of the
 table that is used by the persistence provider to store generated
@@ -5118,7 +5135,7 @@ primary key values are normally positive integers.
 
 [source,java]
 ----
-@Target({TYPE, METHOD, FIELD})
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 @Repeatable(TableGenerators.class)
 public @interface TableGenerator {
@@ -5144,15 +5161,14 @@ public @interface TableGenerator {
 
 |String
 |name
-|(Required) A unique generator name that can be referenced by one or more classes
-to be the generator for primary key values.
-|
+|(Optional) A unique generator name that can be referenced by one or more
+classes to be the generator for primary key values.
+|See text above
 
 |String
 |table
-|(Optional) Name of table that stores the
-generated primary key values.
-|Name is chosen by persistence provider
+|(Optional) Name of table that stores the generated primary key values.
+|A provider-chosen table name
 
 |String
 |catalog
@@ -5265,7 +5281,7 @@ specify multiple table generators.
 
 [source,java]
 ----
-@Target({TYPE, METHOD, FIELD})
+@Target({TYPE, METHOD, FIELD, PACKAGE})
 @Retention(RUNTIME)
 public @interface TableGenerators {
     TableGenerator[] value();

spec/src/main/asciidoc/ch12-xml-or-mapping-descriptor.adoc

@@ -3046,7 +3046,7 @@ object/relational mapping schema for use with the persistence API.
     <xsd:annotation>
       <xsd:documentation>
 
-        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME)
         public @interface SequenceGenerator {
           String name() default "";
           String sequenceName() default "";
@@ -3155,7 +3155,7 @@ object/relational mapping schema for use with the persistence API.
     <xsd:annotation>
       <xsd:documentation>
 
-        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME)
         public @interface TableGenerator {
           String name() default "";
           String table() default "";