[hibernate-commits] Hibernate SVN: r19963 - core/trunk/documentation/manual/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Fri Jul 16 15:46:12 EDT 2010
Author: hardy.ferentschik
Date: 2010-07-16 15:46:12 -0400 (Fri, 16 Jul 2010)
New Revision: 19963
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/filters.xml
Log:
HHH-5153 Added @Filter and @FilterDef to filtering chapter
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/filters.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/filters.xml 2010-07-16 19:04:26 UTC (rev 19962)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/filters.xml 2010-07-16 19:46:12 UTC (rev 19963)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,156 +22,194 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent">
%BOOK_ENTITIES;
-
]>
-
<chapter id="filters">
- <title>Filtering data</title>
-
- <para>
- Hibernate3 provides an innovative new approach to handling data with "visibility" rules.
- A <emphasis>Hibernate filter</emphasis> is a global, named, parameterized filter that can be
- enabled or disabled for a particular Hibernate session.
- </para>
+ <title>Filtering data</title>
- <section id="objectstate-filters" revision="1">
- <title>Hibernate filters</title>
+ <para>Hibernate3 provides an innovative new approach to handling data with
+ "visibility" rules. A <emphasis>Hibernate filter</emphasis> is a global,
+ named, parameterized filter that can be enabled or disabled for a particular
+ Hibernate session.</para>
- <para>
- Hibernate3 has the ability to pre-define filter criteria and attach those filters at both
- a class level and a collection level. A filter criteria allows you to define a restriction clause
- similar to the existing "where" attribute available on the class and various collection
- elements. These filter conditions, however, can be parameterized. The application can then
- decide at runtime whether certain filters should be enabled and what their parameter
- values should be. Filters can be used like database views, but they are parameterized inside the
- application.
- </para>
+ <section id="objectstate-filters" revision="1">
+ <title>Hibernate filters</title>
- <para>
- In order to use filters, they must first be defined and then attached to the appropriate
- mapping elements. To define a filter, use the <literal><filter-def/></literal> element
- within a <literal><hibernate-mapping/></literal> element:
- </para>
+ <para>Hibernate3 has the ability to pre-define filter criteria and attach
+ those filters at both a class level and a collection level. A filter
+ criteria allows you to define a restriction clause similar to the existing
+ "where" attribute available on the class and various collection elements.
+ These filter conditions, however, can be parameterized. The application
+ can then decide at runtime whether certain filters should be enabled and
+ what their parameter values should be. Filters can be used like database
+ views, but they are parameterized inside the application.</para>
- <programlisting role="XML"><![CDATA[<filter-def name="myFilter">
- <filter-param name="myFilterParam" type="string"/>
-</filter-def>]]></programlisting>
+ <para>Using annotatons filters are defined via
+ <literal>@org.hibernate.annotations.FilterDef</literal> or
+ <literal>@org.hibernate.annotations.FilterDefs</literal>. A filter
+ definition has a <methodname>name()</methodname> and an array of
+ parameters(). A parameter will allow you to adjust the behavior of the
+ filter at runtime. Each parameter is defined by a
+ <literal>@ParamDef</literal> which has a name and a type. You can also
+ define a <methodname>defaultCondition()</methodname> parameter for a given
+ <literal>@FilterDef</literal> to set the default condition to use when
+ none are defined in each individual <literal>@Filter</literal>.
+ <literal>@FilterDef</literal>(s) can be defined at the class or package
+ level. </para>
- <para>
- This filter can then be attached to a class:
- </para>
+ <para>We now need to define the SQL filter clause applied to either the
+ entity load or the collection load. <literal>@Filter</literal> is used and
+ placed either on the entity or the collection element. The connection
+ between <classname>@FilterName</classname> and
+ <classname>@Filter</classname> is a matching name.</para>
- <programlisting role="XML"><![CDATA[<class name="myClass" ...>
- ...
- <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
-</class>]]></programlisting>
+ <example>
+ <title>@FilterDef and @Filter annotations</title>
- <para>
- Or, to a collection:
- </para>
+ <programlisting language="JAVA" role="JAVA">@Entity
+ at FilterDef(name="minLength", parameters=@ParamDef( name="minLength", type="integer" ) )
+ at Filters( {
+ @Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length"),
+ @Filter(name="minLength", condition=":minLength <= length")
+} )
+public class Forest { ... }</programlisting>
+ </example>
- <programlisting role="XML"><![CDATA[<set ...>
- <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
-</set>]]></programlisting>
+ <para>When the collection use an association table as a relational
+ representation, you might want to apply the filter condition to the
+ association table itself or to the target entity table. To apply the
+ constraint on the target entity, use the regular
+ <literal>@Filter</literal> annotation. However, if you want to target the
+ association table, use the <literal>@FilterJoinTable</literal>
+ annotation.</para>
- <para>
- Or, to both or multiples of each at the same time.
- </para>
+ <example>
+ <title>Using <classname>@FilterJoinTable</classname> for filterting on
+ the association table</title>
- <para>
- The methods on <literal>Session</literal> are: <literal>enableFilter(String filterName)</literal>,
- <literal>getEnabledFilter(String filterName)</literal>, and <literal>disableFilter(String filterName)</literal>.
- By default, filters are <emphasis>not</emphasis> enabled for a given session. Filters must be
- enabled through use of the <literal>Session.enableFilter()</literal> method, which returns an
- instance of the <literal>Filter</literal> interface. If you used the simple filter defined above, it would
- look like this:
- </para>
+ <programlisting language="JAVA" role="JAVA"> @OneToMany
+ @JoinTable
+ //filter on the target entity table
+ @Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length")
+ //filter on the association table
+ @FilterJoinTable(name="security", condition=":userlevel >= requredLevel")
+ public Set<Forest> getForests() { ... }</programlisting>
+ </example>
- <programlisting role="JAVA"><![CDATA[session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");]]></programlisting>
+ <para>Using Hibernate mapping files for defining filters the situtation is
+ very similar. The filters must first be defined and then attached to the
+ appropriate mapping elements. To define a filter, use the
+ <literal><filter-def/></literal> element within a
+ <literal><hibernate-mapping/></literal> element:</para>
- <para>
- Methods on the org.hibernate.Filter interface do allow the method-chaining common to much of Hibernate.
- </para>
+ <example>
+ <title>Defining a filter definition via
+ <literal><filter-def></literal></title>
- <para>
- The following is a full example, using temporal data with an effective record date pattern:
- </para>
+ <programlisting role="XML"><filter-def name="myFilter">
+ <filter-param name="myFilterParam" type="string"/>
+</filter-def></programlisting>
+ </example>
- <programlisting role="XML"><![CDATA[<filter-def name="effectiveDate">
- <filter-param name="asOfDate" type="date"/>
-</filter-def>
+ <para>This filter can then be attached to a class or collection (or, to
+ both or multiples of each at the same time):</para>
-<class name="Employee" ...>
+ <example>
+ <title>Attaching a filter to a class or collection using
+ <literal><filter></literal></title>
+
+ <programlisting role="XML"><class name="myClass" ...>
+ ...
+ <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
+
+ <set ...>
+ <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
+ </set>
+</class></programlisting>
+ </example>
+
+ <para>The methods on <literal>Session</literal> are:
+ <literal>enableFilter(String filterName)</literal>,
+ <literal>getEnabledFilter(String filterName)</literal>, and
+ <literal>disableFilter(String filterName)</literal>. By default, filters
+ are <emphasis>not</emphasis> enabled for a given session. Filters must be
+ enabled through use of the <literal>Session.enableFilter()</literal>
+ method, which returns an instance of the <literal>Filter</literal>
+ interface. If you used the simple filter defined above, it would look like
+ this:</para>
+
+ <programlisting role="JAVA">session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");</programlisting>
+
+ <para>Methods on the org.hibernate.Filter interface do allow the
+ method-chaining common to much of Hibernate.</para>
+
+ <para>The following is a full example, using temporal data with an
+ effective record date pattern:</para>
+
+ <programlisting role="XML"><filter-def name="effectiveDate">
+ <filter-param name="asOfDate" type="date"/>
+</filter-def>
+
+<class name="Employee" ...>
...
- <many-to-one name="department" column="dept_id" class="Department"/>
- <property name="effectiveStartDate" type="date" column="eff_start_dt"/>
- <property name="effectiveEndDate" type="date" column="eff_end_dt"/>
+ <many-to-one name="department" column="dept_id" class="Department"/>
+ <property name="effectiveStartDate" type="date" column="eff_start_dt"/>
+ <property name="effectiveEndDate" type="date" column="eff_end_dt"/>
...
- <!--
+ <!--
Note that this assumes non-terminal records have an eff_end_dt set to
a max db date for simplicity-sake
- -->
- <filter name="effectiveDate"
- condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
-</class>
+ -->
+ <filter name="effectiveDate"
+ condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
+</class>
-<class name="Department" ...>
+<class name="Department" ...>
...
- <set name="employees" lazy="true">
- <key column="dept_id"/>
- <one-to-many class="Employee"/>
- <filter name="effectiveDate"
- condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
- </set>
-</class>]]></programlisting>
+ <set name="employees" lazy="true">
+ <key column="dept_id"/>
+ <one-to-many class="Employee"/>
+ <filter name="effectiveDate"
+ condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
+ </set>
+</class></programlisting>
- <para>
- In order to ensure that you are provided with currently effective records,
- enable the filter on the session prior to retrieving employee data:
- </para>
+ <para>In order to ensure that you are provided with currently effective
+ records, enable the filter on the session prior to retrieving employee
+ data:</para>
-<programlisting role="JAVA"><![CDATA[Session session = ...;
+ <programlisting role="JAVA">Session session = ...;
session.enableFilter("effectiveDate").setParameter("asOfDate", new Date());
-List results = session.createQuery("from Employee as e where e.salary > :targetSalary")
+List results = session.createQuery("from Employee as e where e.salary > :targetSalary")
.setLong("targetSalary", new Long(1000000))
.list();
-]]></programlisting>
+</programlisting>
- <para>
- Even though a salary constraint was mentioned explicitly on the results in the above HQL,
- because of the enabled filter, the query will return only currently active employees who have
- a salary greater than one million dollars.
- </para>
+ <para>Even though a salary constraint was mentioned explicitly on the
+ results in the above HQL, because of the enabled filter, the query will
+ return only currently active employees who have a salary greater than one
+ million dollars.</para>
- <para>
- If you want to use filters with outer joining, either through HQL or load fetching, be
- careful of the direction of the condition expression. It is safest to set this up for left
- outer joining. Place the parameter first followed by the column name(s) after
- the operator.
- </para>
+ <para>If you want to use filters with outer joining, either through HQL or
+ load fetching, be careful of the direction of the condition expression. It
+ is safest to set this up for left outer joining. Place the parameter first
+ followed by the column name(s) after the operator.</para>
- <para>
- After being defined, a filter might be attached to multiple entities and/or
- collections each with its own condition. This can be problematic when the
- conditions are the same each time. Using <literal><filter-def/></literal>
- allows you to definine a default condition, either as an attribute or CDATA:
- </para>
+ <para>After being defined, a filter might be attached to multiple entities
+ and/or collections each with its own condition. This can be problematic
+ when the conditions are the same each time. Using
+ <literal><filter-def/></literal> allows you to definine a default
+ condition, either as an attribute or CDATA:</para>
- <programlisting role="XML"><![CDATA[<filter-def name="myFilter" condition="abc > xyz">...</filter-def>
-<filter-def name="myOtherFilter">abc=xyz</filter-def>]]></programlisting>
+ <programlisting role="XML"><filter-def name="myFilter" condition="abc > xyz">...</filter-def>
+<filter-def name="myOtherFilter">abc=xyz</filter-def></programlisting>
- <para>
- This default condition will be used whenever the filter is attached to something
- without specifying a condition. This means you can give a specific condition
- as part of the attachment of the filter that overrides the default condition in that
- particular case.
- </para>
-
- </section>
-
+ <para>This default condition will be used whenever the filter is attached
+ to something without specifying a condition. This means you can give a
+ specific condition as part of the attachment of the filter that overrides
+ the default condition in that particular case.</para>
+ </section>
</chapter>
-
More information about the hibernate-commits
mailing list