refresh EL annotations

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>
eclipse-ee4j · Feb 14, 2024 · ffe27c4 · ffe27c4
1 parent 8552822
commit ffe27c4
Show file tree

Hide file tree

Showing 155 changed files with 1,716 additions and 1,523 deletions.
diff --git a/...ersistence.core/src/main/java/org/eclipse/persistence/annotations/AdditionalCriteria.java b/...ersistence.core/src/main/java/org/eclipse/persistence/annotations/AdditionalCriteria.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024 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
@@ -22,19 +22,20 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * <p>An additional criteria can be specified at the Entity or MappedSuperclass
+ * <p>An AdditionalCriteria can be specified at the Entity or MappedSuperclass
  * level. When specified at the mapped superclass level, it applies to all
  * inheriting entities unless those entities define their own additional
  * criteria, at which point the additional criteria from the mapped superclass
  * is ignored.</p>
  *
- * <p>The additional criteria supports any valid JPQL string and must use 'this'
+ * <p>The additional criteria supports any valid JPQL string and must use '{@code this}'
  * as an alias to form your additional criteria. E.G.,</p>
- * <pre>
- * {@literal @}Entity
- * {@literal @}AdditionalCriteria("this.nut.size = :NUT_SIZE and this.nut.color = :NUT_COLOR")
- * public class Bolt {...}
- * </pre>
+ * {@snippet :
+ *  @Entity
+ *  @AdditionalCriteria("this.nut.size = :NUT_SIZE and this.nut.color = :NUT_COLOR")
+ *  public class Bolt {
+ *  }
+ * }
  *
  * <p>Additional criteria parameters are also accepted and are set through
  * properties on the entity manager factory, or on an entity manager. When set
@@ -44,7 +45,7 @@
  * <p>Properties set on the entity manager will override those similarly named
  * properties set on the entity manager factory.</p>
  *
- * <p>Additional criteria is not supported with any native queries.</p>
+ * <p>AdditionalCriteria is not supported with any native queries.</p>
  *
  * @author Guy Pelletier
  * @since EclipseLink 2.2
@@ -53,7 +54,7 @@
 @Retention(RUNTIME)
 public @interface AdditionalCriteria {
     /**
-     * (Required) The JPQL fragment to use as the additional criteria.
+     * The JPQL fragment to use as the additional criteria.
      */
     String value();
 }
diff --git a/...org.eclipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/Array.java b/...org.eclipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/Array.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024 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
@@ -24,7 +24,7 @@
 /**
  * Array types are extended object-relational data-types supported by some databases.
  * Array types are user define types in the database such as VARRAY types on Oracle.
- * Arrays can contains basic types (VARCHAR) or other Struct types, and can be stored in
+ * Arrays can contain basic types (VARCHAR) or other Struct types, and can be stored in
  * a column or in a Struct type.
  * <p>
  * This annotation can be defined on a collection attribute that is
@@ -41,17 +41,18 @@
 @Retention(RUNTIME)
 public @interface Array {
     /**
-     * (Optional) The basic or embeddable class that is the element
-     * type of the collection.  This element is optional only if the
-     * collection field or property is defined using Java generics,
-     * and must be specified otherwise.  It defaults to the
-     * paramterized type of the collection when defined using
-     * generics.
+     * The basic or embeddable class that is the element type of the collection.
+     * <p>
+     * This element is optional only if the collection field or property
+     * is defined using Java generics, and must be specified otherwise.
+     * <p>
+     * It defaults to the parameterized type of the collection
+     * when defined using generics.
      */
     Class<?> targetClass() default void.class;
 
     /**
-     * (Required) The database name of the database array structure type.
+     * The database name of the database array structure type.
      */
     String databaseType();
 }
diff --git a/...e.persistence.core/src/main/java/org/eclipse/persistence/annotations/BasicCollection.java b/...e.persistence.core/src/main/java/org/eclipse/persistence/annotations/BasicCollection.java
@@ -20,51 +20,49 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static jakarta.persistence.FetchType.LAZY;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * A BasicCollection is used to map an
- * org.eclipse.persistence.mappings.DirectCollectionMapping, which stores a collection
- * of simple types (String, Number, Date, etc.). It is used in conjunction with
- * a CollectionTable which stores the value and a foreign key to the source
- * object.
+ * A BasicCollection is used to map an {@linkplain org.eclipse.persistence.mappings.DirectCollectionMapping},
+ * which stores a collection of simple types (String, Number, Date, etc.). It is used in conjunction with
+ * a {@linkplain CollectionTable} which stores the value and a foreign key to the source object.
  * <p>
