Tutorial sobre Hibernate

Introduo, configurao e utilizao Utilizando XML ou Anotaes

Prof. Edmilson Prata da Silva Verso 2.0 Abril de 2010

TPICOS

PG

O que o Hibernate? O que preciso fazer para se trabalhar com o Hibernate? Como configurar o CLASSPH do projeto? Exemplo de organizao do projeto Exemplo de configurao do arquivo hibernate.cfg.xml Exemplo de mapeamento objeto relacional com arquivo XML Exemplo de mapeamento objeto relacional com anotaes Alguns recursos avanados de mapeamento com anotaes (falta) Erros comuns na configurao e uso do Hibernate

2 2 5 6 7 8 9 10

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 1

O que o Hibernate?
O Hibernate um toolkit1 de persistncia2 open source3 cujo propsito prover um mecanismo para persistncia de objetos Java ou .Net em um banco de dados relacional. O site do projeto http://www.hibernate.org/, onde pode ser feito o download de qualquer verso do framework. As principais vantagens de se utilizar o Hibernate so: 1. Ele oferece vrios recursos que facilitam o mapeamento do modelo orientado a objetos para o relacional e vice-versa. Este processo conhecido como MOR ou mapeamento objeto relacional; 2. Estes recursos simplificam o trabalho de persistir e recuperar os objetos no modelo relacional, que bastante diferente do orientado a objetos no qual ns desenvolvemos a aplicao; 3. O Hibernate nos d a impresso de que estamos trabalhando com um SGBDOO durante o desenvolvimento da aplicao. Apesar de estarmos trabalhando, na verdade, com um SGBD relacional.

O que preciso fazer para se trabalhar com o Hibernate?

So necessrias apenas quatro aes para se configurar e utilizar o Hibernate. So elas: 1. Download dos recursos necessrios: Voc precisa baixar trs recursos para o funcionamento do Hibernate: Hibernate Core: Arquivo compactado que contm a implementao do Hibernate, documentao, fontes, exemplos, etc. Disponvel em http://www.hibernate.org/ ou http://sourceforge.net/projects/hibernate/files/; Hibernate Annotetions: Contm as anotaes utilizadas pelo Hibernate. Disponvel em http://www.hibernate.org/ ou http://sourceforge.net/projects/hibernate/files/; Diver JDBC: a implementao do JDBC para o SGBD que voc utilizar. Disponvel no site de cada fabricante de SGBD.

1: Toolkit pode ser entendido como um conjunto de ferramentas, como o prprio nome indica, voltadas soluo ou suporte de um tipo de problema/necessidade genrico; 2: O termo persistncia refere-se ao registro e manuteno dos dados em algum tipo de memria permanente, ou seja, os dados continuaro a existir depois que o programa encerrar a execuo, podero ser recuperados e modificados. 3: O termo open source refere-se a uma filosofia de construo de software cujo cdigo fonte aberto. Isto significa que o cdigo fonte est disponvel para que qualquer pessoa o possa ler e entender;

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 2

DICAS: Depois de baixar tudo o que voc precisa, crie um diretrio no seu disco para servir de referencia aos projetos Java (por exemplo d:\java-frameworks). Em seguida descompacte os recursos baixados dentro dele; sempre recomendada a utilizao da ltima verso dos frameworks. Porm, se voc precisar de alguma verso anterior, elas sempre esto disponveis.

