Hibernate.orgCommunity Documentation

Capítulo 19. Filtrando dados

19.1. Filtros do Hibernate

O Hibernate3 provê um novo método inovador para manusear dados com regras de "visibilidade". Um Filtro do Hibernate é um filtro global, nomeado e parametrizado que pode ser habilitado ou não dentro de uma Sessão do Hibernate.

O Hibernate3 tem a habilidade de pré-definir os critérios do filtro e anexar esses filtros no nível da classe e no nível da coleção. Um critério do filtro é a habilidade de definir uma cláusula restritiva muito semelhante à função "where" disponível para a classe e várias coleções. A não ser que essas condições de filtros possam ser parametrizadas. A aplicação pode, então decidir, em tempo de execução, se os filtros definidos devem estar habilitados e quais valores seus parâmetros devem ter. Os filtros podem ser usados como Views de bancos de dados, mas com parâmetros dentro da aplicação.

Using annotatons filters are defined via @org.hibernate.annotations.FilterDef or @org.hibernate.annotations.FilterDefs. A filter definition has a name() 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 @ParamDef which has a name and a type. You can also define a defaultCondition() parameter for a given @FilterDef to set the default condition to use when none are defined in each individual @Filter. @FilterDef(s) can be defined at the class or package level.

We now need to define the SQL filter clause applied to either the entity load or the collection load. @Filter is used and placed either on the entity or the collection element. The connection between @FilterName and @Filter is a matching name.


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 @Filter annotation. However, if you want to target the association table, use the @FilterJoinTable annotation.


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 <filter-def/> element within a <hibernate-mapping/> element:


This filter can then be attached to a class or collection (or, to both or multiples of each at the same time):


Os métodos na Session são: enableFilter(String filterName), getEnabledFilter(String filterName) e disableFilter(String filterName). Por padrão, os filtros não são habilitados dentro de qualquer sessão. Eles devem ser explicitamente habilitados usando o método Session.enabledFilter(), que retorna uma instância da interface Filter. Usando o filtro simples definido acima, o código se pareceria com o seguinte:

session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");

Veja que os métodos da interface org.hibernate.Filter permite o encadeamento do método, comum à maioria das funções do Hibernate.

Um exemplo completo, usando dados temporais com um padrão de datas de registro efetivo:


<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"/>
...
    <!--
        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>

<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>

Para garantir que você sempre tenha registro efetivos, simplesmente habilite o filtro na sessão antes de recuperar os dados dos empregados:

Session session = ...;

session.enableFilter("effectiveDate").setParameter("asOfDate", new Date());
List results = session.createQuery("from Employee as e where e.salary > :targetSalary")
         .setLong("targetSalary", new Long(1000000))
         .list();

No HQL acima, mesmo que tenhamos mencionado apenas uma restrição de salário nos resultados, por causa do filtro habilitado, a consulta retornará apenas os funcionários ativos cujo salário é maior que um milhão de dólares.

Nota: se você planeja usar filtros com união externa (por HQL ou por busca de carga) seja cuidadoso quanto à direção da expressão de condição. É mais seguro configurá-lo para uma união externa esquerda. Coloque o parâmetro primeiro seguido pelo(s) nome(s) da coluna após o operador.

Após ser definido, o filtro deve ser anexado às entidades múltiplas e/ou coleções, cada uma com sua própria condição. Isto pode ser tedioso quando as condições se repetem. Assim, usando o <filter-def/> permite denifir uma condição padrão, tanto como uma função quanto CDATA:


<filter-def name="myFilter" condition="abc > xyz">...</filter-def>
<filter-def name="myOtherFilter">abc=xyz</filter-def>

Esta condição padrão será utilizada todas as vezes que um filtro for anexado a algo sem uma condição específica. Note que isto significa que você pode dar uma condição específica como parte de um anexo de filtro que substitua a condição padrão neste caso em particular.