hibernate reference

HIBERNATE - PersistnciaRelacional para Java Idiomtico

1

Documentao deReferncia Hibernate

3.6.8.Final

por Gavin King, Christian Bauer, Max Rydahl Andersen,Emmanuel Bernard, Steve Ebersole, e Hardy Ferentschik

and thanks to James Cobb (Graphic Design), Cheyenne Weaver (GraphicDesign), Alvaro Netto, Anderson Braulio, Daniel Vieira Costa, Franciscogamarra, Gamarra, Luiz Carlos Rodrigues, Marcel Castelo, Paulo Csar,

Pablo L. de Miranda, Renato Deggau, Rogrio Arajo, e Wanderson Siqueira

iii

Prefcio ............................................................................................................................ xi1. Tutorial ........................................................................................................................ 1

1.1. Parte 1 A primeira aplicao Hibernate ............................................................. 11.1.1. Configurao ........................................................................................... 11.1.2. A primeira Classe .................................................................................... 31.1.3. O mapeamento do arquivo ....................................................................... 41.1.4. Configurao do Hibernate ....................................................................... 71.1.5. Construindo com o Maven ........................................................................ 91.1.6. Inicializao e Auxiliares ......................................................................... 101.1.7. Carregando e salvando objetos ............................................................... 11

1.2. Parte 2 - Mapeando associaes ....................................................................... 141.2.1. Mapeando a classe Person .................................................................... 141.2.2. Uma associao unidirecional baseada em Configurao ......................... 151.2.3. Trabalhando a associao ...................................................................... 161.2.4. Coleo de valores ................................................................................ 181.2.5. Associaes bidirecionais ....................................................................... 201.2.6. Trabalhando com links bidirecionais ........................................................ 21

1.3. EventManager um aplicativo da web .................................................................. 221.3.1. Criando um servlet bsico ...................................................................... 221.3.2. Processando e renderizando ................................................................... 231.3.3. Implementando e testando ...................................................................... 25

1.4. Sumrio ............................................................................................................ 262. Arquitetura ................................................................................................................. 27

2.1. Viso Geral ...................................................................................................... 272.1.1. Minimal architecture ............................................................................... 272.1.2. Comprehensive architecture .................................................................... 282.1.3. Basic APIs ............................................................................................. 29

2.2. Integrao JMX ................................................................................................ 302.3. Sesses Contextuais ......................................................................................... 30

3. Configuration ............................................................................................................. 333.1. Configurao programtica ................................................................................ 333.2. Obtendo uma SessionFactory ............................................................................ 343.3. Conexes JDBC ............................................................................................... 343.4. Propriedades opcionais de configurao ............................................................ 36

3.4.1. Dialetos SQL ......................................................................................... 443.4.2. Busca por unio externa (Outer Join Fetching) ......................................... 453.4.3. Fluxos Binrios (Binary Streams) ............................................................ 463.4.4. Cach de segundo nvel e consulta ......................................................... 463.4.5. Substituio na Linguagem de Consulta .................................................. 463.4.6. Estatsticas do Hibernate ........................................................................ 46

3.5. Logging ............................................................................................................ 473.6. Implementando um NamingStrategy ................................................................... 473.7. Implementing a PersisterClassProvider .............................................................. 483.8. Arquivo de configurao XML ............................................................................ 49

HIBERNATE - Persistncia Rela...

iv

3.9. Java EE Application Server integration ............................................................... 503.9.1. Configurao de estratgia de transao ................................................. 503.9.2. SessionFactory vinculada JNDI ............................................................ 523.9.3. Gerenciamento de contexto de Sesso atual com JTA ............................. 523.9.4. implementao JMX ............................................................................... 53

4. Classes Persistentes ................................................................................................. 554.1. Um exemplo simples de POJO .......................................................................... 55

4.1.1. Implemente um construtor de no argumento .......................................... 564.1.2. Provide an identifier property .................................................................. 574.1.3. Prefer non-final classes (semi-optional) ................................................... 574.1.4. Declare acessores e mutadores para campos persistentes (opcional) ........ 58

4.2. Implementando herana .................................................................................... 584.3. Implementando equals() e hashCode() ............................................................... 594.4. Modelos dinmicos ........................................................................................... 604.5. Tuplizadores ..................................................................................................... 624.6. EntityNameResolvers ........................................................................................ 63

5. Mapeamento O/R Bsico ........................................................................................... 675.1. Declarao de mapeamento .............................................................................. 67

5.1.1. Entity ..................................................................................................... 705.1.2. Identifiers ............................................................................................... 755.1.3. Optimistic locking properties (optional) ..................................................... 945.1.4. Propriedade ........................................................................................... 975.1.5. Embedded objects (aka components) .................................................... 1065.1.6. Inheritance strategy .............................................................................. 1095.1.7. Mapping one to one and one to many associations ................................. 1205.1.8. Id Natural ............................................................................................. 1295.1.9. Any ...................................................................................................... 1305.1.10. Propriedades ...................................................................................... 1325.1.11. Some hbm.xml specificities ................................................................. 134

5.2. Tipos do Hibernate .......................................................................................... 1385.2.1. Entidades e valores .............................................................................. 1385.2.2. Valores de tipos bsicos ....................................................................... 1395.2.3. Tipos de valores personalizados ........................................................... 141

5.3. Mapeando uma classe mais de uma vez .......................................................... 1425.4. Identificadores quotados do SQL ..................................................................... 1435.5. Propriedades geradas ..................................................................................... 1435.6. Column transformers: read and write expressions ............................................. 1435.7. Objetos de Banco de Dados Auxiliares ............................................................. 145

6. Types ....................................................................................................................... 1476.1. Value types .................................................................................................... 147

6.1.1. Basic value types ................................................................................. 1476.1.2. Composite types .................................................................................. 1536.1.3. Collection types .................................................................................... 153

6.2. Entity types ..................................................................................................... 154

v6.3. Significance of type categories ......................................................................... 1546.4. Custom types .................................................................................................. 154

6.4.1. Custom types using org.hibernate.type.Type .......................................... 1546.4.2. Custom types using org.hibernate.usertype.UserType ............................. 1566.4.3. Custom types using org.hibernate.usertype.CompositeUserType ............. 157

6.5. Type registry ................................................................................................... 1597. Mapeamento de coleo .......................................................................................... 161

7.1. Colees persistentes ..................................................................................... 1617.2. How to map collections ................................................................................... 162

7.2.1. Chaves Externas de Coleo ................................................................ 1667.2.2. Colees indexadas ............................................................................. 1667.2.3. Collections of basic types and embeddable objects ................................. 172

7.3. Mapeamentos de coleo avanados. .............................................................. 1747.3.1. Colees escolhidas ............................................................................. 1747.3.2. Associaes Bidirecionais ..................................................................... 1767.3.3. Associaes bidirecionais com colees indexadas ................................ 1807.3.4. Associaes Ternrias .......................................................................... 1827.3.5. Using an ................................................................................. 182

7.4. Exemplos de colees .................................................................................... 1838. Mapeamento de associaes ................................................................................... 189

8.1. Introduo ...................................................................................................... 1898.2. Associaes Unidirecionais .............................................................................. 189

8.2.1. Muitos-para-um .................................................................................... 1898.2.2. Um-para-um ......................................................................................... 1908.2.3. Um-para-muitos .................................................................................... 191

8.3. Associaes Unidirecionais com tabelas associativas ........................................ 1918.3.1. Um-para-muitos .................................................................................... 1918.3.2. Muitos-para-um .................................................................................... 1928.3.3. Um-para-um ......................................................................................... 1938.3.4. Muitos-para-muitos ............................................................................... 193

8.4. Associaes Bidirecionais ................................................................................ 1948.4.1. Um-para-muitos/muitos-para-um ............................................................ 1948.4.2. Um-para-um ......................................................................................... 195

8.5. Associaes Bidirecionais com tabelas associativas .......................................... 1968.5.1. Um-para-muitos/muitos-para-um ............................................................ 1968.5.2. Um para um ........................................................................................ 1978.5.3. Muitos-para-muitos ............................................................................... 198

8.6. Mapeamento de associaes mais complexas .................................................. 1999. Mapeamento de Componentes ................................................................................ 201