2. Configurao do CLASSPATH: De posse dos recursos adquiridos no site oficial do Hibernate, voc agora precisa acrescent-los ao seu projeto no Eclipse. Isto feito por meio da configurao do CLASSPATH4 do seu projeto Java. Veja em detalhes como fazer isso no tpico Como configurar o CLASSPATH do projeto? mais adiante. Por ora, vamos conhecer os pacotes (arquivos .jar5) necessrios ao seu projeto Java que vai utilizar o Hibernate. Voc precisar incluir no seu projeto os seguintes arquivos: O hibernate3.jar, que fica no diretrio raiz do Hibernate Core; Exemplo: d:\java-frameworks\hibernate-3.2\hibernate3.jar Todos os pacotes dentro do diretrio lib do Hibernate Core, que so as dependncias e recursos utilizados pelo Hibernate; Exemplo: d:\java-frameworks\hibernate-3.2\lib\* O hibernate-annotetions.jar, que fica no diretrio raiz do Hibernate Annotetions; Exemplo: d:\java-frameworks\hibernate-annotetions-3.3.0\hibernate-annotetions.jar Todos os pacotes dentro do diretrio lib do Hibernate Annotetions, que so suas dependncias; Exemplo: d:\java-frameworks\hibernate-annotetions-3.3.0\lib\* 3. Mapeamento Objeto Relacional: Tambm conhecido pela sigla MOR, como citado anteriormente. Consiste em se apontar a correspondncia que existe entre os atributos de uma classe (modelo OO) e os campos de uma tabela no banco de dados (modelo relacional). Isto torna possvel, por exemplo, a construo automtica de objetos a partir do retorno de uma consulta SQL. Podemos realizar o mapeamento por uma das seguintes tcnicas: Uso de XML: Consiste em se criar um arquivo XML para mapear cada classe de domnio do projeto cujos objetos sero persistidos. preciso acrescentar estes arquivos XML de mapeamento no arquivo hibernate.cfg.xml, para indicar a localizao fsica de cada um deles.

4: CLASSPAH uma varivel de ambiente que indica a localizao fsica das bibliotecas e classes externas que o projeto precisar utilizar; 5: Arquivos .jar so arquivos empacotados, ou seja, arquivos que servem de repositrio para outros arquivos. So utilizados em Java para agrupar, organizar e facilitar a difuso das classes de um projeto.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 3

A principal vantagem desta tcnica a separao do cdigo de mapeamento OR e o cdigo da classe de domnio (bean). A desvantagem que se trata de um processo mais trabalhoso e com uma quantidade maior de cdigo; Uso de Anotaes: Tambm conhecidas como annotetions uma forma prtica e fcil de fazer anotaes no cdigo Java, ou seja, de incluir metadados sobre uma classe dentro do prprio cdigo desta classe. Como vantagens, isto evita a criao de um novo arquivo para fazer o MOR, escreve-se bem menos cdigo e alguns defendem que haja mais legibilidade devido proximidade das informaes, ou seja, dos metadados e do cdigo Java. Tem a desvantagem, contudo, de misturar informaes do modelo relacional dentro da classe de domnio em Java. H tambm quem defenda que o cdigo fica menos legvel com esta mistura. 4. Configurao do Hibernate: H um arquivo especfico para a realizao desta tarefa chamado hibernate.cfg.xml. Neste arquivo voc deve informar, nas respectivas entradas, informaes como: A URL JDBC; O usurio e a senha de acesso ao banco; Os arquivos XML para mapeamento das classes de domnio (caso haja); As classes mapeadas com annotetions (caso haja) Vrias outras configuraes possveis.

O ideal que voc faa a sua configurao a partir de um arquivo hibernate.cfg.xml j existente, ou seja, a partir de um modelo que voc possa copiar e modificar para a sua necessidade. Isto torna erros bobos, como os de digitao, menos freqentes. O prprio Hibernate disponibiliza um modelo quando voc baixa o Hibernate Core. Esse modelo fica no diretrio etc. Exemplo: d:\hibernate-3.2\etc\hibernate.cfg.xml ATENO: Este arquivo deve ficar no diretrio raiz do seu projeto, em geral o diretrio src, para que o Hibernate funcione. Caso contrrio, voc receber uma erro com a mensagem /hibernate.cfg.xml not found.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 4

Como configurar o CLASSPH do projeto?

Esta uma operao simples. Basta clicar com o boto direito sobre o projeto e selecionar a opo propriedades no menu suspenso que aparecer. A tela de propriedades do seu projeto se abrir, como exemplificado na figura 01. Selecione a opo Java Build Path aba Libraries. Nesta aba voc poder acrescentar os arquivos jar ao seu projeto por meio dos botes que aparecem direita da tela. Note que na figura 01 todos os arquivos jar necessrios ao Hibernate j foram acrescentados ao projeto. Para fazer esta configurao, os arquivos jar foram colocados, fisicamente, em d:\teste\lib e depois, utilizando o boto Add External JARs, os arquivos foram localizados e acrescentados ao projeto.

