JBoss Seam is very rich and powerful framework but some of its features are badly documented.
Hibernate Filters is one of these forgotten features. In fact filters documentation in Seam is rather useless.
I won’t explain in details Hibernate Filters here. Hibernate documentation does it ways better. To make short it’s a smart solution to add conditions to the “where” clause of a request at runtime.
To create such a filter in Seam, one will also have to read Hibernate annotations on that matter.
For instance let say we have an used cars stock for which we had developed a bunch of forms and pages to search and navigate through it. We also created a Seam component to handle a requests collection to populate search form’s combo box fields and orchestrate all the search and navigation.
In database, cars have a “stockVoLib” field which gives car origin (demonstration, management car, etc…). Until now this field wasn’t used by the application and search were done on all the stock db. But now, our customer ask for a new navigation having exactly the same look at the first one but restricted on a given car origin.
We can answer to this request in two different ways.
- Refactor all the running website’s engine to introduce the new “stcokVoLib” parameter in all the requests and code calling these requests
- Create a filter which will save us a lot of refactoring work on existing code.
Guess what ? I prefer to create a filter 
(good news for the end of this post).
1.Hibernate filter creation with annotations
First thing to do : define the filter. We can dot it in the target entity or at the package level. As a filter can be applied to more than one entity I prefer the package level option. So I add a “package-info.java” file to my entities package to define the filter in it.
@FilterDef(name = "stockLib", defaultCondition = "stockLibele = :aStockLib", parameters = @ParamDef(name = "aStockLib", type = "string")) package org.fpp.domain; import org.hibernate.annotations.FilterDef; import org.hibernate.annotations.ParamDef;
The name of the filter is “stockLib”, it has a default condition which will be used if there is no condition defined when the filter is applied on the entity and it also has one string parameter : “aStockLib”.
Keep in mind that the condition defined here is not a HQL “where” but a SQL one.
After that I apply the filter on one or more entities (I could also attach it to a collection). In my use case I only have one entity concerned : “usedCar”.
@Entity
@Filter(name = "stockLib")
public class usedCar {
...
3.Using the filter with Hibernate
Now, I can use the filter with Hibernate. I can activate it and send it parameter values by getting Hibernate session (if we are using JPA we do that with EntityManager.getDelegate())
Session session=(Session) entityManager.getDelegate();
session.enableFilter("stockLib").setParameter("aStockLib", "VD");
...
session.disableFilter("stockLib");
3.What about Seam ?
You can do better with Seam by creating a filter component (wraping Hibernate filter) in which you can inject parameter at runtime.
We only have to have this component in the Seam components.xml file.
<persistence:filter name="stockLibFilter">
<persistence:name>stockLib</persistence:name>
<persistence:parameters>
<key>aStockLib</key>
<value>#{parameterHdl.stockLib}</value>
</persistence:parameters>
</persistence:filter>
Remember that parameters value in this “meta-filter” should always be expressed in expression language even if we want inject a constant : #{‘VD’}.
In our example “parameterHdl” is a Seam component in which the stockLib parameter is injected from the URL according tto the the following configuration in pages.xml
<param name="stockLib" value="#{parameterHdl.stockLib}" required="false"/>
At that point Seam filter can be injected in a specific EntityManager on which the filter will be always activated.
<persistence:managed-persistence-context name="emStockLib" auto-create="true" persistence-unit-jndi-name="java:/fppEntityManagerFactory" >
<persistence:filters>
<value>#{stockLibFilter}</value>
</persistence:filters>
</persistence:managed-persistence-context>
This new entityManager could be injected in components instead of the standard entityManager (without filter). There is nothing to do to activate the filter, it is on by default.
But that’s not all !
4.Dynamic filters activation in Seam
It’s here that Seam documentation is lacking something very useful : filters activation can be dynamically set at run time.
Thus we can write someting like :
<persistence:filter name="stockLibFilter" enabled="#{!(empty parameterHdl.stockLib)}">
<persistence:name>stockLib</persistence:name>
<persistence:parameters>
<key>aStockLib</key>
<value>#{parameterHdl.stockLib}</value>
</persistence:parameters>
</persistence:filter>
Pay attention to the “enabled” parameter in which we put a boolean expression. It means that the filter is activated only if stockLib field of component parameterHdl is not empty. As this field is filled by URL parameter injection, an existing stockLib parameter in URL activate the filter.
In this usage we can apply the filter to the application’s main entityManager (no need to create a specific one) and this filter will be activated if its enabled parameter is satisfied. This test will be evaluated each time the entityManager is called (that’s Seam’s “magic”).
<persistence:managed-persistence-context name="entityManager" auto-create="true" persistence-unit-jndi-name="java:/fppEntityManagerFactory" >
<persistence:filters>
<value>#{stockLibFilter}</value>
</persistence:filters>
</persistence:managed-persistence-context>
So we have injected a dynamically activated Hibernate filter in the entityManager and its activation will depend of the application context.
One last thing to keep in mind : if the enabled parameter of the filter uses a Seam component (like in my example), you should not inject the “filtered” entityManager in this component. If you did you would get an exception at the application launch caused by the circular reference.
