introduce comment and check, @CheckConstraint annotation (#382)

see #381

Co-authored-by: Lukas Jungmann <lukas.jungmann@oracle.com>

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

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King      - 3.2
+
+package jakarta.persistence;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Used to specify a SQL check constraint on a column or table
+ * when schema generation is in effect.
+ *
+ * @see Table#check()
+ * @see Column#check()
+ *
+ * @since 3.2
+ */
+@Target({})
+@Retention(RUNTIME)
+public @interface CheckConstraint {
+
+    /**
+     * (Optional) The name of the constraint; defaults to a provider-generated name.
+     */
+    String name() default "";
+
+    /**
+     * (Required) The native SQL expression to be checked.
+     */
+    String constraint();
+
+}

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

@@ -121,4 +121,20 @@
      * (Applies only if a decimal column is used.)
      */
     int scale() default 0;
+
+    /**
+     * (Optional) Check constraints to be applied to the column.
+     * These are only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    CheckConstraint[] check() default {};
+
+    /**
+     * (Optional) A comment to be applied to the column.
+     * This is only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    String comment() default "";
 }

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

@@ -183,4 +183,20 @@
      *  @since 2.1
      */
     ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
+
+    /**
+     * (Optional) Check constraints to be applied to the column.
+     * These are only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    CheckConstraint[] check() default {};
+
+    /**
+     * (Optional) A comment to be applied to the column.
+     * This is only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    String comment() default "";
 }

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

@@ -152,4 +152,20 @@
      * @since 2.1 
      */
     Index[] indexes() default {};
+
+    /**
+     * (Optional) Check constraints to be applied to the table.
+     * These are only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    CheckConstraint[] check() default {};
+
+    /**
+     * (Optional) A comment to be applied to the table.
+     * This is only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    String comment() default "";
 }

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

@@ -118,4 +118,20 @@
      * @since 2.1
      */
     Index[] indexes() default {};
+
+    /**
+     * (Optional) Check constraints to be applied to the table.
+     * These are only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    CheckConstraint[] check() default {};
+
+    /**
+     * (Optional) A comment to be applied to the table.
+     * This is only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    String comment() default "";
 }

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

@@ -78,4 +78,20 @@
      * @since 2.1
      */
     Index[] indexes() default {};
+
+    /**
+     * (Optional) Check constraints to be applied to the table.
+     * These are only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    CheckConstraint[] check() default {};
+
+    /**
+     * (Optional) A comment to be applied to the table.
+     * This is only used if table generation is in effect.
+     *
+     * @since 3.2
+     */
+    String comment() default "";
 }

spec/src/main/asciidoc/appendixes.adoc

@@ -124,6 +124,8 @@ Added _concat()_ overload accepting list of expressions to _CriteriaBuilder_
 
 Made the _name_ member of _TableGenerator_ and _SequenceGenerator_ optional
 
+Introduced _comment_ and _check_ members to table and column annotations, along with _CheckConstraint_
+
 Clarified the primary key types supported for each _GenerationType_
 
 Entity and embeddable classes may now be static inner classes

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

@@ -861,6 +861,8 @@ public @interface Column {
     int length() default 255;
     int precision() default 0; // decimal precision
     int scale() default 0; // decimal scale
+    CheckConstraint[] check() default {}
+    String comment() default "";
 }
 ----
 
@@ -934,6 +936,18 @@ if a string-valued column is used.)
 |(Optional) The scale for a decimal (exact
 numeric) column. (Applies only if a decimal column is used.)
 |0
+
+|CheckConstraint[]
+|check
+|(Optional) Check constraints for the column. These are
+only used if table generation is in effect.
+|No check constraint
+
+|String
+|comment
+|(Optional) Comment for the column. This is
+only used if table generation is in effect.
+|No comment
 |===
 
 *Example 1:*
@@ -2197,6 +2211,8 @@ public @interface JoinColumn {
     String columnDefinition() default "";
     String table() default "";
     ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
+    CheckConstraint[] check() default {}
+    String comment() default "";
 }
 ----
 
@@ -2291,6 +2307,18 @@ join is for an element collection, the name of the collection table.
 |(Optional) The foreign key constraint for
 the join column. This is used only if table generation is in effect.
 |Provider's default
+
+|CheckConstraint[]
+|check
+|(Optional) Check constraints for the column. These are
+only used if table generation is in effect.
+|No check constraint
+
+|String
+|comment
+|(Optional) Comment for the column. This is
+only used if table generation is in effect.
+|No comment
 |===
 
 *Example 1:*
@@ -2426,6 +2454,8 @@ public @interface JoinTable {
     ForeignKey inverseForeignKey() default @ForeignKey(PROVIDER_DEFAULT);
     UniqueConstraint[] uniqueConstraints() default {};
     Index[] indexes() default {};
+    CheckConstraint[] check() default {}
+    String comment() default "";
 }
 ----
 
@@ -2490,6 +2520,18 @@ effect.
 |(Optional) Indexes for the table. These are
 only used if table generation is in effect.
 |No additional indexes
+
+|CheckConstraint[]
+|check
+|(Optional) Check constraints for the table. These are
+only used if table generation is in effect.
+|No check constraint
+
+|String
+|comment
+|(Optional) Comment for the table. This is
+only used if table generation is in effect.
+|No comment
 |===
 
 *Example:*
@@ -4560,6 +4602,8 @@ public @interface SecondaryTable {
     ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT);
     UniqueConstraint[] uniqueConstraints() default {};
     Index[] indexes() default {};
+    CheckConstraint[] check() default {}
+    String comment() default "";
 }
 ----
 
@@ -4608,6 +4652,18 @@ entailed by primary key mappings.
 |(Optional) Indexes for the table. These are
 only used if table generation is in effect.
 |No additional indexes
+
+|CheckConstraint[]
+|check
+|(Optional) Check constraints for the table. These are
+only used if table generation is in effect.
+|No check constraint
+
+|String
+|comment
+|(Optional) Comment for the table. This is
+only used if table generation is in effect.
+|No comment
 |===
 
 *Example 1:* Single secondary table with a single primary key column.
@@ -4830,6 +4886,8 @@ public @interface Table {
     String schema() default "";
     UniqueConstraint[] uniqueConstraints() default {};
     Index[] indexes() default {};
+    CheckConstraint[] check() default {}
+    String comment() default "";
 }
 ----
 
@@ -4868,6 +4926,18 @@ constraints
 |(Optional) Indexes for the table. These are
 only used if table generation is in effect.
 |No additional indexes
+
+|CheckConstraint[]
+|check
+|(Optional) Check constraints for the table. These are
+only used if table generation is in effect.
+|No check constraint
+
+|String
+|comment
+|(Optional) Comment for the table. This is
+only used if table generation is in effect.
+|No comment
 |===
 
 *Example:*