Hibernate.orgCommunity Documentation

Capítulo 4. Classes Persistentes

4.1. Um exemplo simples de POJO
4.1.1. Implemente um construtor de não argumento
4.1.2. Provide an identifier property
4.1.3. Prefer non-final classes (semi-optional)
4.1.4. Declare acessores e mutadores para campos persistentes (opcional)
4.2. Implementando herança
4.3. Implementando equals() e hashCode()
4.4. Modelos dinâmicos
4.5. Tuplizadores
4.6. EntityNameResolvers

Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). The term "persistent" here means that the classes are able to be persisted, not that they are in the persistent state (see Seção 11.1, “Estado dos objetos no Hibernate” for discussion).

Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO) programming model. However, none of these rules are hard requirements. Indeed, Hibernate assumes very little about the nature of your persistent objects. You can express a domain model in other ways (using trees of java.util.Map instances, for example).

Exemplo 4.1. Simple POJO representing a cat

package eg;

import java.util.Set;
import java.util.Date;
public class Cat {
private Long id; // identifier
private Date birthdate;
private Color color;
private char sex;
private float weight;
    private int litterId;
    private Cat mother;
    private Set kittens = new HashSet();
    private void setId(Long id) {
        this.id=id;
    }
    public Long getId() {
        return id;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    public Date getBirthdate() {
        return birthdate;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }
    public float getWeight() {
        return weight;
    }
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
    public char getSex() {
        return sex;
    }
    void setLitterId(int id) {
        this.litterId = id;
    }
    public int getLitterId() {
        return litterId;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }
    public Cat getMother() {
        return mother;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    public Set getKittens() {
        return kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kitten.setMother(this);
    kitten.setLitterId( kittens.size() );
        kittens.add(kitten);
    }
}

As quatro regras principais das classes persistentes são descritas em maiores detalhes nas seguintes seções.

Cat has a property named id. This property maps to the primary key column(s) of the underlying database table. The type of the identifier property can be any "basic" type (see ???). See Seção 9.4, “Componentes como identificadores compostos” for information on mapping composite (multi-column) identifiers.

Nota

Identifiers do not necessarily need to identify column(s) in the database physically defined as a primary key. They should just identify columns that can be used to uniquely identify rows in the underlying table.

Recomendamos que você declare propriedades de identificador nomeados de forma consistente nas classes persistentes e que você use um tipo anulável (ou seja, não primitivo).

A central feature of Hibernate, proxies (lazy loading), depends upon the persistent class being either non-final, or the implementation of an interface that declares all public methods. You can persist final classes that do not implement an interface with Hibernate; you will not, however, be able to use proxies for lazy association fetching which will ultimately limit your options for performance tuning. To persist a final class which does not implement a "full" interface you must disable proxy generation. See Exemplo 4.2, “Disabling proxies in hbm.xml” and Exemplo 4.3, “Disabling proxies in annotations”.



If the final class does implement a proper interface, you could alternatively tell Hibernate to use the interface instead when generating the proxies. See Exemplo 4.4, “Proxying an interface in hbm.xml” and Exemplo 4.5, “Proxying an interface in annotations”.



You should also avoid declaring public final methods as this will again limit the ability to generate proxies from this class. If you want to use a class with public final methods, you must explicitly disable proxying. Again, see Exemplo 4.2, “Disabling proxies in hbm.xml” and Exemplo 4.3, “Disabling proxies in annotations”.

Uma subclasse também deve observar as primeiras e segundas regras. Ela herda sua propriedade de identificador a partir das superclasses, Cat. Por exemplo:

package eg;


public class DomesticCat extends Cat {
        private String name;
        public String getName() {
                return name;
        }
        protected void setName(String name) {
                this.name=name;
        }
}

Você precisa substituir os métodos equals() e hashCode() se você:

O Hibernate garante a equivalência de identidades persistentes (linha de base de dados) e identidade Java somente dentro de um certo escopo de sessão. Dessa forma, assim que misturarmos instâncias recuperadas em sessões diferentes, devemos implementar equals() e hashCode() se quisermos ter semânticas significativas para os Sets.

A forma mais óbvia é implementar equals()/hashCode() comparando o valor do identificador de ambos objetos. Caso o valor seja o mesmo, ambos devem ter a mesma linha de base de dados, assim eles serão iguais (se ambos forem adicionados a um Set, nós só teremos um elemento no Set). Infelizmente, não podemos usar esta abordagem com os identificadores gerados. O Hibernate atribuirá somente os valores de identificadores aos objetos que forem persistentes, uma instância recentemente criada não terá nenhum valor de identificador. Além disso, se uma instância não for salva e estiver em um Set, salvá-la atribuirá um valor de identificador ao objeto. Se equals() e hashCode() fossem baseados em um valor identificador, o código hash teria mudado, quebrando o contrato do Set. Consulte o website do Hibernate para acessar uma discussão completa sobre este problema. Note que esta não é uma edição do Hibernate, e sim semânticas naturais do Java de igualdade e identidade.

Recomendamos implementar equals() e hashCode() usando Business key equality. A chave de negócios significa que o método equals() compara somente a propriedade que formar uma chave de negócios, uma chave que identificaria nossa instância na realidade (uma chave de candidato natural):

public class Cat {


    ...
    public boolean equals(Object other) {
        if (this == other) return true;
        if ( !(other instanceof Cat) ) return false;
        final Cat cat = (Cat) other;
        if ( !cat.getLitterId().equals( getLitterId() ) ) return false;
        if ( !cat.getMother().equals( getMother() ) ) return false;
        return true;
    }
    public int hashCode() {
        int result;
        result = getMother().hashCode();
        result = 29 * result + getLitterId();
        return result;
    }
}

A business key does not have to be as solid as a database primary key candidate (see Seção 13.1.3, “Considerando a identidade do objeto”). Immutable or unique properties are usually good candidates for a business key.

Entidades persistentes não precisam ser representadas como classes POJO ou como objetos JavaBeans em tempo de espera. O Hibernate também suporta modelos dinâmicos (usando Maps de Maps em tempo de execução) e a representação de entidades como árvores DOM4J. Com esta abordagem, você não escreve classes persistes, somente arquivos de mapeamentos.

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular SessionFactory using the default_entity_mode configuration option (see Tabela 3.3, “Propriedades de Configuração do Hibernate”).

Os seguintes exemplos demonstram a representação usando Maps. Primeiro, no arquivo de mapeamento, um entity-name precisa ser declarado ao invés de (ou além de) um nome de classe:


<hibernate-mapping>

    <class entity-name="Customer">

        <id name="id"
            type="long"
            column="ID">
            <generator class="sequence"/>
        </id>

        <property name="name"
            column="NAME"
            type="string"/>

        <property name="address"
            column="ADDRESS"
            type="string"/>

        <many-to-one name="organization"
            column="ORGANIZATION_ID"
            class="Organization"/>

        <bag name="orders"
            inverse="true"
            lazy="false"
            cascade="all">
            <key column="CUSTOMER_ID"/>
            <one-to-many class="Order"/>
        </bag>

    </class>
    
</hibernate-mapping>

Note que embora as associações sejam declaradas utilizando nomes de classe, o tipo alvo de uma associação pode também ser uma entidade dinâmica, ao invés de um POJO.

Após ajustar o modo de entidade padrão para dynamic-map para a SessionFactory, você poderá trabalhar com Maps de Maps no período de execução:

Session s = openSession();

Transaction tx = s.beginTransaction();
// Create a customer
Map david = new HashMap();
david.put("name", "David");
// Create an organization
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");
// Link both
david.put("organization", foobar);
// Save both
s.save("Customer", david);
s.save("Organization", foobar);
tx.commit();
s.close();

As vantagens de um mapeamento dinâmico são o tempo de retorno rápido para realizar o protótipo sem a necessidade de implementar uma classe de entidade. No entanto, você perde o tipo de tempo de compilação, verificando e muito provavelmente terá que lidar com muitas exceções de tempo de espera. Graças ao mapeamento do Hibernate, o esquema do banco de dados pode ser facilmente normalizado e seguro, permitindo adicionar uma implementação modelo de domínio apropriado na camada do topo num futuro próximo.

Modos de representação de entidade podem ser também ajustados para base por Session:

Session dynamicSession = pojoSession.getSession(EntityMode.MAP);


// Create a customer
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close()
...
// Continue on pojoSession

Por favor, note que a chamada para a getSession() usando um EntityMode está na API de Session e não na SessionFactory. Dessa forma, a nova Session compartilha a conexão, transação e outra informação de contexto JDBC adjacente. Isto significa que você não precisará chamar flush() e close() na Session secundária, e também deixar a transação e o manuseio da conexão para a unidade primária do trabalho.

More information about the XML representation capabilities can be found in Capítulo 20, Mapeamento XML.

org.hibernate.tuple.Tuplizer and its sub-interfaces are responsible for managing a particular representation of a piece of data given that representation's org.hibernate.EntityMode. If a given piece of data is thought of as a data structure, then a tuplizer is the thing that knows how to create such a data structure, how to extract values from such a data structure and how to inject values into such a data structure. For example, for the POJO entity mode, the corresponding tuplizer knows how create the POJO through its constructor. It also knows how to access the POJO properties using the defined property accessors.

There are two (high-level) types of Tuplizers:

Users can also plug in their own tuplizers. Perhaps you require that java.util.Map implementation other than java.util.HashMap be used while in the dynamic-map entity-mode. Or perhaps you need to define a different proxy generation strategy than the one used by default. Both would be achieved by defining a custom tuplizer implementation. Tuplizer definitions are attached to the entity or component mapping they are meant to manage. Going back to the example of our Customer entity, Exemplo 4.6, “Specify custom tuplizers in annotations” shows how to specify a custom org.hibernate.tuple.entity.EntityTuplizer using annotations while Exemplo 4.7, “Specify custom tuplizers in hbm.xml” shows how to do the same in hbm.xml



org.hibernate.EntityNameResolver is a contract for resolving the entity name of a given entity instance. The interface defines a single method resolveEntityName which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and would indicate that the resolver does not know how to resolve the entity name of the given entity instance). Generally speaking, an org.hibernate.EntityNameResolver is going to be most useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The hibernate test suite has an example of this exact style of usage under the org.hibernate.test.dynamicentity.tuplizer2. Here is some of the code from that package for illustration.

/**

 * A very trivial JDK Proxy InvocationHandler implementation where we proxy an
 * interface as the domain model and simply store persistent state in an internal
 * Map.  This is an extremely trivial example meant only for illustration.
 */
public final class DataProxyHandler implements InvocationHandler {
        private String entityName;
        private HashMap data = new HashMap();
        public DataProxyHandler(String entityName, Serializable id) {
                this.entityName = entityName;
                data.put( "Id", id );
        }
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                String methodName = method.getName();
                if ( methodName.startsWith( "set" ) ) {
                        String propertyName = methodName.substring( 3 );
                        data.put( propertyName, args[0] );
                }
                else if ( methodName.startsWith( "get" ) ) {
                        String propertyName = methodName.substring( 3 );
                        return data.get( propertyName );
                }
                else if ( "toString".equals( methodName ) ) {
                        return entityName + "#" + data.get( "Id" );
                }
                else if ( "hashCode".equals( methodName ) ) {
                        return new Integer( this.hashCode() );
                }
                return null;
        }
        public String getEntityName() {
                return entityName;
        }
        public HashMap getData() {
                return data;
        }
}
public class ProxyHelper {
    public static String extractEntityName(Object object) {
        // Our custom java.lang.reflect.Proxy instances actually bundle
        // their appropriate entity name, so we simply extract it from there
        // if this represents one of our proxies; otherwise, we return null
        if ( Proxy.isProxyClass( object.getClass() ) ) {
            InvocationHandler handler = Proxy.getInvocationHandler( object );
            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {
                DataProxyHandler myHandler = ( DataProxyHandler ) handler;
                return myHandler.getEntityName();
            }
        }
        return null;
    }
    // various other utility methods ....
}
/**
 * The EntityNameResolver implementation.
 *
 * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names
 * should be resolved.  Since this particular impl can handle resolution for all of our
 * entities we want to take advantage of the fact that SessionFactoryImpl keeps these
 * in a Set so that we only ever have one instance registered.  Why?  Well, when it
 * comes time to resolve an entity name, Hibernate must iterate over all the registered
 * resolvers.  So keeping that number down helps that process be as speedy as possible.
 * Hence the equals and hashCode implementations as is
 */
public class MyEntityNameResolver implements EntityNameResolver {
    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();
    public String resolveEntityName(Object entity) {
        return ProxyHelper.extractEntityName( entity );
    }
    public boolean equals(Object obj) {
        return getClass().equals( obj.getClass() );
    }
    public int hashCode() {
        return getClass().hashCode();
    }
}
public class MyEntityTuplizer extends PojoEntityTuplizer {
        public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {
                super( entityMetamodel, mappedEntity );
        }
        public EntityNameResolver[] getEntityNameResolvers() {
                return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };
        }
    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {
        String entityName = ProxyHelper.extractEntityName( entityInstance );
        if ( entityName == null ) {
            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );
        }
        return entityName;
    }
    ...

Com o objetivo de registrar um org.hibernate.EntityNameResolver, os usuários devem tanto:

  1. Implement a custom tuplizer (see Seção 4.5, “Tuplizadores”), implementing the getEntityNameResolvers method

  2. Registrá-lo com o org.hibernate.impl.SessionFactoryImpl (que é a classe de implementação para org.hibernate.SessionFactory) usando o método registerEntityNameResolver.