Hibernate.org Community Documentation

- Anterior
- Próxima

## Capítulo 19. Filtrando dados

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.

## 19.1. Filtros 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.

Exemplo 19.1. @FilterDef and @Filter annotations

    @Entity

    @FilterDef(name="minLength", parameters=@ParamDef( name="minLength", type="integer" ) )

    @Filters( {

        @Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length"),

        @Filter(name="minLength", condition=":minLength <= length")

    } )

    public class Forest { ... }

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.

Exemplo 19.2. Using `@FilterJoinTable` for filterting on the association table

    @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() { ... }

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:

Exemplo 19.3. Defining a filter definition via `<filter-def>`

    <filter-def name="myFilter">

        <filter-param name="myFilterParam" type="string"/>

    </filter-def>

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

Exemplo 19.4. Attaching a filter to a class or collection using `<filter>`

    <class name="myClass" ...>

        ...

        <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>

        <set ...>

            <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>

        </set>

    </class>

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.

Copyright © 2004 Red Hat, Inc.

- AnteriorCapítulo 18. SQL Nativo
- Acima
- Principal
- PróximaCapítulo 20. Mapeamento XML