9.1. Objetos dependentes ...................................................................................... 2019.2. Colees de objetos dependentes ................................................................... 2039.3. Componentes como ndices de Map ................................................................ 2049.4. Componentes como identificadores compostos ................................................. 2059.5. Componentes Dinmicos ................................................................................. 207


vi

10. Mapeamento de Herana ....................................................................................... 20910.1. As trs estratgias ........................................................................................ 209

10.1.1. Tabela por hierarquia de classes ......................................................... 20910.1.2. Tabela por subclasse .......................................................................... 21010.1.3. Tabela por subclasse: usando um discriminador ................................... 21110.1.4. Mesclar tabela por hierarquia de classes com tabela por subclasse ........ 21110.1.5. Tabela por classe concreta ................................................................. 21210.1.6. Tabela por classe concreta usando polimorfismo implcito ..................... 21310.1.7. Mesclando polimorfismo implcito com outros mapeamentos de herana .. 214

10.2. Limitaes .................................................................................................... 21511. Trabalhando com objetos ...................................................................................... 217

11.1. Estado dos objetos no Hibernate ................................................................... 21711.2. Tornando os objetos persistentes ................................................................... 21711.3. Carregando o objeto ...................................................................................... 21911.4. Consultando .................................................................................................. 220

11.4.1. Executando consultas ......................................................................... 22011.4.2. Filtrando colees .............................................................................. 22511.4.3. Consulta por critrio ........................................................................... 22611.4.4. Consultas em SQL nativa ................................................................... 226

11.5. Modificando objetos persistentes .................................................................... 22611.6. Modificando objetos desacoplados ................................................................. 22711.7. Deteco automtica de estado ..................................................................... 22811.8. Apagando objetos persistentes ...................................................................... 22911.9. Replicando objeto entre dois armazenamentos de dados diferentes. ................. 22911.10. Limpando a Sesso ..................................................................................... 23011.11. Persistncia Transitiva ................................................................................. 23111.12. Usando metadados ..................................................................................... 234

12. Read-only entities .................................................................................................. 23712.1. Making persistent entities read-only ................................................................ 237

12.1.1. Entities of immutable classes .............................................................. 23812.1.2. Loading persistent entities as read-only ............................................... 23812.1.3. Loading read-only entities from an HQL query/criteria ........................... 23912.1.4. Making a persistent entity read-only ..................................................... 240

12.2. Read-only affect on property type ................................................................... 24112.2.1. Simple properties ................................................................................ 24212.2.2. Unidirectional associations .................................................................. 24312.2.3. Bidirectional associations .................................................................... 245

13. Transaes e Concorrncia ................................................................................... 24713.1. Sesso e escopos de transaes ................................................................... 247

13.1.1. Unidade de trabalho ........................................................................... 24713.1.2. Longas conversaes ......................................................................... 24913.1.3. Considerando a identidade do objeto ................................................... 25013.1.4. Edies comuns ................................................................................. 251

13.2. Demarcao de transaes de bancos de dados ............................................ 251

vii

13.2.1. Ambiente no gerenciado ................................................................... 25213.2.2. Usando JTA ....................................................................................... 25313.2.3. Tratamento de Exceo ...................................................................... 25513.2.4. Tempo de espera de Transao .......................................................... 256

13.3. Controle de concorrncia otimista .................................................................. 25713.3.1. Checagem de verso da aplicao ...................................................... 25713.3.2. Sesso estendida e versionamento automtico .................................... 25813.3.3. Objetos destacados e versionamento automtico .................................. 25913.3.4. Versionamento automtico customizado ............................................... 259

13.4. Bloqueio Pessimista ...................................................................................... 26013.5. Modos para liberar a conexo ........................................................................ 261

14. Interceptadores e Eventos ..................................................................................... 26314.1. Interceptadores ............................................................................................. 26314.2. Sistema de Eventos ...................................................................................... 26514.3. Segurana declarativa do Hibernate ............................................................... 266

15. Batch processing ................................................................................................... 26915.1. Insero em lotes .......................................................................................... 26915.2. Atualizao em lotes ..................................................................................... 27015.3. A interface de Sesso sem Estado ................................................................ 27015.4. Operaes no estilo DML .............................................................................. 271

16. HQL: A Linguagem de Consultas do Hibernate ..................................................... 27516.1. Diferenciao de maiscula e minscula ........................................................ 27516.2. A clusula from ............................................................................................. 27516.3. Associaes e unies .................................................................................... 27616.4. Formas de sintxe de unies ......................................................................... 27816.5. Referncia propriedade do identificador ....................................................... 27816.6. A clusula select ........................................................................................... 27916.7. Funes de agregao .................................................................................. 28016.8. Pesquisas Polimrficas .................................................................................. 28116.9. A clusula where .......................................................................................... 28116.10. Expresses ................................................................................................. 28316.11. A clusula ordenar por ................................................................................ 28716.12. A clusula agrupar por ................................................................................ 28816.13. Subconsultas ............................................................................................... 28816.14. Exemplos de HQL ....................................................................................... 28916.15. Atualizao e correo em lote .................................................................... 29216.16. Dicas & Truques ......................................................................................... 29216.17. Componentes .............................................................................................. 29316.18. Sintxe do construtor de valores de linha ...................................................... 294

17. Consultas por critrios .......................................................................................... 29517.1. Criando uma instncia Criteria ....................................................................... 29517.2. Limitando o conjunto de resultados ................................................................ 29517.3. Ordenando resultados ................................................................................... 29617.4. Associaes .................................................................................................. 297


viii

17.5. Busca de associao dinmica ...................................................................... 29817.6. Exemplos de consultas .................................................................................. 29817.7. Projees, agregaes e agrupamento. .......................................................... 29917.8. Consultas e subconsultas desanexadas. ......................................................... 30117.9. Consultas por um identificador natural ............................................................ 302

18. SQL Nativo ............................................................................................................. 30318.1. Usando um SQLQuery .................................................................................. 303

18.1.1. Consultas Escalares ........................................................................... 30318.1.2. Consultas de Entidade ........................................................................ 30418.1.3. Manuseio de associaes e colees .................................................. 30518.1.4. Retorno de entidades mltiplas ........................................................... 30518.1.5. Retorno de entidades no gerenciadas ................................................ 30718.1.6. Manuseio de herana ......................................................................... 30818.1.7. Parmetros ........................................................................................ 308

18.2. Consultas SQL Nomeadas ............................................................................. 30818.2.1. Utilizando a propriedade retorno para especificar explicitamente osnomes de colunas/alias .................................................................................. 31418.2.2. Usando procedimentos de armazenamento para consultas .................... 315

18.3. SQL padronizado para criar, atualizar e deletar ............................................... 31718.4. SQL padronizado para carga ......................................................................... 319

19. Filtrando dados ...................................................................................................... 32119.1. Filtros do Hibernate ....................................................................................... 321

20. Mapeamento XML ................................................................................................... 32520.1. Trabalhando com dados em XML ................................................................... 325

20.1.1. Especificando o mapeamento de uma classe e de um arquivo XMLsimultaneamente ............................................................................................ 32520.1.2. Especificando somente um mapeamento XML ...................................... 326

20.2. Mapeando metadados com XML .................................................................... 32620.3. Manipulando dados em XML ......................................................................... 328

21. Aumentando o desempenho .................................................................................. 33121.1. Estratgias de Busca .................................................................................... 331

21.1.1. Trabalhando com associaes preguiosas (lazy) ................................. 33221.1.2. Personalizando as estratgias de busca .............................................. 33321.1.3. Proxies de associao final nico ........................................................ 33421.1.4. Inicializando colees e proxies .......................................................... 33621.1.5. Usando busca em lote ........................................................................ 33721.1.6. Usando busca de subseleo .............................................................. 33821.1.7. Perfis de Busca .................................................................................. 33821.1.8. Usando busca preguiosa de propriedade ............................................ 340

21.2. O Cach de Segundo Nvel ........................................................................... 34121.2.1. Mapeamento de Cache ....................................................................... 34221.2.2. Estratgia: somente leitura .................................................................. 34521.2.3. Estratgia: leitura/escrita ..................................................................... 34521.2.4. Estratgia: leitura/escrita no estrita .................................................... 345

ix

21.2.5. Estratgia: transacional ....................................................................... 34521.2.6. Compatibilidade de Estratgia de Concorrncia de Cache Provedor ....... 345

