add documentation about filters
This commit is contained in:
parent
9ea6f162fd
commit
263e303829
|
@ -18,6 +18,10 @@ import org.hibernate.engine.spi.FilterDefinition;
|
||||||
* A filter may be defined using {@link org.hibernate.annotations.FilterDef}
|
* A filter may be defined using {@link org.hibernate.annotations.FilterDef}
|
||||||
* and {@link org.hibernate.annotations.Filter}, and must be explicitly
|
* and {@link org.hibernate.annotations.Filter}, and must be explicitly
|
||||||
* enabled at runtime by calling {@link Session#enableFilter(String)}.
|
* enabled at runtime by calling {@link Session#enableFilter(String)}.
|
||||||
|
* <p>
|
||||||
|
* 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 org.hibernate.annotations.FilterDef
|
||||||
* @see Session#enableFilter(String)
|
* @see Session#enableFilter(String)
|
||||||
|
|
|
@ -1160,6 +1160,10 @@ public interface Session extends SharedSessionContract, EntityManager {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Enable the named {@linkplain Filter filter} for this current session.
|
* Enable the named {@linkplain Filter filter} for this current session.
|
||||||
|
* <p>
|
||||||
|
* 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.
|
* @param filterName the name of the filter to be enabled.
|
||||||
*
|
*
|
||||||
|
|
|
@ -50,6 +50,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
|
||||||
* <pre>
|
* <pre>
|
||||||
* session.enableFilter("Current");
|
* session.enableFilter("Current");
|
||||||
* </pre>
|
* </pre>
|
||||||
|
* <p>
|
||||||
|
* A filter has no effect unless it is explicitly enabled.
|
||||||
*
|
*
|
||||||
* @author Matthew Inger
|
* @author Matthew Inger
|
||||||
* @author Emmanuel Bernard
|
* @author Emmanuel Bernard
|
||||||
|
|
|
@ -170,6 +170,26 @@
|
||||||
* {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices
|
* {@code ALL} and {@code DISABLE_SELECTIVE} fit extremely poorly with the practices
|
||||||
* advocated above.
|
* advocated above.
|
||||||
*
|
*
|
||||||
|
* <h3 id="filters">Filters</h3>
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
* <ul>
|
||||||
|
* <li>The {@link org.hibernate.annotations.FilterDef} annotation defines a named
|
||||||
|
* filter, declares its parameters, and might specify a filtering expression
|
||||||
|
* used by default. There should be exactly one of these annotations per filter
|
||||||
|
* name.
|
||||||
|
* <li>The {@link org.hibernate.annotations.Filter} annotation is used to identify
|
||||||
|
* which entities and associations are affected by the filter, and provide a
|
||||||
|
* more specific filtering condition.
|
||||||
|
* </ul>
|
||||||
|
* <p>
|
||||||
|
* Note that a filter has no affect unless it is
|
||||||
|
* {@linkplain org.hibernate.Session#enableFilter(java.lang.String) enabled} in a
|
||||||
|
* particular session.
|
||||||
|
*
|
||||||
* <h3 id="dialect-specific-sql">Dialect-specific native SQL</h3>
|
* <h3 id="dialect-specific-sql">Dialect-specific native SQL</h3>
|
||||||
*
|
*
|
||||||
* Many annotations in this package allow the specification of native SQL expressions or
|
* Many annotations in this package allow the specification of native SQL expressions or
|
||||||
|
|
|
@ -37,9 +37,10 @@
|
||||||
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
||||||
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
||||||
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
||||||
<li>{@link org.hibernate.Transaction} to control local transactions</li>
|
<li>{@link org.hibernate.Transaction} to control local transactions,</li>
|
||||||
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
||||||
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
||||||
|
<li>{@link org.hibernate.Filter} to manage filters,</li>
|
||||||
<li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
|
<li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
|
||||||
and</li>
|
and</li>
|
||||||
<li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
|
<li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
|
||||||
|
|
|
@ -37,9 +37,10 @@
|
||||||
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
||||||
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
||||||
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
||||||
<li>{@link org.hibernate.Transaction} to control local transactions</li>
|
<li>{@link org.hibernate.Transaction} to control local transactions,</li>
|
||||||
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
||||||
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
||||||
|
<li>{@link org.hibernate.Filter} to manage filters,</li>
|
||||||
<li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
|
<li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
|
||||||
and</li>
|
and</li>
|
||||||
<li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
|
<li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
|
||||||
|
|
Loading…
Reference in New Issue