package-level @SequenceGenerator and @TableGenerator

see #511

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

@@ -4900,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 {
@@ -4979,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();
@@ -5107,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
@@ -5119,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 {
@@ -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 "";