Hibernate.orgCommunity Documentation
As classes persistentes são classes dentro de um aplicativo que implementa as entidades de problemas de negócios (ex.: Cliente e Pedido em um aplicativo e-commerce). Nem todas as instâncias de uma classe persistente estão em estado persistente, uma instância pode, ao invés disso, ser transiente ou desanexada.
O Hibernate trabalha melhor se estas classes seguirem uma regra simples, também conhecida como modelo de programação Objeto de Java Antigo Simples (POJO). No entanto, nenhuma destas regras são difíceis solicitações. Certamente, o Hibernate3 considera muito pouco da natureza de seus objetos persistentes. Você pode expressar um modelo de domínio de outras formas (por exemplo: utilizando árvores de instâncias Map).
A maior parte dos aplicativos Java requerem uma classe persistente que representa os felinos. Por exemplo:
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 possui um construtor de não argumento. Todas as classes persistentes devem ter um construtor padrão (que não pode ser público), para que o Hibernate possa instanciá-lo utilizando um Constructor.newInstance(). Nós recomendamos enfaticamente ter um construtor padrão com ao menos uma visibilidade package para a geração de um proxy de tempo de espera no Hibernate.
Cat possui uma propriedade chamada id. Esta propriedade mapeia para a coluna de chave primária de uma tabela de banco de dados. A propriedade pode ter sido chamada por qualquer nome e seu tipo pode ter sido qualquer um primitivo, ou qualquer tipo "wrapper", java.lang.String ou java.util.Date. Se sua tabela de banco de dados de legacia possuir chaves compostas, você também poderá usar uma classe de usuário definido, com propriedades destes tipos (veja a seção de identificadores compostos mais adiante.)
A propriedade de identificador é estritamente opcional. Você pode deixá-los desligados e deixar que o Hibernate encontre os identificadores de objeto internamente. No entanto, não recomendamos que faça isto.
Na verdade, algumas funcionalidades estão disponíveis somente para classes que declaram uma propriedade de identificador:
Transitive reattachment for detached objects (cascade update or cascade merge) - see Seção 10.11, “Persistência Transitiva”
Session.saveOrUpdate()
Session.merge()
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).
Um recurso central do Hibernate, proxies, depende da classe persistente ser tanto não final como uma implementação de uma interface que declare todos os métodos públicos.
Você pode persistir as classes final que não implementam uma interface com o Hibernate, mas não poderá usar os proxies para busca por associação lazy, que irá limitar suas opções para ajuste de desempenho.
Você deve evitar declarar métodos public final em classes não finais. Se você desejar usar uma classe com um método public final você deve desabilitar o proxy explicitamente, ajustando lazy="false".
Cat declara os métodos assessores para todos os seus campos persistentes. Muitas ferramentas ORM persistem diretamente variáveis de instâncias. Acreditamos ser melhor prover uma indireção entre o esquema relacional e as estruturas de dados internos da classe. Por padrão, o Hibernate persiste as propriedades de estilo JavaBeans, e reconhece nomes de métodos da forma getFoo, isFoo e setFoo. Caso solicitado, você pode mudar para direcionar acesso ao campo para certas propriedades, caso seja necessário.
As propriedades precisam not ser declaradas como públicas. O Hibernate pode persistir uma propriedade com um par get/set padrão protegido ou privado.
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ê:
pretender inserir instâncias de classes persistentes em um Set (a forma mais recomendada é representar associações de muitos valores), e
pretender usar reconexão de instâncias desanexadas
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 12.1.3, “Considerando a identidade do objeto”). Immutable or unique properties are usually good candidates for a business key.
The following features are currently considered experimental and may change in the near future.
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 19, Mapeamento XML.
org.hibernate.tuple.Tuplizer, e suas sub-interfaces, são responsáveis por gerenciar uma certa representação de uma parte de dado, dada a org.hibernate.EntityMode da representação. Se uma parte de dado é tida como uma estrutura de dado, então o tuplizador se encarrega de criar tal estrutura de dado e como extrair e injetar valores de e em tal estrutura de dados. Por exemplo, para um modo POJO, o tuplizador correspondente sabe como criar um POJO através de seu construtor. Além disso, ele sabe como acessar propriedades de POJO usando assessores de propriedades definidas.
Existem dois tipos de alto nível de Tuplizadores, representados pelas interfaces org.hibernate.tuple.entity.EntityTuplizer e org.hibernate.tuple.component.ComponentTuplizer. Os EntityTuplizers são responsáveis pelo gerenciamento dos contratos mencionados acima em relação às entidades, enquanto os ComponentTuplizers realizam o mesmo para os componentes.
Os usuários podem também plugar seu próprio tuplizador. Talvez você queira usar uma implementação java.util.Map ao invés de uma java.util.HashMap enquanto estiver no modo de entidade mapa dinâmico, ou talvez você precise definir uma estratégia de geração de proxy diferente, ao invés de uma utilizada por padrão. Ambas seriam alcançadas definindo uma implementação de tuplizador personalizada. As definições do tuplizador estão anexadas à entidade ou ao mapeamento de componente que tiverem que gerenciar. Retornando ao exemplo da entidade do nosso cliente:
<hibernate-mapping>
<class entity-name="Customer">
<!--
Override the dynamic-map entity-mode
tuplizer for the customer entity
-->
<tuplizer entity-mode="dynamic-map"
class="CustomMapTuplizerImpl"/>
<id name="id" type="long" column="ID">
<generator class="sequence"/>
</id>
<!-- other properties -->
...
</class>
</hibernate-mapping>
public class CustomMapTuplizerImpl
extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {
// override the buildInstantiator() method to plug in our custom map...
protected final Instantiator buildInstantiator(
org.hibernate.mapping.PersistentClass mappingInfo) {
return new CustomMapInstantiator( mappingInfo );
}
private static final class CustomMapInstantiator
extends org.hibernate.tuple.DynamicMapInstantitor {
// override the generateMap() method to return our custom map...
protected final Map generateMap() {
return new CustomMap();
}
}
}
A interface org.hibernate.EntityNameResolver é um contrato para resolver o nome da entidade de uma instância de entidade dada. A interface define um resolveEntityName de método único que é passado à instância de entidade e é esperado a retornar ao nome de entidade apropriado (nulo é permitido e indicaria que o solucionador não saiba como resolver o nome de entidade da instância de entidade dada). Normalmente, um org.hibernate.EntityNameResolver será mais útil no caso de modelos dinâmicos. Um exemplo poderá ser usado nas interfaces com proxie no caso dos modelos dinâmicos. O hibernate test suite possui um exemplo deste estilo exato de uso sob o org.hibernate.test.dynamicentity.tuplizer2. Segue abaixo parte do código a partir daquele pacote para ilustração.
/**
* 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 impls
*/
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:
Implementar um Tuplizer personalizado, implementando o método getEntityNameResolvers.
Registrá-lo com o org.hibernate.impl.SessionFactoryImpl (que é a classe de implementação para org.hibernate.SessionFactory) usando o método registerEntityNameResolver.
Copyright © 2004 Red Hat, Inc.