- * Converters may be used if the desired object type and the data type do not
- * match.
+ * Converters may be used if the desired object type and the data type do not match.
  * <p>
  * A BasicCollection can be specified on within an Entity, MappedSuperclass
  * and Embeddable class.
  *
- * @see "jakarta.persistence.ElementCollection"
- * @see org.eclipse.persistence.annotations.CollectionTable
- * @see org.eclipse.persistence.annotations.Convert
- * @see org.eclipse.persistence.annotations.Converter
- * @see org.eclipse.persistence.annotations.ObjectTypeConverter
- * @see org.eclipse.persistence.annotations.TypeConverter
+ * @see CollectionTable
+ * @see Convert
+ * @see Converter
+ * @see ObjectTypeConverter
+ * @see TypeConverter
  *
  * @author Guy Pelletier
  * @since Oracle TopLink 11.1.1.0.0
- * @deprecated
+ * @deprecated Use {@linkplain jakarta.persistence.ElementCollection}.
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 @Deprecated
 public @interface BasicCollection {
     /**
-     * (Optional) Defines whether the value of the field or property should
-     * be lazily loaded or must be eagerly fetched. The EAGER strategy is a
+     * Defines whether the value of the field or property should
+     * be lazily loaded or must be eagerly fetched. The {@linkplain jakarta.persistence.FetchType#EAGER} strategy is a
      * requirement on the persistence provider runtime that the value must be
-     * eagerly fetched. The LAZY strategy is a hint to the persistence provider
-     * runtime. If not specified, defaults to LAZY.
+     * eagerly fetched. The {@linkplain jakarta.persistence.FetchType#LAZY} strategy is a hint to the persistence provider
+     * runtime.
+     * <p>
+     * If not specified, defaults to {@linkplain jakarta.persistence.FetchType#LAZY}.
      */
-    FetchType fetch() default LAZY;
+    FetchType fetch() default FetchType.LAZY;
 
     /**
-     * (Optional) The name of the value column that holds the direct collection
-     * data. Defaults to the property or field name.
+     * The name of the value column that holds the direct collection data.
+     * <p>
+     * Defaults to the property or field name.
      */
     Column valueColumn() default @Column;
 }
diff --git a/....eclipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/BasicMap.java b/....eclipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/BasicMap.java
@@ -20,69 +20,78 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static jakarta.persistence.FetchType.LAZY;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * A BasicMap is used to map an org.eclipse.persistence.mappings.DirectMapMapping, which
+ * A BasicMap is used to map an {@linkplain org.eclipse.persistence.mappings.DirectMapMapping}, which
  * stores a collection of key-value pairs of simple types (String, Number, Date,
- * etc.). It is used in conjunction with a CollectionTable which stores the key,
+ * etc.). It is used in conjunction with a {@linkplain CollectionTable} which stores the key,
  * the value and a foreign key to the source object.
  * A converter may be used if the desired object type and the data type do not
  * match. This applied to both the key and value of the map.
  * <p>
  * A BasicMap can be specified within an Entity, MappedSuperclass and Embeddable
  * class.
  *
- * @see "jakarta.persistence.ElementCollection"
- * @see org.eclipse.persistence.annotations.CollectionTable
- * @see org.eclipse.persistence.annotations.Convert
- * @see org.eclipse.persistence.annotations.Converter
- * @see org.eclipse.persistence.annotations.ObjectTypeConverter
- * @see org.eclipse.persistence.annotations.TypeConverter
+ * @see CollectionTable
+ * @see Convert
+ * @see Converter
+ * @see ObjectTypeConverter
+ * @see TypeConverter
  *
  * @author Guy Pelletier
  * @since Oracle TopLink 11.1.1.0.0