Figura 01: Tela de propriedades do projeto.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 5

Exemplo de organizao do projeto:

A estrutura na figura 02 demonstra a organizao bsica do cdigo e das bibliotecas em uma aplicao WEB seguindo o padro MVC. Note nesta figura os seguintes detalhes: Todos os arquivos .jar necessrios para o uso do Hibernate foram acrescentados ao projeto (Referenced Libraries), configurando-se o CLASSPATH; O arquivo de configurao do Hibernate (hibernate.cfg.xml) est no diretrio raiz (src) do projeto. Cada classe foi colocada na camada mais apropriada, de acordo com o padro MVC; Os XMLs que mapeiam as classes de domnio esto no pacote modelo.

Figura 02: Exemplo de organizao da aplicao.

Tutorial Hibernate V.2 Edmilson Prata abr/2010 Pg. 6

Exemplo de configurao do arquivo hibernate.cfg.xml:

No arquivo de configurao do Hibernate, que deve estar no diretrio raiz do seu projeto (em geral o src), voc deve configurar, basicamente, os seguintes dados: A URL JDBC Na propriedade hibernate.connection.url; O driver JDBC que hibernate.connection.driver_class; ser utilizado Na propriedade

O nome do usurio Na propriedade hibernate.connection.username; A senha do usurio Na propriedade hibernate.connection.password; Os arquivos XML que fazem o mapeamento das classes de domnio do seu projeto, caso haja, na propriedade mapping resource; As classes de domnio mapeadas por anotaes, caso haja, na propriedade mapping class.

Veja o arquivo-exemplo de uma configurao utilizando o gerenciamento do Pool de conexes do prprio Hibernate e o PostgreSQL como SGBD:

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> <hibernate-configuration> <session-factory> <property name="hibernate.connection.url"> jdbc:postgresql://127.0.0.1:5432/aulas?charSet=LATIN1</property> <property name="hibernate.connection.driver_class">org.postgresql.Driver</property> <property name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property> <property name="hibernate.connection.username">postgres</property> <property name="hibernate.connection.password">senha</property> <property name="hibernate.show_sql">true</property> <property name="hibernate.format_sql">true</property> <!-Configura o hibernate para comparar as classes com as tabelas do banco e atualiza-las automaticamente:

--> <property name="hibernate.hdm2ddl.auto">update</property> <!-- Alternativa para gerenciamento do pool de conexes com o BD: O C3P0 --> <!-<property name="hibernate.c3p0.min_size">5</property> <property name="hibernate.c3p0.max_size">20</property> <property name="hibernate.c3p0.timeout">180</property> <property name="hibernate.c3p0.idle_test_period">100</property> --> <!-- Classes de domnio mapeadas com annotations: --> <mapping class="modelo.ClasseBean1" /> <mapping class="modelo.ClasseBean2" /> <!-- Classes de domnio mapeadas por XML: --> <mapping resource="modelo/ClasseBean3.hbm.xml"/> </session-factory> </hibernate-configuration>

Exemplo 01: Configurao do arquivo hibernate.cfg.xml

Tutorial Hibernate V.2 Edmilson Prata abr/2010 Pg. 7

Exemplo de mapeamento objeto relacional com arquivo XML:

O exemplo 02 apresenta o mapeamento de uma classe de domnio chamada JavaBean1 ( esquerda) com o uso de XML ( direita). Este um mapeamento bsico, ou seja, no explora os vrios recursos do Hibernate como, por exemplo, juno de tabelas, relacionamentos entre objetos, etc. A classe sugerida possui apenas dois atributos e eles so mapeados pelo cdigo do arquivo XML.

Exemplo 02: Cdigo da classe JavaBean1 e cdigo XML para o mapeamento objeto relacional.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 8

Exemplo de mapeamento objeto relacional com anotaes:

O exemplo 03 apresenta o mapeamento da classe JavaBean1, a mesma utilizada no exemplo 02, s que desta vez utilizando anotaes ao invs de XML.

import import import import import

javax.persistence.Column; javax.persistence.Entity; javax.persistence.GeneratedValue; javax.persistence.Id; javax.persistence.Table;