21.3. Gerenciando os caches ................................................................................. 34621.4. O Cache de Consulta .................................................................................... 348

21.4.1. Ativao do cache de consulta ............................................................ 34821.4.2. Regies de cache de consulta ............................................................ 349

21.5. Entendendo o desempenho da Coleo ......................................................... 34921.5.1. Taxonomia ......................................................................................... 34921.5.2. Listas, mapas, bags de id e conjuntos so colees mais eficientes paraatualizar ........................................................................................................ 35021.5.3. As Bags e listas so as colees de inverso mais eficientes. ............... 35121.5.4. Deletar uma vez ................................................................................. 351

21.6. Monitorando desempenho .............................................................................. 35221.6.1. Monitorando uma SessionFactory ........................................................ 35221.6.2. Mtricas ............................................................................................. 353

22. Guia de Toolset ...................................................................................................... 35522.1. Gerao de esquema automtico ................................................................... 355

22.1.1. Padronizando o esquema ................................................................... 35622.1.2. Executando a ferramenta .................................................................... 35922.1.3. Propriedades ...................................................................................... 35922.1.4. Usando o Ant ..................................................................................... 36022.1.5. Atualizaes de esquema incremental ................................................. 36022.1.6. Utilizando Ant para atualizaes de esquema incremental ..................... 36122.1.7. Validao de esquema ....................................................................... 36122.1.8. Utilizando Ant para validao de esquema ........................................... 362

23. Additional modules ................................................................................................ 36323.1. Bean Validation ............................................................................................. 363

23.1.1. Adding Bean Validation ....................................................................... 36323.1.2. Configuration ...................................................................................... 36323.1.3. Catching violations .............................................................................. 36523.1.4. Database schema ............................................................................... 365

23.2. Hibernate Search .......................................................................................... 36623.2.1. Description ......................................................................................... 36623.2.2. Integration with Hibernate Annotations ................................................. 366

24. Exemplo: Pai/Filho ................................................................................................. 36724.1. Uma nota sobre as colees ......................................................................... 36724.2. Bidirecional um-para-muitos ........................................................................... 36724.3. Ciclo de vida em Cascata .............................................................................. 36924.4. Cascatas e unsaved-value ............................................................................. 37124.5. Concluso ..................................................................................................... 371

25. Exemplo: Aplicativo Weblog .................................................................................. 37325.1. Classes Persistentes ..................................................................................... 37325.2. Mapeamentos Hibernate ................................................................................ 37425.3. Cdigo Hibernate .......................................................................................... 376


x

26. Exemplo: Vrios Mapeamentos .............................................................................. 38126.1. Empregador/Empregado ................................................................................ 38126.2. Autor/Trabalho .............................................................................................. 38326.3. Cliente/Ordem/Produto .................................................................................. 38526.4. Exemplos variados de mapeamento ............................................................... 387

26.4.1. Associao um-para-um "Typed" ......................................................... 38726.4.2. Exemplo de chave composta .............................................................. 38826.4.3. Muitos-para-muitos com funo de chave composta compartilhada ........ 39026.4.4. Contedo baseado em discriminao ................................................... 39026.4.5. Associaes em chaves alternativas .................................................... 391

27. Melhores prticas ................................................................................................... 39328. Consideraes da Portabilidade do Banco de Dados ............................................ 397

28.1. Fundamentos da Portabilidade ....................................................................... 39728.2. Dialeto .......................................................................................................... 39728.3. Resoluo do Dialeto .................................................................................... 39728.4. Gerao do identificador ................................................................................ 39828.5. Funes do banco de dados .......................................................................... 39928.6. Tipos de mapeamentos ................................................................................. 399

Referncias ................................................................................................................... 401

xi

Prefcio

Working with both Object-Oriented software and Relational Databases can be cumbersomeand time consuming. Development costs are significantly higher due to a paradigm mismatchbetween how data is represented in objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. The term Object/Relational Mapping refersto the technique of mapping data from an object model representation to a relational data modelrepresentation (and visa versa). See http://en.wikipedia.org/wiki/Object-relational_mapping for agood high-level discussion.

Nota

While having a strong background in SQL is not required to use Hibernate, havinga basic understanding of the concepts can greatly help you understand Hibernatemore fully and quickly. Probably the single best background is an understanding ofdata modeling principles. You might want to consider these resources as a goodstarting point:

http://www.agiledata.org/essays/dataModeling101.html

http://en.wikipedia.org/wiki/Data_modeling

Hibernate not only takes care of the mapping from Java classes to database tables (and fromJava data types to SQL data types), but also provides data query and retrieval facilities. It cansignificantly reduce development time otherwise spent with manual data handling in SQL andJDBC. Hibernates design goal is to relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, hand-crafted data processingusing SQL and JDBC. However, unlike many other persistence solutions, Hibernate does not hidethe power of SQL from you and guarantees that your investment in relational technology andknowledge is as valid as always.

Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernatecan certainly help you to remove or encapsulate vendor-specific SQL code and will help with thecommon task of result set translation from a tabular representation to a graph of objects.

Por favor siga os seguintes passos, caso voc seja inexperiente com o Hibernate, MapeamentoObjeto/Relacional ou mesmo Java:

1. Read Captulo 1, Tutorial for a tutorial with step-by-step instructions. The source code for thetutorial is included in the distribution in the doc/reference/tutorial/ directory.

2. Read Captulo 2, Arquitetura to understand the environments where Hibernate can be used.

Prefcio

xii

3. Verifique no diretrio eg/ em sua distribuio de Hibernate, do qual possui umasimples aplicao autnoma. Copie seu driver JDBC para o diretrio lib/ e edite eg/hibernate.properties, especificando valores corretos para o seu banco de dados. Nodiretrio de distribuio sob o comando aviso, digite ant eg (usando Ant), ou sob Windows,digite build eg.

4. Use this reference documentation as your primary source of information. Consider reading[JPwH] if you need more help with application design, or if you prefer a step-by-step tutorial. Alsovisit http://caveatemptor.hibernate.org and download the example application from [JPwH].

5. As respostas das perguntas mais freqentes podem ser encontradas no website Hibernate.

6. A terceira parte de demonstrao, exemplos e tutoriais esto vinculadas no website Hibernate.

7. A rea de Comunidade no website Hibernate um bom recurso para parceiros de design evrias solues integradas. ( Tomcat, JBoss AS, Struts, EJB, etc. )

There are a number of ways to become involved in the Hibernate community, including

Trying stuff out and reporting bugs. See http://hibernate.org/issuetracker.html details.

Trying your hand at fixing some bugs or implementing enhancements. Again, see http://hibernate.org/issuetracker.html details.

http://hibernate.org/community.html list a few ways to engage in the community.

There are forums for users to ask questions and receive help from the community.