- *
- * @deprecated
+ * @deprecated Use {@linkplain jakarta.persistence.ElementCollection}.
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 @Deprecated
 public @interface BasicMap {
     /**
-     * (Optional) Defines whether the value of the field or property should
-     * be lazily loaded or must be eagerly fetched. The EAGER strategy is a
+     * Defines whether the value of the field or property should
+     * be lazily loaded or must be eagerly fetched. The {@linkplain jakarta.persistence.FetchType#EAGER} strategy is a
      * requirement on the persistence provider runtime that the value must be
-     * eagerly fetched. The LAZY strategy is a hint to the persistence provider
-     * runtime. If not specified, defaults to LAZY.
+     * eagerly fetched. The {@linkplain jakarta.persistence.FetchType#LAZY} strategy is a hint to the persistence provider
+     * runtime.
+     * <p>
+     * If not specified, defaults to {@linkplain jakarta.persistence.FetchType#LAZY}.
      */
-    FetchType fetch() default LAZY;
+    FetchType fetch() default FetchType.LAZY;
 
     /**
-     * (Optional) The name of the data column that holds the direct map
-     * key. If the name on the key column is "", the name will default to:
-     * the name of the property or field; "_KEY".
+     * The name of the data column that holds the direct map key.
+     * <p>
+     * If the name on the key column is {@code ""},
+     * the name will be defaulted to the concatenation of the following:
+     * <ul>
+     *  <li>the name of the property or field</li>
+     *  <li>"{@code _KEY}"</li>
+     * </ul>
      */
     Column keyColumn() default @Column;
 
     /**
-     * (Optional) Specify the key converter. Default is equivalent to specifying
-     * {@literal @}Convert("none"), meaning no converter will be added to the direct map key.
+     * Specify the key converter.
+     * <p>
+     * Default is equivalent to specifying {@code @Convert("none")},
+     * meaning no converter will be added to the direct map key.
      */
     Convert keyConverter() default @Convert;
 
     /**
-     * (Optional) The name of the data column that holds the direct collection data.
-     * Defaults to the property or field name.
+     * The name of the data column that holds the direct collection data.
+     * <p>
+     * Default is the property or field name.
      */
     Column valueColumn() default @Column;
 
     /**
-     * (Optional) Specify the value converter. Default is equivalent to specifying
-     * {@literal @}Convert("none"), meaning no converter will be added to the value column mapping.
+     * Specify the value converter.
+     * <p>
+     * Default is equivalent to specifying {@code @Convert("none")},
+     * meaning no converter will be added to the value column mapping.
      */
     Convert valueConverter() default @Convert;
 }
diff --git a/...clipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/BatchFetch.java b/...clipse.persistence.core/src/main/java/org/eclipse/persistence/annotations/BatchFetch.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024 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
@@ -22,7 +22,7 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * A BatchFetch annotation can be used on any relationship mapping,
+ * A BatchFetch annotation can be used on any relationship mapping
  * (OneToOne, ManyToOne, OneToMany, ManyToMany, ElementCollection, BasicCollection, BasicMap).
  * It allows the related objects to be batch read in a single query.
  * Batch fetching can also be set at the query level, and it is
@@ -35,16 +35,18 @@
 @Retention(RUNTIME)
 public @interface BatchFetch {
     /**
-     * (Optional) The type of batch-fetch to use.
-     * Either JOIN, EXISTS or IN.
-     * JOIN is the default.
+     * The type of batch-fetch to use.
+     * Either {@linkplain BatchFetchType#JOIN}, {@linkplain BatchFetchType#EXISTS} or {@linkplain BatchFetchType#IN}.
+     * <p>
+     * {@linkplain BatchFetchType#JOIN} is the default.
      */
     BatchFetchType value() default BatchFetchType.JOIN;
 
     /**
      * Define the default batch fetch size.
-     * This is only used for IN type batch reading and defines
+     * This is only used for {@linkplain BatchFetchType#IN} type batch reading and defines
      * the number of keys used in each IN clause.
+     * <p>
      * The default size is 256, or the query's pageSize for cursor queries.
      */
     int size() default -1;

diff --git a/...se.persistence.core/src/main/java/org/eclipse/persistence/annotations/BatchFetchType.java b/...se.persistence.core/src/main/java/org/eclipse/persistence/annotations/BatchFetchType.java
@@ -15,7 +15,7 @@
 package org.eclipse.persistence.annotations;
 
 /**
- * Enum used with the BatchFetch annotation, or {@code eclipselink.batch.type} query hint.
+ * Enum used with the {@linkplain BatchFetch} annotation, or "{@systemProperty eclipselink.batch.type}" query hint.
  * This can be specified on a mapping or query to configure the type of batch reading to be used.
  *
  * @see BatchFetch
@@ -24,22 +24,26 @@
  */
 public enum BatchFetchType {
     /**
-     * This is the default form of batch reading.
      * The original query's selection criteria is joined with the batch query.
+     * <p>
+     * This is the default form of batch reading.
      */
     JOIN,
 
     /**
-     * This uses an SQL EXISTS and a sub-select in the batch query instead of a join.
+     * Use an SQL EXISTS and a sub-select in the batch query instead of a join.
+     * <p>
      * This has the advantage of not requiring an SQL DISTINCT which can have issues
      * with LOBs, or may be more efficient for some types of queries or on some databases.
      */
     EXISTS,
 
     /**
-     * This uses an SQL IN clause in the batch query passing in the source object Ids.
+     * Use an SQL IN clause in the batch query passing in the source object Ids.
+     * <p>
      * This has the advantage of only selecting the objects not already contained in the cache,
      * and can work better with cursors, or if joins cannot be used.
+     * <p>
      * This may only work for singleton Ids on some databases.
      */
     IN