@Entity //Indica que a classe uma classe persistente @Table(name = "tb_java_bean_1") // Indica em que tabela esto os dados Public class JavaBean1 { // atributos: @Id //Indica que trata-se da PK na tabela @GeneratedValue //que o valor ser gerado pelo banco @Column(name = "cl_atr1") //o nome da coluna na tabela private Integer atributo1; @Column(name = "cl_atr1") private String atributo2; // construtor padro: public JavaBean1() { super(); } // gets e sets: public Integer getAtributo1() { return atributo1; } public void setAtributo1(Integer atributo1) { this.atributo1 = atributo1; } public String getAtributo2() { return atributo2; } public void setAtributo2(String atributo2) { this.atributo2 = atributo2; } }

Exemplo 03: Classe JavaBean1 mapeada com anotaes ou annotetions.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 9

Erros comuns na configurao e uso do Hibernate:

Veremos a seguir alguns erros comuns na utilizao do Hibernate: 1. Erro /hibernate.cfg.xml not found: O arquivo de configurao do Hibernate no foi encontrado. comum colocar-se este arquivo em local incorreto ou esquecer-se dele. Ele deve estar no diretrio raiz do projeto; 2. Erro JDBC driver class not found: driver.Informado: O driver JDBC no foi encontrado. Provavelmente voc no acrescentou o driver (arquivo jar) ao CLASSPATH do projeto ou a descrio/caminho do driver especificada no arquivo hibernate.cfg.xml est errado (propriedade hibernate.connection.driver_class); 3. Erro database nome_do_banco does not found: O banco de dados especificado na URL JDBC (arquivo hibernate.cfg.xml) provavelmente est escrito errado ou o banco no foi criado no SGBD; 4. Erro Conexo negada: FATAL: password authentication failed for user "nomeUsuarioFornecido": O nome de usurio ou a senha informados no arquivo hibernate.cfg.xml esto errados; 5. Erro no persister for: NomeDaClasse: O arquivo XML da classe indicada (que faz o mapeamento desta) no foi includo no arquivo de configurao do Hibernate; 6. Erro Resource: NomeDoArquivo.hbm.xml not found: Ou o arquivo XML que faz o mapeamento da classe de domnio no existe, ou a sua localizao (indicada no arquivo hibernate.cfg.xml) est errada ou, ainda, o nome do arquivo foi escrito errado; 7. Erro relation nome_tabela does not exist: A tabela indicada no XML no foi encontrada no banco o nome da tabela pode ter sido escrito errado; 8. Erro NoClassDefFoundError: NomeDaClasse: O nome da classe especificado no XML est incorreto. muito comum escrever-se o nome da classe com letra minscula no XML. Ateno a sua digitao! 9. Erro persistent class not found: NomeDaClasse: A classe especificada no XML no foi encontrada no caminha informado. comum esquecer-se de indicar o pacote ao qual a classe pertence ou digitar algum nome incorretamente; 10. Erro Object class NomeDaClasse must declare a default (no-argument) constructor: Significa que a classe de domnio indicada no possui um construtor vazio. Para utilizar o Hibernate preciso que as classes de domnio possuam o construtor padro, ou seja, sem argumentos; 11. Erro duplicate import: NomeDaClasse: Indica algum problema no XML da classe. Pode ser mapeamento de algum atributo em duplicidade, algum atributo mapeado com um tipo de dado invlido (ex. type=real), etc.; 12. Erro ClassCastException indicando algum mtodo set da classe de domnio: O tipo especificado no XML para o atributo, cujo mtodo set foi chamado, est diferente do que foi definido na classe de domnio;

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 10

13. Erro NullPointerException at NomeDaClasee.setPropertyValues(AbstractEntityPersister.java): Ocorre quando um atributo da classe definido com um tipo primitivo e, ao carregar um objeto solicitado (consulta), um valor null retornado para este atributo. Como o null no pode ser atribudo a um primitivo o erro acontece. Para evitar este tipo de problema, no utilize tipos primitivos ao definir os atributos das suas classes de domnio. A figura 03 abaixo demonstra a ocorrncia deste erro;

Figura 03: Erro ao tentar atribuir null para um atributo de tipo primitivo.

Tutorial Hibernate V.2 Edmilson Prata abr/2010

Pg. 11