There are also IRC [http://en.wikipedia.org/wiki/Internet_Relay_Chat] channels for both userand developer discussions.

Helping improve or translate this documentation. Contact us on the developer mailing list if youhave interest.

Evangelizing Hibernate within your organization.

1

TutorialIntencionado para novos usurios, este captulo fornece uma introduo detalhada do Hibernate,comeando com um aplicativo simples usando um banco de dados em memria. O tutorial baseado num tutorial anterior desenvolvido por Michael Gloegl. Todo o cdigo est contido nodiretrio tutorials/web da fonte do projeto.

Importante

Este tutorial espera que o usurio tenha conhecimento de ambos Java e SQL.Caso voc tenha um conhecimento limitado do JAVA ou SQL, recomendado quevoc inicie com uma boa introduo quela tecnologia, antes de tentar entendero Hibernate.

Nota

Esta distribuio contm outro aplicativo de amostra sob o diretrio de fonte doprojeto tutorial/eg.

1.1. Parte 1 A primeira aplicao HibernateVamos supor que precisemos de uma aplicao com um banco de dados pequeno que possaarmazenar e atender os eventos que queremos, alm das informaes sobre os hosts desteseventos.

Nota

Mesmo que usando qualquer banco de dados do qual voc se sinta confortvel,ns usaremos HSQLDB [http://hsqldb.org/] (o em memria, banco de dados Java)para evitar a descrio de instalao/configurao de quaisquer servidores dobanco de dados.

1.1.1. Configurao

O primeiro passo em que precisamos tomar configurar o ambiente de desenvolvimento.Ns usaremos o "layout padro" suportado por muitas ferramentas de construo, tais comoMaven [http://maven.org]. Maven, em particular, possui um excelente recurso de descriodisto layout [http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html]. Assim como este tutorial deve ser um aplicativo da web, ns criaremos e faremosuso dos diretrios src/main/java, src/main/resources e src/main/webapp.

Captulo 1. Tutorial

2

Ns usaremos Maven neste tutorial, tirando vantagem destas capacidades de dependnciatransitiva assim como a habilidade de muitos IDEs de configurar automaticamente um projetobaseado no descritor maven.

4.0.0

org.hibernate.tutorials hibernate-tutorial 1.0.0-SNAPSHOT First Hibernate Tutorial

${artifactId}

org.hibernate hibernate-core

javax.servlet servlet-api

org.slf4j slf4j-simple

javassist javassist

Dica

It is not a requirement to use Maven. If you wish to use something else to buildthis tutorial (such as Ant), the layout will remain the same. The only change isthat you will need to manually account for all the needed dependencies. If you

A primeira Classe

3

use something like Ivy [http://ant.apache.org/ivy/] providing transitive dependencymanagement you would still use the dependencies mentioned below. Otherwise,you'd need to grab all dependencies, both explicit and transitive, and add themto the project's classpath. If working from the Hibernate distribution bundle, thiswould mean hibernate3.jar, all artifacts in the lib/required directory and allfiles from either the lib/bytecode/cglib or lib/bytecode/javassist directory;additionally you will need both the servlet-api jar and one of the slf4j loggingbackends.

Salve este arquivo como pom.xml no diretrio raiz do projeto.

1.1.2. A primeira Classe

Agora, iremos criar uma classe que representa o evento que queremos armazenar na base dedados. Isto uma classe JavaBean simples com algumas propriedades:

package org.hibernate.tutorial.domain;

import java.util.Date;

public class Event { private Long id;

private String title; private Date date;

public Event() {}

public Long getId() { return id; }

private void setId(Long id) { this.id = id; }

public Date getDate() { return date; }

public void setDate(Date date) { this.date = date; }

public String getTitle() { return title; }

public void setTitle(String title) { this.title = title; }}

Captulo 1. Tutorial

4

Voc pode ver que esta classe usa o padro JavaBean para o nome convencional dos mtodosde propriedade getter e setter, como tambm a visibilidade privada dos campos. Este umpadro de projeto recomendado, mas no requerido. O Hibernate pode tambm acessar camposdiretamente, o benefcio para os mtodos de acesso a robustez para o refactoring.

A propriedade id mantm um nico valor de identificao para um evento particular. Todasas classes persistentes da entidade (bem como aquelas classes dependentes de menosimportncia) precisam de uma propriedade de identificao, caso ns queiramos usar o conjuntocompleto de caractersticas do Hibernate. De fato, a maioria das aplicaes, especialmente.aplicaes web, precisam distinguir os objetos pelo identificador. Portanto, voc deverconsiderar esta, uma caracterstica ao invs de uma limitao. Porm, ns normalmente nomanipulamos a identidade de um objeto, conseqentemente o mtodo setter dever ser privado.O Hibernate somente nomear os identificadores quando um objeto for salvo. O Hibernate podeacessar mtodos pblicos, privados, e protegidos, como tambm campos pblicos, privados,protegidos diretamente. A escolha sua e voc pode adaptar seu projeto de aplicao.

O construtor sem argumentos um requerimento para todas as classes persistentes; O Hibernateprecisa criar para voc os objetos usando Java Reflection. O construtor pode ser privado, porm,a visibilidade do pacote requerida para a procurao da gerao em tempo de execuo erecuperao eficiente dos dados sem a instrumentao de bytecode.

Salve este arquivo no diretrio src/main/java/org/hibernate/tutorial/domain.

1.1.3. O mapeamento do arquivo

O Hibernate precisa saber como carregar e armazenar objetos da classe de persistncia. aquique o mapeamento do arquivo do Hibernate entrar em jogo. O arquivo mapeado informa aoHibernate, qual tabela no banco de dados ele dever acessar, e quais as colunas na tabela eledever usar.

A estrutura bsica de um arquivo de mapeamento parecida com:

[...]

Note que o Hibernate DTD muito sofisticado. Voc pode usar isso para auto-concluso nomapeamento XML dos elementos e funes no seu editor ou IDE. Voc tambm pode abriro arquivo DTD no seu editor. Esta a maneira mais fcil de ter uma viso geral de todos oselementos e funes e dos padres, como tambm alguns comentrios. Note que o Hibernateno ir carregar o arquivo DTD da web, e sim da classpath da aplicao. O arquivo DTD est

O mapeamento do arquivo

5

includo no hibernate-core.jar (como tambm no hibernate3.jar, caso usando a vinculaode distribuio.

Importante

Ns omitiremos a declarao do DTD nos exemplos futuros para encurtar o cdigo.Isto, claro, no opcional.

Entre as duas tags hibernate-mapping, inclua um elemento class. Todas as classespersistentes da entidade (novamente, poder haver mais tarde, dependncias sobre as classesque no so classes-primrias de entidades) necessitam do tal mapeamento, para uma tabelana base de dados SQL:

At agora, informamos o Hibernate sobre como fazer para persistir e carregar objetos daclasse Event da tabela EVENTS, cada instncia representada por uma coluna na tabela. Agora,continuaremos com o mapeamento de uma nica propriedade identificadora para as chavesprimrias da tabela. Alm disso, como no precisamos nos preocupar em manipular esteidentificador, iremos configurar uma estratgia de gerao de ids do Hibernate para uma colunade chave primria substituta:

O elemento id a declarao de uma propriedade do identificador. O atributo do mapeamentoname="id" declara que o nome da propriedade JavaBeans e informa o Hibernate a utilizar osmtodos getId() and setId() para acessar a propriedade. A atributo da coluna informa oHibernate qual coluna da tabela EVENTS mantm o valor de chave primria.

O elemento generator aninhado especifica a estratgia da gerao do identificador (como osvalores do identificador so gerados?). Neste caso, ns escolhemos native, do qual oferece

Captulo 1. Tutorial

6

um nvel de portabilidade dependendo no dialeto do banco de dados configurado. O Hibernatesuporta o banco de dados gerado, globalmente nico, assim como a aplicao determinada,identificadores. A gerao do valor do identificador tambm um dos muitos pontos de extensodo Hibernate e voc pode realizar o plugin na sua prpria estratgia.

Dica

native is no longer consider the best strategy in terms of portability. for furtherdiscussion, see Seo 28.4, Gerao do identificador

Finalmente, incluiremos as declaraes para as propriedades persistentes da classe no arquivomapeado. Por padro, nenhuma das propriedades da classe considerada persistente:

Assim como com o elemento id, a funo name do elemento property informa ao Hibernate qualmtodo getter e setter dever usar. Assim, neste caso, o Hibernate ir procurar pelos mtodosgetDate(), setDate(), getTitle() e setTitle().

Nota

Porque fazer o mapeamento da propriedade date includo na funo column, e notitle no fazer? Sem a funo column o Hibernate, por padro, utiliza o nome dapropriedade como o nome da coluna. Isto funciona bem para o title. Entretanto,o date uma palavra-chave reservada na maioria dos bancos de dados, por issoseria melhor mape-lo com um nome diferente.

O mapeamento do title tambm no possui a funo type. O tipo que declaramos e utilizamosnos arquivos mapeados, no so como voc esperava, ou seja, funes de dados Java. Elestambm no so como os tipos de base de dados SQL. Esses tipos podem ser chamados deTipos de mapeamento Hibernate, que so conversores que podem traduzir tipos de dados doJava para os tipos de dados SQL e vice-versa. Novamente, o Hibernate ir tentar determinara converso correta e mapear o type prprio, caso o tipo da funo no estiver presente nomapeamento. Em alguns casos, esta deteco automtica (que usa Reflection sobre as classes

Configurao do Hibernate

7

Java) poder no ter o padro que voc espera ou necessita. Este o caso com a propriedadedate. O Hibernate no sabe se a propriedade, que do java.util.Date, pode mapear parauma coluna do tipo date do SQL, timestamp ou time. Ns preservamos as informaes sobredatas e horas pelo mapeamento da propriedade com um conversor timestamp.

Dica

O Hibernate realiza esta determinao de tipo de mapeamento usando a reflexoquando os arquivos de mapeamentos so processados. Isto pode levar tempo erecursos, portanto se voc inicializar o desempenho, ser importante que vocconsidere claramente a definio do tipo para uso.

Salve este arquivo de mapeamento como src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml.

1.1.4. Configurao do Hibernate

Nestas alturas, voc deve possuir a classe persistente e seu arquivo de mapeamento prontos. o momento de configurar o Hibernate. Primeiro, vamos configurar o HSQLDB para rodar no"modo do servidor".

Nota

Ns realizamos isto para que aqueles dados permaneam entre as execues.

Ns utilizaremos o Maven exec plugin para lanar o servidor HSQLDB pela execuo:mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0file:target/data/tutorial". Voc pode ver ele iniciando e vinculando ao soquete TCP/IP,aqui ser onde nossa aplicao ir se conectar depois. Se voc deseja iniciar uma nova basede dados durante este tutorial, finalize o HSQLDB, delete todos os arquivos no diretrio target/data, e inicie o HSQLBD novamente.

O Hibernate conectar ao banco de dados no lugar de sua aplicao, portanto ele precisar sabercomo obter as conexes. Para este tutorial ns usaremos um pool de conexo autnomo (aoinvs de javax.sql.DataSource). O Hibernate vem com o suporte para dois teros dos poolsde conexo JDBC de cdigo aberto: c3p0 [https://sourceforge.net/projects/c3p0] e proxool [http://proxool.sourceforge.net/]. No entanto, ns usaremos o pool de conexo interna do Hibernate paraeste tutorial.

Captulo 1. Tutorial

8

Cuidado

O pool de conexo interna do Hibernate no recomendado para uso deproduo. Ele possui deficincia em diversos recursos encontrados em qualquerpool de conexo apropriado.

Para as configuraes do Hibernate, ns podemos usar um arquivo simpleshibernate.properties, um arquivo mais sofisticado hibernate.cfg.xml ou at mesmouma instalao programtica completa. A maioria dos usurios prefere utilizar o arquivo deconfigurao XML:

org.hsqldb.jdbcDriver jdbc:hsqldb:hsql://localhost sa

1

org.hibernate.dialect.HSQLDialect

thread

org.hibernate.cache.NoCacheProvider

true

update

Construindo com o Maven

9

Nota

Perceba que este arquivo de configurao especifica um DTD diferente

Configure a SessionFactory do Hibernate. A SessionFactory uma fbrica global responsvelpor uma base de dados particular. Se voc tiver diversas bases de dados, use diversasconfiguraes , geralmente em diversos arquivos de configurao, para umainicializao mais fcil.

Os primeiros quatro elementos property contm a configurao necessria para a conexoJBDC. O elemento property do dialeto especifica a variante do SQL particular que o Hibernategera.

Dica

In most cases, Hibernate is able to properly determine which dialect to use. SeeSeo 28.3, Resoluo do Dialeto for more information.

O gerenciamento automtico de sesso do Hibernate para contextos de persistncia bastantetil neste contexto. A opo hbm2ddl.auto habilita a gerao automtica de esquemas dabase de dados, diretamente na base de dados. Isto tambm pode ser naturalmente desligadoapenas removendo a opo de configurao ou redirecionado para um arquivo com ajudado SchemaExport na tarefa do Ant. Finalmente, iremos adicionar os arquivos das classes depersistncia mapeadas na configurao.

Salve este arquivo como hibernate.cfg.xml no diretrio src/main/resources.

1.1.5. Construindo com o MavenNs iremos construir agora o tutorial com Maven. Voc necessitar que o Maven estejainstalado; ele est disponvel a partir do Maven download page [http://maven.apache.org/download.html]. O Maven gravar o arquivo /pom.xml que criamos anteriormente, alm de sabercomo executar algumas tarefas do projeto bsico. Primeiro, vamos rodar o objetivo compile paranos certificarmos de que tudo foi compilado at agora:

[hibernateTutorial]$ mvn compile[INFO] Scanning for projects...

Captulo 1. Tutorial

10

[INFO] ------------------------------------------------------------------------[INFO] Building First Hibernate Tutorial[INFO] task-segment: [compile][INFO] ------------------------------------------------------------------------[INFO] [resources:resources][INFO] Using default encoding to copy filtered resources.[INFO] [compiler:compile][INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes[INFO] ------------------------------------------------------------------------[INFO] BUILD SUCCESSFUL[INFO] ------------------------------------------------------------------------[INFO] Total time: 2 seconds[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009[INFO] Final Memory: 5M/547M[INFO] ------------------------------------------------------------------------

1.1.6. Inicializao e Auxiliares hora de carregar e armazenar alguns objetos Event, mas primeiro ns temos de completara instalao com algum cdigo de infraestrutura. Voc precisa inicializar o Hibernate pelaconstruo de um objeto org.hibernate.SessionFactory global e o armazenamento dele emalgum lugar de fcil acesso para o cdigo da aplicao. O org.hibernate.SessionFactory usado para obter instncias org.hibernate.Session. O org.hibernate.Session representauma unidade de single-threaded de trabalho. O org.hibernate.SessionFactory um objetoglobal thread-safe, instanciado uma vez.

Criaremos uma classe de ajuda HibernateUtil, que cuida da inicializao e faz acesso a umaorg.hibernate.SessionFactory mais conveniente.

package org.hibernate.tutorial.util;

import org.hibernate.SessionFactory;import org.hibernate.cfg.Configuration;

public class HibernateUtil {

private static final SessionFactory sessionFactory = buildSessionFactory();

private static SessionFactory buildSessionFactory() { try { // Create the SessionFactory from hibernate.cfg.xml return new Configuration().configure().buildSessionFactory(); } catch (Throwable ex) { // Make sure you log the exception, as it might be swallowed System.err.println("Initial SessionFactory creation failed." + ex); throw new ExceptionInInitializerError(ex); } }

public static SessionFactory getSessionFactory() { return sessionFactory; }

Carregando e salvando objetos

11

}

Salve este cdigo como src/main/java/org/hibernate/tutorial/util/HibernateUtil.java

Esta classe no s produz uma referncia org.hibernate.SessionFactory global em seuinicializador esttico, mas tambm esconde o fato de que utiliza um autnomo esttico. Nspoderemos buscar pela referncia org.hibernate.SessionFactory a partir do JNDI no servidorda aplicao ou qualquer outra localizao para este assunto.

Se voc der um nome SessionFactory em seu arquivo de configurao, o Hibernate ir, defato, tentar vincul-lo ao JNDI sob aquele nome, depois que estiver construdo. Outra opomelhor seria usar a implementao JMX e deixar o recipiente JMX capaz, instanciar e vincularum HibernateService ao JNDI. Essas opes avanadas so discutidas no documento dereferncia do Hibernate. Tais opes avanadas sero discutidas mais tarde.

Voc precisar agora configurar um sistema de logging. O Hibernate usa logging comuns e lheoferece a escolha entre o Log4j e o logging do JDK 1.4 . A maioria dos desenvolvedores prefere oLog4j: copie log4j.properties da distribuio do Hibernate no diretrio etc/, para seu diretriosrc, depois v em hibernate.cfg.xml. D uma olhada no exemplo de configurao e mude asconfiguraes se voc quiser ter uma sada mais detalhada. Por padro, apenas as mensagensde inicializao do Hibernate so mostradas no stdout.

O tutorial de infra-estrutura est completo e ns j estamos preparados para algum trabalho deverdade com o Hibernate.

1.1.7. Carregando e salvando objetosWe are now ready to start doing some real work with Hibernate. Let's start by writing anEventManager class with a main() method:

package org.hibernate.tutorial;

import org.hibernate.Session;

import java.util.*;

import org.hibernate.tutorial.domain.Event;import org.hibernate.tutorial.util.HibernateUtil;

public class EventManager {

public static void main(String[] args) { EventManager mgr = new EventManager();

if (args[0].equals("store")) { mgr.createAndStoreEvent("My Event", new Date()); }

HibernateUtil.getSessionFactory().close();

Captulo 1. Tutorial

12

}

private void createAndStoreEvent(String title, Date theDate) { Session session = HibernateUtil.getSessionFactory().getCurrentSession(); session.beginTransaction();

Event theEvent = new Event(); theEvent.setTitle(title); theEvent.setDate(theDate); session.save(theEvent);

session.getTransaction().commit(); }

}

Em createAndStoreEvent(), criamos um novo objeto de Event, e passamos para o Hibernate.O Hibernate sabe como tomar conta do SQL e executa INSERTs no banco de dados.

A org.hibernate.Session is designed to represent a single unit of work (a single atomic piece ofwork to be performed). For now we will keep things simple and assume a one-to-one granularitybetween a Hibernate org.hibernate.Session and a database transaction. To shield our code fromthe actual underlying transaction system we use the Hibernate org.hibernate.TransactionAPI. In this particular case we are using JDBC-based transactional semantics, but it could alsorun with JTA.

O que a sessionFactory.getCurrentSession() faz? Primeiro, voc pode chamar quantasvezes e de onde quiser, assim que voc receber sua org.hibernate.SessionFactory. Omtodo getCurrentSession() sempre retorna unidade de trabalho "atual". Voc se lembraque ns mudamos a opo de configurao desse mecanismo para "thread" em nosso src/main/resources/hibernate.cfg.xml? Devido a esta configurao, o contexto de uma unidadede trabalho atual estar vinculada thread Java atual que executa nossa aplicao.

Importante

O Hibernate oferece trs mtodos da sesso atual. O mtodo "thread" baseadono possui por interesse o uso de produo; ele basicamente til paraprototyping e tutoriais tais como este. A sesso atual ser discutida em maisdetalhes mais tarde.

Um org.hibernate.Session comea quando for necessria, quando feita a primeira chamada getCurrentSession(). ento limitada pelo Hibernate para a thread atual. Quando a transaotermina, tanto com commit quanto rollback, o Hibernate tambm desvincula a Session da threade fecha isso pra voc. Se voc chamar getCurrentSession() novamente, voc receber umanova Session e poder comear uma nova unidade de trabalho.

Em relao ao escopo da unidade de trabalho, o Hibernate org.hibernate.Session deve serutilizado para executar uma ou mais operaes do banco de dados? O exemplo acima utiliza

Carregando e salvando objetos

13

uma Session para cada operao. Isto pura coincidncia, o exemplo simplesmente no complexo o bastante para mostrar qualquer outra abordagem. O escopo de um Hibernateorg.hibernate.Session flexvel, mas voc nunca deve configurar seu aplicativo para utilizarum novo Hibernate org.hibernate.Session para aoperao de banco de dados every. Portanto,mesmo que voc o veja algumas vezes mais nos seguintes exemplos, considere session-per-operation como um anti-modelo. Um aplicativo da web real ser demonstrado mais adiante nestetutorial.

See Captulo 13, Transaes e Concorrncia for more information about transaction handlingand demarcation. The previous example also skipped any error handling and rollback.

Para rodar isto, ns faremos uso do Maven exec plugin para chamarnossa classe com a instalao do classpath necessria: mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"

Nota

Voc precisa executar o mvn compile primeiramente.

Voc dever ver, aps a compilao, a inicializao do Hibernate e, dependendo da suaconfigurao, muito log de sada. No final, voc ver a seguinte linha:

[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)

Este o INSERT executado pelo Hibernate.

Adicionamos uma opo para o mtodo principal com o objetivo de listar os eventos arquivados:

if (args[0].equals("store")) { mgr.createAndStoreEvent("My Event", new Date()); } else if (args[0].equals("list")) { List events = mgr.listEvents(); for (int i = 0; i < events.size(); i++) { Event theEvent = (Event) events.get(i); System.out.println( "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate() ); } }

Nos tambm adicionamos um novo listEvents() method is also added:

private List listEvents() { Session session = HibernateUtil.getSessionFactory().getCurrentSession();

Captulo 1. Tutorial

14

session.beginTransaction(); List result = session.createQuery("from Event").list(); session.getTransaction().commit(); return result; }

Here, we are using a Hibernate Query Language (HQL) query to load all existing Event objectsfrom the database. Hibernate will generate the appropriate SQL, send it to the database andpopulate Event objects with the data. You can create more complex queries with HQL. SeeCaptulo 16, HQL: A Linguagem de Consultas do Hibernate for more information.

Agora podemos chamar nossa nova funcionalidade usando, novamente, o Maven execplugin: mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"

1.2. Parte 2 - Mapeando associaesNs mapeamos uma classe de entidade de persistncia para uma tabela. Agora vamos continuare adicionar algumas associaes de classe. Primeiro iremos adicionar pessoas nossa aplicaoe armazenar os eventos em que elas participam.

1.2.1. Mapeando a classe Person

O primeira parte da classe Person parece-se com isto:

package org.hibernate.tutorial.domain;

public class Person {

private Long id; private int age; private String firstname; private String lastname;

public Person() {}

// Accessor methods for all properties, private setter for 'id'

}

Salve isto ao arquivo nomeado src/main/java/org/hibernate/tutorial/domain/Person.java

Aps isto, crie um novo arquivo de mapeamento como src/main/resources/org/hibernate/tutorial/domain/Person.hbm.xml

Uma associao unidirecional baseada em Configurao

15

Finalmente, adicione o novo mapeamento configurao do Hibernate:

Crie agora uma associao entre estas duas entidades. As pessoas (Person) podem participarde eventos, e eventos possuem participantes. As questes de design com que teremos de lidarso: direcionalidade, multiplicidade e comportamento de coleo.

1.2.2. Uma associao unidirecional baseada em ConfiguraoIremos adicionar uma coleo de eventos na classe Person. Dessa forma, poderemos navegarpelos eventos de uma pessoa em particular, sem executar uma consulta explicitamente, apenaschamando Person#getEvents. As associaes de valores mltiplos so representadas noHibernate por um dos contratos do Java Collection Framework; aqui ns escolhemos umjava.util.Set, uma vez que a coleo no conter elementos duplicados e a ordem no relevante em nossos exemplos:

public class Person {

private Set events = new HashSet();

public Set getEvents() { return events;

}

public void setEvents(Set events) { this.events = events; }}

Antes de mapearmos esta associao, pense no outro lado. Claramente, poderamos apenasfazer isto de forma unidirecional. Ou poderamos criar outra coleo no Event, se quisermosnavegar de ambas direes. Isto no necessrio, de uma perspectiva funcional. Voc podersempre executar uma consulta explcita para recuperar os participantes de um evento emparticular. Esta uma escolha de design que cabe a voc, mas o que claro nessa discusso a multiplicidade da associao: "muitos" vlidos em ambos os lados, ns chamamos isto de uma

Captulo 1. Tutorial

16

associao muitos-para-muitos. Daqui pra frente, usaremos o mapeamento muitos-para-muitosdo Hibernate:

O Hibernate suporta todo tipo de mapeamento de coleo, sendo um set mais comum. Para umaassociao muitos-para-muitos ou relacionamento de entidade n:m, necessria uma tabela deassociao. Cada linha nessa tabela representa um link entre uma pessoa e um evento. O nomeda tabela configurado com a funo table do elemento set. O nome da coluna identificadorana associao, pelo lado da pessoa, definido com o elemento key, o nome da coluna pelolado dos eventos, definido com a funo column do many-to-many. Voc tambm precisa dizerpara o Hibernate a classe dos objetos na sua coleo (a classe do outro lado das colees dereferncia).

O esquema de mapeamento para o banco de dados est a seguir:

_____________ __________________

| | | | _____________ | EVENTS | | PERSON_EVENT | | | |_____________| |__________________| | PERSON | | | | | |_____________| | *EVENT_ID | | *EVENT_ID | | | | EVENT_DATE | | *PERSON_ID | | *PERSON_ID | | TITLE | |__________________| | AGE | |_____________| | FIRSTNAME | | LASTNAME | |_____________|

1.2.3. Trabalhando a associao

Vamos reunir algumas pessoas e eventos em um novo mtodo na classe EventManager:

private void addPersonToEvent(Long personId, Long eventId) { Session session = HibernateUtil.getSessionFactory().getCurrentSession();

Trabalhando a associao

17

session.beginTransaction();

Person aPerson = (Person) session.load(Person.class, personId); Event anEvent = (Event) session.load(Event.class, eventId); aPerson.getEvents().add(anEvent);


Aps carregar um Person e um Event, simplesmente modifique a coleo usando os mtodosnormais de uma coleo. Como voc pode ver, no h chamada explcita para update() ousave(); o Hibernate detecta automaticamente que a coleo foi modificada e que necessitaser atualizada. Isso chamado de checagem suja automtica, e voc tambm pode us-lamodificando o nome ou a data de qualquer um dos seus objetos. Desde que eles estejam noestado persistent, ou seja, limitado por uma Session do Hibernate em particular, o Hibernatemonitora qualquer alterao e executa o SQL em modo de gravao temporria. O processode sincronizao do estado da memria com o banco de dados, geralmente apenas no final deuma unidade de trabalho, normalmente apenas no final da unidade de trabalho, chamado deflushing. No nosso cdigo, a unidade de trabalho termina com o commit , ou rollback, da transaodo banco de dados.

Voc pode tambm querer carregar pessoas e eventos em diferentes unidades de trabalho. Ouvoc modifica um objeto fora de um org.hibernate.Session, quando no se encontra no estadopersistente (se j esteve neste estado anteriormente, chamamos esse estado de detached). Vocpode at mesmo modificar uma coleo quando esta se encontrar no estado detached:

private void addPersonToEvent(Long personId, Long eventId) { Session session = HibernateUtil.getSessionFactory().getCurrentSession(); session.beginTransaction();

Person aPerson = (Person) session .createQuery("select p from Person p left join fetch p.events where p.id = :pid") .setParameter("pid", personId) .uniqueResult(); // Eager fetch the collection so we can use it detached Event anEvent = (Event) session.load(Event.class, eventId);

session.getTransaction().commit();

// End of first unit of work

aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached

// Begin second unit of work

Session session2 = HibernateUtil.getSessionFactory().getCurrentSession(); session2.beginTransaction(); session2.update(aPerson); // Reattachment of aPerson

session2.getTransaction().commit(); }

Captulo 1. Tutorial

18

A chamada update cria um objeto persistente novamente, pode-se dizer que ele liga o objeto auma nova unidade de trabalho, assim qualquer modificao que voc faa neste objeto enquantoestiver no estado desanexado pode ser salvo no banco de dados. Isso inclui qualquer modificao(adio/excluso) que voc faa em uma coleo da entidade deste objeto.

Bem, isso no de grande utilidade na nossa situao atual, porm, um importante conceitoque voc pode criar em seu prprio aplicativo. No momento, complete este exerccio adicionandouma ao ao mtodo principal da classe EventManager e chame-o pela linha de comando.Se voc precisar dos identificadores de uma pessoa ou evento - o mtodo save() retornarestes identificadores (voc poder modificar alguns dos mtodos anteriores para retornar aqueleidentificador):

else if (args[0].equals("addpersontoevent")) { Long eventId = mgr.createAndStoreEvent("My Event", new Date()); Long personId = mgr.createAndStorePerson("Foo", "Bar"); mgr.addPersonToEvent(personId, eventId); System.out.println("Added person " + personId + " to event " + eventId); }

Este foi um exemplo de uma associao entre duas classes igualmente importantes: duasentidades. Como mencionado anteriormente, h outras classes e tipos dentro de um modelotpico, geralmente "menos importante". Alguns voc j viu, como um int ou uma String.Ns chamamos essas classes de tipos de valores, e suas instncias dependem de umaentidade particular. As instncias desses tipos no possuem sua prpria identidade, nem socompartilhados entre entidades. Duas pessoas no referenciam o mesmo objeto firstnamemesmo se elas tiverem o mesmo objeto firstname. Naturalmente, os tipos de valores no soapenas encontrados dentro da JDK, mas voc pode tambm criar suas classes como, porexemplo, Address ou MonetaryAmount. De fato, no aplicativo Hibernate todas as classes JDKso consideradas tipos de valores.

Voc tambm pode criar uma coleo de tipo de valores. Isso conceitualmente muito diferentede uma coleo de referncias para outras entidades, mas em Java parece ser quase a mesmacoisa.

1.2.4. Coleo de valores

Vamos adicionar uma coleo de endereos de e-mail entidade Person. Isto ser representadocomo um java.util.Set das instncias java.lang.String:

private Set emailAddresses = new HashSet();

public Set getEmailAddresses() { return emailAddresses; }

public void setEmailAddresses(Set emailAddresses) { this.emailAddresses = emailAddresses;

Coleo de valores

19

}

Segue abaixo o mapeamento deste Set:

A diferena comparada com o mapeamento anterior se encontra na parte element, que informaao Hibernate que a coleo no contm referncias outra entidade, mas uma coleo deelementos do tipo String. O nome da tag em minsculo indica que se trata de um tipo/conversorde mapeamento do Hibernate. Mais uma vez, a funo table do elemento set determina o nomeda tabela para a coleo. O elemento key define o nome da coluna de chave estrangeira natabela de coleo. A funo column dentro do elemento element define o nome da coluna ondeos valores da String sero armazenados.

Segue abaixo o esquema atualizado:

_____________ __________________

| | | | _____________ | EVENTS | | PERSON_EVENT | | | ___________________ |_____________| |__________________| | PERSON | | | | | | | |_____________| | PERSON_EMAIL_ADDR | | *EVENT_ID | | *EVENT_ID | | | |___________________| | EVENT_DATE | | *PERSON_ID | | *PERSON_ID | | *PERSON_ID | | TITLE | |__________________| | AGE | | *EMAIL_ADDR | |_____________| | FIRSTNAME | |___________________| | LASTNAME | |_____________|

Voc pode observar que a chave primria da tabela da coleo na verdade uma chavecomposta, usando as duas colunas. Isso tambm implica que cada pessoa no pode terendereos de e-mail duplicados, o que exatamente a semntica que precisamos para um setem Java.

Voc pode agora tentar adicionar elementos essa coleo, do mesmo modo que fizemosanteriormente ligando pessoas e eventos. o mesmo cdigo em Java:

private void addEmailToPerson(Long personId, String emailAddress) { Session session = HibernateUtil.getSessionFactory().getCurrentSession(); session.beginTransaction();

Person aPerson = (Person) session.load(Person.class, personId); // adding to the emailAddress collection might trigger a lazy load of the collection aPerson.getEmailAddresses().add(emailAddress);

Captulo 1. Tutorial

20


Desta vez no utilizamos uma consulta fetch (busca) para inicializar a coleo. Monitore o logSQL e tente otimiz-lo com rdua busca.

1.2.5. Associaes bidirecionais

Agora iremos mapear uma associao bidirecional. Voc far uma associao entre o trabalhoperson e event de ambos os lados em Java. O esquema do banco de dados acima no muda,de forma que voc continua possuir a multiplicidade muitos-para-muitos.

Nota

Um banco de dados relacional mais flexvel que um linguagem de programaoda rede, de maneira que ele no precisa de uma direo de navegao; os dadospodem ser visualizados e restaurados de qualquer maneira.

Primeiramente, adicione uma coleo de participantes classe Event:

private Set participants = new HashSet();

public Set getParticipants() { return participants; }

public void setParticipants(Set participants) { this.participants = participants; }

Agora mapeie este lado da associao em Event.hbm.xml.

Como voc pode ver, esses so mapeamentos set normais em ambos documentos demapeamento. Observe que os nomes das colunas em key e many-to-many esto trocadosem ambos os documentos de mapeamento. A adio mais importante feita est na funoinverse="true" no elemento set da coleo da classe Event.

Trabalhando com links bidirecionais

21

Isso significa que o Hibernate deve pegar o outro lado, a classe Person, quando precisarencontrar informao sobre a relao entre as duas entidades. Isso ser muito mais fcil deentender quando voc analisar como a relao bidirecional entre as entidades criada.

1.2.6. Trabalhando com links bidirecionais

Primeiro, tenha em mente que o Hibernate no afeta a semntica normal do Java. Como foique criamos um link entre uma Person e um Event no exemplo unidirecional? Adicionamosuma instncia de Event, da coleo de referncias de eventos, uma instncia de Person.Ento, obviamente, se quisermos que este link funcione bidirecionalmente, devemos fazer amesma coisa para o outro lado, adicionando uma referncia de Person na coleo de um Event.Essa "configurao de link de ambos os lados" absolutamente necessria e voc nunca deveesquecer de faz-la.

Muitos desenvolvedores programam de maneira defensiva e criam mtodos de gerenciamentode um link que ajustam-se corretamente em ambos os lados (como por exemplo, em Person):

protected Set getEvents() { return events;

}

protected void setEvents(Set events) { this.events = events; }

public void addToEvent(Event event) { this.getEvents().add(event); event.getParticipants().add(this); }

public void removeFromEvent(Event event) { this.getEvents().remove(event); event.getParticipants().remove(this); }

Observe que os mtodos set e get da coleo esto protegidos. Isso permite que classes esubclasses do mesmo pacote continuem acessando os mtodos, mas evita que qualquer outraclasse, que no esteja no mesmo pacote, acesse a coleo diretamente. Repita os passos paraa coleo do outro lado.

E sobre o mapeamento da funo inverse? Para voc, e para o Java, um link bidirecional simplesmente uma questo de configurar corretamente as referncias de ambos os lados. OHibernate, entretanto, no possui informao necessria para ajustar corretamente as instruesINSERT e UPDATE do SQL (para evitar violaes de restrio) e precisa de ajuda para manipularas associaes bidirecionais de forma apropriada. Ao fazer um lado da associao com a funoinverse, voc instrui o Hibernate para basicamente ignor-lo, considerando-o uma cpia dooutro lado. Isso o necessrio para o Hibernate compreender todas as possibilidades quandotransformar um modelo de navegao bidirecional em esquema de banco de dados do SQL. Asregras que voc precisa lembrar so diretas: todas as associaes bidirecionais necessitam que

Captulo 1. Tutorial

22

um lado possua a funo inverse. Em uma associao de um-para-muitos, precisar ser o ladode "muitos", j em uma associao de muitos-para-muitos voc poder selecionar qualquer lado.

1.3. EventManager um aplicativo da webUm aplicativo de web do Hibernate utiliza uma Session e uma Transaction quase do mesmomodo que um aplicativo autnomo. Entretanto, alguns modelos comuns so teis. Ns agoracriaremos um EventManagerServlet. Esse servlet lista todos os eventos salvos no banco dedados, e cria um formulrio HTML para entrada de novos eventos.

1.3.1. Criando um servlet bsico

Ns deveremos criar o nosso servket de processamento bsico primeiramente. Uma vez queo servlet manuseia somente requisies GET do HTTP, o mtodo que iremos implementar doGet():

package org.hibernate.tutorial.web;

// Imports

public class EventManagerServlet extends HttpServlet {

protected void doGet( HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" );

try { // Begin unit of work HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction();

// Process request and render page...

// End unit of work HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit(); } catch (Exception ex) { HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback(); if ( ServletException.class.isInstance( ex ) ) { throw ( ServletException ) ex; } else { throw new ServletException( ex ); } } }

}

Salve esse servlet como src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java

Processando e renderizando

23

O modelo que estamos aplicando neste cdigo chamado session-per-request. Quando umasolicitao chega ao servlet, uma nova Session do Hibernate aberta atravs da primeirachamada para getCurrentSession() em SessionFactory. Ento uma transao do banco dedados inicializada e todo acesso a dados deve ocorrer dentro de uma transao, no importandose o dado de leitura ou escrita. No se deve utilizar o modo auto-commit em aplicaes.

Nunca utilize uma nova Session do Hibernate para todas as operaes de banco de dados.Utilize uma Session do Hibernate que seja de interesse todas as solicitaes. UtilizegetCurrentSession(), para que seja vinculado automaticamente thread atual de Java.

Agora, as possveis aes de uma solicitao sero processadas e uma resposta HTML serrenderizada. J chegaremos nesta parte.

Finalmente, a unidade de trabalho termina quando o processamento e a renderizao socompletados. Se ocorrer algum erro durante o processamento ou a renderizao, uma exceoser lanada e a transao do banco de dados revertida. Isso completa o modelo session-per-request. Em vez de usar cdigo de demarcao de transao em todo servlet voc pode tambmcriar um filtro servlet. D uma olhada no website do Hibernate e do Wiki para maiores informaessobre esse modelo, chamado Sesso Aberta na Visualizao. Voc precisar disto assim quevoc considerar renderizar sua visualizao no JSP, no apenas num servlet.

1.3.2. Processando e renderizando

Vamos implementar o processamento da solicitao e renderizao da pgina.

// Write HTML header PrintWriter out = response.getWriter(); out.println("Event Manager");

// Handle actions if ( "store".equals(request.getParameter("action")) ) {

String eventTitle = request.getParameter("eventTitle"); String eventDate = request.getParameter("eventDate");

if ( "".equals(eventTitle) || "".equals(eventDate) ) { out.println("Please enter event title and date."); } else { createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate)); out.println("Added event."); } }

// Print page printEventForm(out); listEvents(out, dateFormatter);

// Write HTML footer out.println(""); out.flush();

Captulo 1. Tutorial

24

out.close();

O estilo deste cdigo misturado com o Java e HTML, no escalariam em um aplicativo maiscomplexo, tenha em mente que estamos somente ilustrando os conceitos bsicos do Hibernateneste tutorial. O cdigo imprime um cabealho e nota de rodap em HTML. Dentro desta pgina,so impressos um formulrio para entrada de evento em HTML e uma lista de todos os eventono banco de dados. O primeiro mtodo trivial e somente produz um HTML:

private void printEventForm(PrintWriter out) { out.println("Add new event:"); out.println(""); out.println("Title: "); out.println("Date (e.g. 24.12.2009): "); out.println(""); out.println(""); }

O mtodo listEvents() utiliza a Session do Hibernate, limitado ao thread atual para executaruma consulta:

private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {

List result = HibernateUtil.getSessionFactory() .getCurrentSession().createCriteria(Event.class).list(); if (result.size() > 0) { out.println("Events in database:"); out.println(""); out.println(""); out.println("Event title"); out.println("Event date"); out.println(""); Iterator it = result.iterator(); while (it.hasNext()) { Event event = (Event) it.next(); out.println(""); out.println("" + event.getTitle() + ""); out.println("" + dateFormatter.format(event.getDate()) + ""); out.println(""); } out.println(""); } }

Finalmente, a ao store, despachada ao mtodo createAndStoreEvent(), que tambmutiliza a Session da thread atual:

protected void createAndStoreEvent(String title, Date theDate) { Event theEvent = new Event(); theEvent.setTitle(title);

Implementando e testando

25

theEvent.setDate(theDate);

HibernateUtil.getSessionFactory() .getCurrentSession().save(theEvent); }

O servlet est completo agora. Uma solicitao ao servlet ser processada com uma nicaSession e Transaction. Quanto antes estiver no aplicativo autnomo, maior a chance doHibernate vincular automaticamente estes objetos thread atual de execuo. Isto lhe d aliberdade para inserir seu cdigo e acessar a SessionFactory como desejar. Geralmente,usaramos um diagrama mais sofisticado e moveramos o cdigo de acesso de dados para osobjetos de acesso dos dados (o modelo DAO). Veja o Hibernate Wiki para mais exemplos.

1.3.3. Implementando e testandoPara implementar este aplicativo em testes, ns devemos criar um Arquivo da Web (WAR).Primeiro, ns devemos definir o descritor WAR como src/main/webapp/WEB-INF/web.xml

Event Manager org.hibernate.tutorial.web.EventManagerServlet

Event Manager /eventmanager

Para construir e implementar, chame seu diretrio de projeto ant war e copie o arquivohibernate-tutorial.war para seu diretrio Tomcat webapp.

Nota

If you do not have Tomcat installed, download it from http://tomcat.apache.org/and follow the installation instructions. Our application requires no changes to thestandard Tomcat configuration.

Uma vez implementado e com o Tomcat rodando, acesse o aplicativo em http://localhost:8080/hibernate-tutorial/eventmanager. Tenha a certeza de observar o log doTomcat para ver o Hibernate inicializar quando a primeira solicitao chegar em seu servlet (o

Captulo 1. Tutorial

26

inicializador esttico no HibernateUtil chamado) e para obter o resultado detalhado casoexcees aconteam.

1.4. SumrioEste tutorial cobriu itens bsicos de como escrever um aplicativo

hibernate reference

Documents