Merge pull request #935 from njr-11/906-standardize-on-the-term-entit…

…y-attribute

standardize on the term entity attribute

api/src/main/java/jakarta/data/Sort.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
  * <p>Requests sorting on a given entity attribute.</p>
  *
  * <p>An instance of {@code Sort} specifies a sorting criterion based
- * on an entity field, with a sorting {@linkplain Direction direction}
+ * on an entity attribute, with a sorting {@linkplain Direction direction}
  * and well-defined case sensitivity.</p>
  *
  * <p>A query method of a repository may have a parameter or parameters
@@ -83,24 +83,28 @@
  * sort criteria.</p>
  *
  *
- * @param <T>         entity class of the property upon which to sort.
- * @param property    name of the property to order by.
- * @param isAscending whether ordering for this property is ascending (true) or descending (false).
+ * @param <T>         entity class of the entity attribute upon which to sort.
+ * @param property    name of the entity attribute to order by.
+ * @param isAscending whether ordering for this attribute is ascending (true) or descending (false).
  * @param ignoreCase  whether or not to request case insensitive ordering from a database with case sensitive collation.
  */
 public record Sort<T>(String property, boolean isAscending, boolean ignoreCase) {
 
     /**
-     * <p>Defines sort criteria for an entity property. For more descriptive code, use:</p>
+     * <p>Defines sort criteria for an entity attribute. For more descriptive code, use:</p>
      * <ul>
-     * <li>{@link #asc(String) Sort.asc(propertyName)} for ascending sort on a property.</li>
-     * <li>{@link #ascIgnoreCase(String) Sort.ascIgnoreCase(propertyName)} for case insensitive ascending sort on a property.</li>
-     * <li>{@link #desc(String) Sort.desc(propertyName)} for descending sort on a property.</li>
-     * <li>{@link #descIgnoreCase(String) Sort.descIgnoreCase(propertyName)} for case insensitive descending sort on a property.</li>
+     * <li>{@link #asc(String) Sort.asc(attributeName)}
+     *     for ascending sort on an entity attribute.</li>
+     * <li>{@link #ascIgnoreCase(String) Sort.ascIgnoreCase(attributeName)}
+     *     for case insensitive ascending sort on an entity attribute.</li>
+     * <li>{@link #desc(String) Sort.desc(attributeName)}
+     *     for descending sort on an entity attribute.</li>
+     * <li>{@link #descIgnoreCase(String) Sort.descIgnoreCase(attributeName)}
+     *      for case insensitive descending sort on an entity attribute.</li>
      * </ul>
      *
-     * @param property    name of the property to order by.
-     * @param isAscending whether ordering for this property is ascending (true) or descending (false).
+     * @param property    name of the entity attribute to order by.
+     * @param isAscending whether ordering for this attribute is ascending (true) or descending (false).
      * @param ignoreCase  whether or not to request case insensitive ordering from a database with case sensitive collation.
      */
     public Sort {
@@ -109,9 +113,9 @@ public record Sort<T>(String property, boolean isAscending, boolean ignoreCase)
 
     // Override to provide method documentation:
     /**
-     * Name of the property to order by.
+     * Name of the entity attribute to order by.
      *
-     * @return The property name to order by; will never be {@code null}.
+     * @return The attribute name to order by; will never be {@code null}.
      */
     public String property() {
         return property;
@@ -124,26 +128,28 @@ public String property() {
      * A database with case insensitive collation performs case insensitive
      * ordering regardless of the requested {@code ignoreCase} value.</p>
      *
-     * @return Returns whether or not to request case insensitive sorting for the property.
+     * @return Returns whether or not to request case insensitive sorting for the entity attribute.
      */
     public boolean ignoreCase() {
         return ignoreCase;
     }
 
     // Override to provide method documentation:
     /**
-     * Indicates whether to sort the property in ascending order (true) or descending order (false).
+     * Indicates whether to sort the entity attribute in ascending order (true)
+     * or descending order (false).
      *
-     * @return Returns whether sorting for this property shall be ascending.
+     * @return Returns whether sorting for this attribute shall be ascending.
      */
     public boolean isAscending() {
         return isAscending;
     }
 
     /**
-     * Indicates whether to sort the property in descending order (true) or ascending order (false).
+     * Indicates whether to sort the entity attribute in descending order (true)
+     * or ascending order (false).
      *
-     * @return Returns whether sorting for this property shall be descending.
+     * @return Returns whether sorting for this attribute shall be descending.
      */
     public boolean isDescending() {
         return !isAscending;
@@ -152,67 +158,67 @@ public boolean isDescending() {
     /**
      * Create a {@link Sort} instance
      *
-     * @param <T>        entity class of the sortable property.
-     * @param property  the property name to order by
-     * @param direction the direction in which to order.
+     * @param <T>        entity class of the sortable entity attribute.
+     * @param attribute  name of the entity attribute to order by
+     * @param direction  the direction in which to order.
      * @param ignoreCase whether to request a case insensitive ordering.
      * @return a {@link Sort} instance. Never {@code null}.
      * @throws NullPointerException when there is a null parameter
      */
-    public static <T> Sort<T> of(String property, Direction direction, boolean ignoreCase) {
+    public static <T> Sort<T> of(String attribute, Direction direction, boolean ignoreCase) {
         Objects.requireNonNull(direction, "direction is required");
-        return new Sort<>(property, Direction.ASC.equals(direction), ignoreCase);
+        return new Sort<>(attribute, Direction.ASC.equals(direction), ignoreCase);
     }
 
     /**
      * Create a {@link Sort} instance with {@link Direction#ASC ascending direction}
      * that does not request case insensitive ordering.
      *
-     * @param <T>      entity class of the sortable property.
-     * @param property the property name to order by
+     * @param <T>       entity class of the sortable entity attribute.
+     * @param attribute name of the entity attribute to order by
      * @return a {@link Sort} instance. Never {@code null}.
-     * @throws NullPointerException when the property is null
+     * @throws NullPointerException when the attribute name is null
      */
-    public static <T> Sort<T> asc(String property) {
-        return new Sort<>(property, true, false);
+    public static <T> Sort<T> asc(String attribute) {
+        return new Sort<>(attribute, true, false);
     }
 
     /**
      * Create a {@link Sort} instance with {@link Direction#ASC ascending direction}
      * and case insensitive ordering.
      *
-     * @param <T>      entity class of the sortable property.
-     * @param property the property name to order by.
+     * @param <T>       entity class of the sortable entity attribute.
+     * @param attribute name of the entity attribute to order by.
      * @return a {@link Sort} instance. Never {@code null}.
-     * @throws NullPointerException when the property is null.
+     * @throws NullPointerException when the attribute name is null.
      */
-    public static <T> Sort<T> ascIgnoreCase(String property) {
-        return new Sort<>(property, true, true);
+    public static <T> Sort<T> ascIgnoreCase(String attribute) {
+        return new Sort<>(attribute, true, true);
     }
 
     /**
      * Create a {@link Sort} instance with {@link Direction#DESC descending direction}
      * that does not request case insensitive ordering.
      *
-     * @param <T>      entity class of the sortable property.
-     * @param property the property name to order by
+     * @param <T>       entity class of the sortable entity attribute.
+     * @param attribute name of the entity attribute to order by
      * @return a {@link Sort} instance. Never {@code null}.
-     * @throws NullPointerException when the property is null
+     * @throws NullPointerException when the attribute name is null
      */
-    public static <T> Sort<T> desc(String property) {
-        return new Sort<>(property, false, false);
+    public static <T> Sort<T> desc(String attribute) {
+        return new Sort<>(attribute, false, false);
     }
 
     /**
      * Create a {@link Sort} instance with {@link Direction#DESC descending direction}
      * and case insensitive ordering.
      *
-     * @param <T>      entity class of the sortable property.
-     * @param property the property name to order by.
+     * @param <T>       entity class of the sortable entity attribute.
+     * @param attribute name of the entity attribute to order by.
      * @return a {@link Sort} instance. Never {@code null}.
-     * @throws NullPointerException when the property is null.
+     * @throws NullPointerException when the attribute name is null.
      */
-    public static <T> Sort<T> descIgnoreCase(String property) {
-        return new Sort<>(property, false, true);
+    public static <T> Sort<T> descIgnoreCase(String attribute) {
+        return new Sort<>(attribute, false, true);
     }
 }

api/src/main/java/jakarta/data/TextRestrictionRecord.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2024,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,12 +34,12 @@ record TextRestrictionRecord<T>(
         Objects.requireNonNull(attribute, "Attribute must not be null");
     }
 
-    TextRestrictionRecord(String field, Operator comparison, boolean escaped, String value) {
-        this(field, comparison, true, escaped, value);
+    TextRestrictionRecord(String attributeName, Operator comparison, boolean escaped, String value) {
+        this(attributeName, comparison, true, escaped, value);
     }
 
-    TextRestrictionRecord(String field, Operator comparison, String value) {
-        this(field, comparison, true, false, value);
+    TextRestrictionRecord(String attributeName, Operator comparison, String value) {
+        this(attributeName, comparison, true, false, value);
     }
 
     @Override

api/src/main/java/jakarta/data/metamodel/StaticMetamodel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2023,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@
  * <p>Annotates a class which serves as a static metamodel for an entity, enabling
  * type-safe access to entity attribute names and related objects such as instances
  * of {@link Sort}s for an attribute. A metamodel class contains one or more
- * {@code public static} fields corresponding to persistent fields of the entity class.
+ * {@code public static} fields corresponding to attributes of the entity class.
  * The type of each of these fields must be either {@link String}, {@link Attribute},
  * or a subinterface of {@code Attribute} defined in this package.</p>
  *

api/src/main/java/jakarta/data/page/CursoredPage.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,11 +33,11 @@
  * inserted, deleted, or updated in the database between page requests.
  * Cursor-based pagination is possible when a query result set has a
  * well-defined total order, that is, when the results are sorted by a
- * list of entity fields which forms a unique key on the result set.
- * This list of entity fields must be the entity fields of the combined
+ * list of entity attributes which forms a unique key on the result set.
+ * This list of entity attributes must be the entity attributes of the combined
  * sort criteria of the repository method, in the same order of precedence.
- * This could just be the identifier field of the entity, or it might be
- * some other combination of fields which uniquely identifies each query
+ * This could just be the identifier attribute of the entity, or it might be
+ * some other combination of entity attributes which uniquely identifies each query
  * result.</p>
  *
  * <p>When cursor-based pagination is used, a {@linkplain #nextPageRequest
@@ -100,14 +100,14 @@
  * vulnerable to changes made to data in between page requests. Adding or
  * removing entities is possible without causing unexpected missed or
  * duplicate results. Cursor-based pagination does not prevent misses and
- * duplicates if the entity properties which are the sort criteria for
+ * duplicates if the entity attributes which are the sort criteria for
  * existing entities are modified or if an entity is re-added with different
  * sort criteria after having previously been removed.</p>
  *
  * <h2>Cursor-based Pagination with {@code @Query}</h2>
  *
  * <p>Cursor-based pagination involves generating and appending additional
- * restrictions involving the key fields to the {@code WHERE} clause of the
+ * restrictions involving the key elements to the {@code WHERE} clause of the
  * query. For this to be possible, a user-provided JDQL or JPQL query must
  * end with a {@code WHERE} clause to which additional conditions may be
  * appended.</p>

api/src/main/java/jakarta/data/repository/BasicRepository.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -186,7 +186,7 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
     /**
      * Deletes a given entity. Deletion is performed by matching the Id, and if the entity is
      * versioned (for example, with {@code jakarta.persistence.Version}), then also the version.
-     * Other properties of the entity do not need to match.
+     * Other attributes of the entity do not need to match.
      *
      * @param entity must not be {@code null}.
      * @throws OptimisticLockingFailureException if the entity is not found in the database for deletion
@@ -199,7 +199,7 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
     /**
      * Deletes the given entities. Deletion of each entity is performed by matching the unique identifier,
      * and if the entity is versioned (for example, with {@code jakarta.persistence.Version}), then also
-     * the version. Other properties of the entity do not need to match.
+     * the version. Other attributes of the entity do not need to match.
      *
      * @param entities Must not be {@code null}. Must not contain {@code null} elements.
      * @throws OptimisticLockingFailureException If an entity is not found in the database for deletion

api/src/main/java/jakarta/data/repository/By.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2023,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,16 +25,16 @@
 
 /**
  * <p>Annotates a parameter of a repository method, specifying a mapping to
- * a persistent field:</p>
+ * an entity attribute:</p>
  * <ul>
- * <li>if a {@linkplain #value field name} is specified, the parameter maps
- *     to the persistent field with the specified name, or
+ * <li>if an {@linkplain #value attribute name} is specified, the parameter maps
+ *     to the entity attribute with the specified name, or
  * <li>if the special value {@value #ID} is specified, the parameter maps
- *     to the unique identifier field or property.
+ *     to the unique identifier attribute.
  * </ul>
  * <p>Arguments to the annotated parameter are compared to values of the
- * mapped persistent field.</p>
- * <p>The field name may be a compound name like {@code address.city}.</p>
+ * mapped attribute.</p>
+ * <p>The attribute name may be a compound name like {@code address.city}.</p>
  *
  * <p>For example, for a {@code Person} entity with attributes {@code ssn},
  * {@code firstName}, {@code lastName}, and {@code address} we might have:</p>
@@ -84,23 +84,25 @@
 public @interface By {
 
     /**
-     * The name of the persistent field mapped by the annotated parameter,
-     * or {@value #ID} to indicate the unique identifier field or property
+     * The name of the entity attribute mapped by the annotated parameter,
+     * or {@value #ID} to indicate the unique identifier attribute
      * of the entity.
      *
-     * @return the persistent field name, or {@value #ID} to indicate the
-     *         unique identifier field.
+     * @return the entity attribute name, or {@value #ID} to indicate the
+     *         unique identifier attribute.
      */
     String value();
 
     /**
-     * The special value which indicates the unique identifier field or
-     * property. The annotation {@code By(ID)} maps a parameter to the
-     * identifier.
+     * <p>
+     * The special value which indicates the unique identifier attribute.
+     * The annotation {@code By(ID)} maps a parameter to the identifier.
+     * </p>
      * <p>
      * Note that {@code id(this)} is the expression in JPQL for the
      * unique identifier of an entity with an implicit identification
      * variable.
+     * </p>
      */
     String ID = "id(this)";
 }

api/src/main/java/jakarta/data/repository/CrudRepository.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -82,7 +82,7 @@
  * <p>The module Javadoc provides an {@link jakarta.data/ overview} of Jakarta Data.</p>
  *
  * @param <T> the type of the primary entity class of the repository.
- * @param <K> the type of the unique identifier field of property of the primary entity.
+ * @param <K> the type of the unique identifier attribute of the primary entity.
  * @see BasicRepository
  * @see DataRepository
  */