From c7a26efed543c93fcf68f1f4efe63cad9a091cac Mon Sep 17 00:00:00 2001 From: Gavin Date: Mon, 2 Jan 2023 21:48:47 +0100 Subject: [PATCH] more jdoc improvements to annotations --- .../org/hibernate/annotations/Formula.java | 2 ++ .../org/hibernate/annotations/OrderBy.java | 33 +++++++++++++------ .../java/org/hibernate/annotations/Where.java | 11 +++++++ .../hibernate/annotations/WhereJoinTable.java | 22 +++++++++---- .../hibernate/annotations/package-info.java | 2 +- .../boot/model/internal/CollectionBinder.java | 2 +- 6 files changed, 53 insertions(+), 19 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java b/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java index 96b8fead91..a2c2b4a3d9 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Formula.java @@ -16,6 +16,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; /** * Specifies an expression written in native SQL that is used to read the value of * an attribute instead of storing the value in a {@link jakarta.persistence.Column}. + *

* A {@code Formula} mapping defines a "derived" attribute, whose state is determined * from other columns and functions when an entity is read from the database. *

@@ -25,6 +26,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * @Formula("sub_total + (sub_total * tax)") * long getTotalCost() { ... } * + *

* It may even call SQL functions: * 

  * // call native SQL functions
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java b/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java
index f3e52b327b..ce11245ff3 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java
@@ -16,19 +16,32 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Order a collection using an expression written in native SQL.
  * 

- * The order is applied by the database when the collection is fetched, but is not maintained
- * by operations that mutate the collection in memory. If the collection is a {@link java.util.Set}
- * or {@link java.util.Map}, the order is maintained using a {@link java.util.LinkedHashSet} or
- * {@link java.util.LinkedHashMap}.
+ * The order is applied by the database when the collection is fetched,
+ * but is not maintained by operations that mutate the collection in
+ * memory.
+ * 

+ * If the collection is a {@link java.util.Set} or {@link java.util.Map},
+ * the order is maintained using a {@link java.util.LinkedHashSet} or
+ * {@link java.util.LinkedHashMap}. If the collection is a bag or
+ * {@link java.util.List}, the order is maintained by the underlying
+ * {@link java.util.ArrayList}.
+ * 

+ * There are several other ways to order or sort a collection:
  * 

  * 

- * It is illegal to use both {@code OrderBy} and {@link jakarta.persistence.OrderBy}.
+ * It's illegal to use {@code OrderBy} together with the JPA-defined
+ * {@link jakarta.persistence.OrderBy} for the same collection.
  *
  * @see jakarta.persistence.OrderBy
  * @see SortComparator
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Where.java b/hibernate-core/src/main/java/org/hibernate/annotations/Where.java
index cc612c0d69..30cfa046da 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Where.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/Where.java
@@ -38,6 +38,16 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * List<Document> documents;
  *
*

+ * The {@link WhereJoinTable} annotation lets a restriction be applied to + * an {@linkplain jakarta.persistence.JoinTable association table}: + * 

+ * @ManyToMany
+ * @JoinTable(name = "collaborations")
+ * @Where(clause = "status <> 'DELETED'")
+ * @WhereJoinTable(clause = "status = 'ACTIVE'")
+ * List<Document> documents;
+ *
+ *

* By default, {@code @Where} restrictions declared for an entity are not * applied when loading a collection of that entity type. This behavior is * controlled by: @@ -46,6 +56,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; *

  • the configuration property * {@value org.hibernate.cfg.AvailableSettings#USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS}. * + *

    * Note that {@code @Where} restrictions are always applied and cannot be * disabled. Nor may they be parameterized. They're therefore much * less flexible than {@linkplain Filter filters}. diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java b/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java index 650c0ed9e6..df3f68ec47 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java @@ -6,26 +6,34 @@ */ package org.hibernate.annotations; -import java.lang.annotation.ElementType; import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import static java.lang.annotation.ElementType.FIELD; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + /** * Specifies a restriction written in native SQL to add to the generated SQL * when querying the {@linkplain jakarta.persistence.JoinTable join table} * of a collection. *

    - * For example, @Where("status <> 'DELETED'") could be - * used to hide associations which have been soft-deleted from an association - * table. + * For example, @WhereJoinTable("status <> 'DELETED'") + * could be used to hide associations which have been soft-deleted from an + * association table. + * + * @apiNote This separate annotation is useful because it's possible to filter + * a many-to-many association both by a restriction on the + * join table, and, simultaneously, by a restriction on the + * associated entity table. The {@link Where @Where} annotation always + * filters entity tables. * * @author Emmanuel Bernard * * @see Where */ -@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) -@Retention(RetentionPolicy.RUNTIME) +@Target({METHOD, FIELD}) +@Retention(RUNTIME) public @interface WhereJoinTable { /** * A predicate, written in native SQL. diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java index 30cfc53cc4..1881daf975 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/package-info.java @@ -299,7 +299,7 @@ *

  • {@link org.hibernate.annotations.Formula} allows a field or property to map to an * arbitrary SQL expression instead of a column, *
  • {@link org.hibernate.annotations.Check} specifies a check constraint condition, - *
  • {@link org.hibernate.annotations.ColumnDefault} specifies default value, and + *
  • {@link org.hibernate.annotations.ColumnDefault} specifies a default value, and * {@link org.hibernate.annotations.GeneratedColumn} specifies a generated value, *
  • {@link org.hibernate.annotations.Filter} and {@link org.hibernate.annotations.Where} * each specify a restriction written in SQL, diff --git a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java index 16fb0042a5..28574e16aa 100644 --- a/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java +++ b/hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java @@ -1715,7 +1715,7 @@ public abstract class CollectionBinder { final String whereClause = getWhereClause(); if ( hasAssociationTable ) { // A many-to-many association has an association (join) table - // Collection#setManytoManyWhere is used to set the "where" clause that applies to + // Collection#setManytoManyWhere is used to set the "where" clause that applies // to the many-to-many associated entity table (not the join table). collection.setManyToManyWhere( whereClause ); }