From 263e3038299c7f81a175a74b1ddf04832d6b526b Mon Sep 17 00:00:00 2001 From: Gavin Date: Fri, 30 Dec 2022 14:01:09 +0100 Subject: [PATCH] add documentation about filters --- .../src/main/java/org/hibernate/Filter.java | 4 ++++ .../src/main/java/org/hibernate/Session.java | 4 ++++ .../org/hibernate/annotations/FilterDef.java | 2 ++ .../hibernate/annotations/package-info.java | 20 +++++++++++++++++++ hibernate-core/src/main/javadoc/overview.html | 3 ++- release/src/release/javadoc/overview.html | 3 ++- 6 files changed, 34 insertions(+), 2 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/Filter.java b/hibernate-core/src/main/java/org/hibernate/Filter.java index d85b31c31f..9d3dcde23f 100644 --- a/hibernate-core/src/main/java/org/hibernate/Filter.java +++ b/hibernate-core/src/main/java/org/hibernate/Filter.java @@ -18,6 +18,10 @@ import org.hibernate.engine.spi.FilterDefinition; * A filter may be defined using {@link org.hibernate.annotations.FilterDef} * and {@link org.hibernate.annotations.Filter}, and must be explicitly * enabled at runtime by calling {@link Session#enableFilter(String)}. + *

+ * Every parameter of the filter must be set immediately after + * {@code enableFilter()} is called, and before any other operation of the + * session is invoked. * * @see org.hibernate.annotations.FilterDef * @see Session#enableFilter(String) diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java index 7149dfb61d..dc4baa237c 100644 --- a/hibernate-core/src/main/java/org/hibernate/Session.java +++ b/hibernate-core/src/main/java/org/hibernate/Session.java @@ -1160,6 +1160,10 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Enable the named {@linkplain Filter filter} for this current session. + *

+ * The returned {@link Filter} object must be used to bind arguments + * to parameters of the filter, and every parameter must be set before + * any other operation of this session is called. * * @param filterName the name of the filter to be enabled. * diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java index aeafbe507b..2c2083bbbb 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java @@ -50,6 +50,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * 

  * session.enableFilter("Current");
  *
+ *

+ * A filter has no effect unless it is explicitly enabled. * * @author Matthew Inger * @author Emmanuel Bernard 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 7bad703337..43ad669e9b 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 @@ -170,6 +170,26 @@ * {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices * advocated above. * + *

Filters

+ * + * Filters are an extremely powerful feature of Hibernate, allowing the definition of + * parameterized families of filtered "views" of the domain data. They're also easy + * to use, with the minor caveat that they require the developer to express filtering + * expressions in native SQL. + * + *

+ * Note that a filter has no affect unless it is + * {@linkplain org.hibernate.Session#enableFilter(java.lang.String) enabled} in a + * particular session. + * *

Dialect-specific native SQL

* * Many annotations in this package allow the specification of native SQL expressions or diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html index 1200882c37..a2a4cd710d 100644 --- a/hibernate-core/src/main/javadoc/overview.html +++ b/hibernate-core/src/main/javadoc/overview.html @@ -37,9 +37,10 @@
  • {@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,
  • {@link org.hibernate.StatelessSession} for processes involving many entity instances,
  • {@link org.hibernate.Cache} to manage the second-level cache,
    • -
  • {@link org.hibernate.Transaction} to control local transactions
    • +
  • {@link org.hibernate.Transaction} to control local transactions,
  • {@link org.hibernate.query.Query} to execute HQL queries,
  • {@link org.hibernate.query.NativeQuery} to execute native SQL queries,
    • +
  • {@link org.hibernate.Filter} to manage filters,
  • {@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries, and
  • {@link org.hibernate.relational.SchemaManager} to execute DDL in tests.
    • diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html index 1200882c37..a2a4cd710d 100644 --- a/release/src/release/javadoc/overview.html +++ b/release/src/release/javadoc/overview.html @@ -37,9 +37,10 @@
  • {@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,
  • {@link org.hibernate.StatelessSession} for processes involving many entity instances,
  • {@link org.hibernate.Cache} to manage the second-level cache,
    • -
  • {@link org.hibernate.Transaction} to control local transactions
    • +
  • {@link org.hibernate.Transaction} to control local transactions,
  • {@link org.hibernate.query.Query} to execute HQL queries,
  • {@link org.hibernate.query.NativeQuery} to execute native SQL queries,
    • +
  • {@link org.hibernate.Filter} to manage filters,
  • {@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries, and
  • {@link org.hibernate.relational.SchemaManager} to execute DDL in tests.