Hibernate.orgCommunity Documentation
Devido ao fato do Hibernate ser projetado para operar em vários ambientes diferentes, há um grande número de parâmetros de configuração. Felizmente, a maioria possui valores padrão consideráveis e o Hibernate é distribuído com um arquivo hibernate.properties de exemplo no etc/ que mostra várias opções. Apenas coloque o arquivo de exemplo no seu classpath e personalize-o.
Uma instância de org.hibernate.cfg.Configuration representa um conjunto inteiro de mapeamentos de tipos Java de aplicação para um banco de dados SQL. O org.hibernate.cfg.Configuration é usado para construir uma SessionFactory imutável. Os mapeamentos são compilados a partir de diversos arquivos de mapeamento XML.
Você pode obter uma instância org.hibernate.cfg.Configuration intanciando-a diretamente e especificando os documentos de mapeamento XML. Se os arquivos de mapeamento estiverem no classpath, use addResource(). Por exemplo:
Configuration cfg = new Configuration()
.addResource("Item.hbm.xml")
.addResource("Bid.hbm.xml");
Uma alternativa é especificar a classe mapeada e permitir que o Hibernate encontre o documento de mapeamento para você:
Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class);
O Hibernate procurará pelos arquivos de mapeamento chamados /org/hibernate/auction/Item.hbm.xml e /org/hibernate/auction/Bid.hbm.xml no classpath. Esta abordagem elimina qualquer nome de arquivo de difícil compreensão.
Uma Configuration também permite que você especifique propriedades de configuração específica. Por exemplo:
Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class)
.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
.setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
.setProperty("hibernate.order_updates", "true");
Esta não é a única forma de passar as propriedades de configuração para o Hibernate. As várias opções incluem:
Passar uma instância de java.util.Properties para Configuration.setProperties().
Colocar hibernate.properties de arquivo nomeado no diretório raíz do classpath.
Determinar as propriedades do System usando java -Dproperty=value.
Incluir elementos <property> no hibernate.cfg.xml (discutido mais tarde).
Caso você deseje inicializar rapidamente o hibernate.properties é a abordagem mais rápida.
O org.hibernate.cfg.Configuration é previsto como um objeto de tempo de inicialização, a ser descartado quando um SessionFactory for criado.
Quando todos os mapeamentos forem analisados pelo org.hibernate.cfg.Configuration, a aplicação deve obter uma factory para as instâncias do org.hibernate.Session. O objetivo desta factory é ser compartilhado por todas as threads da aplicação:
SessionFactory sessions = cfg.buildSessionFactory();
O Hibernate permite sua aplicação instanciar mais do que um org.hibernate.SessionFactory. Isto será útil se você estiver usando mais do que um banco de dados.
Normalmente, você deseja que o org.hibernate.SessionFactory crie e faça um um pool de conexões JDBC para você. Se você seguir essa abordagem, a abertura de um org.hibernate.Session será tão simples quanto:
Session session = sessions.openSession(); // open a new Session
Assim que você fizer algo que requeira o acesso ao banco de dados, uma conexão JDBC será obtida a partir do pool.
Para esse trabalho, precisaremos passar algumas propriedades da conexão JDBC para o Hibernate. Todos os nomes de propriedades Hibernate e semânticas são definidas na classe org.hibernate.cfg.Environment. Descreveremos agora as configurações mais importantes para a conexão JDBC.
O Hibernate obterá conexões (e efetuará o pool) usando java.sql.DriverManager se você determinar as seguintes propriedades:
Tabela 3.1. Propriedades JDBC Hibernate
| Nome da Propriedade | Propósito |
|---|---|
| hibernate.connection.driver_class | JDBC driver class |
| hibernate.connection.url | JDBC URL |
| hibernate.connection.username | database user |
| hibernate.connection.password | database user password |
| hibernate.connection.pool_size | maximum number of pooled connections |
No entanto, o algoritmo de pool de conexões do próprio Hibernate é um tanto rudimentar. A intenção dele é ajudar a iniciar e não para ser usado em um sistema de produção ou até para testar o desempenho. Você deve utilizar um pool de terceiros para conseguir um melhor desempenho e estabilidade. Apenas substitua a propriedade hibernate.connection.pool_size pela configuração específica do pool de conexões. Isto irá desligar o pool interno do Hibernate. Por exemplo, você pode gostar de usar C3P0.
O C3P0 é um pool conexão JDBC de código aberto distribuído junto com Hibernate no diretório lib. O Hibernate usará o próprio org.hibernate.connection.C3P0ConnectionProvider para o pool de conexão se você configurar a propriedade hibernate.c3p0.*. Se você gostar de usar Proxool, consulte o pacote hibernate.properties e o web site do Hibernate para mais informações.
Este é um exemplo de arquivo hibernate.properties para c3p0:
hibernate.connection.driver_class = org.postgresql.Driver hibernate.connection.url = jdbc:postgresql://localhost/mydatabase hibernate.connection.username = myuser hibernate.connection.password = secret hibernate.c3p0.min_size=5 hibernate.c3p0.max_size=20 hibernate.c3p0.timeout=1800 hibernate.c3p0.max_statements=50 hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
Para usar dentro de um servidor de aplicação, você deve configurar o Hibernate para obter conexões de um servidor de aplicação javax.sql.Datasource registrado no JNDI. Você precisará determinar pelo menos uma das seguintes propriedades:
Tabela 3.2. Propriedades do Datasource do Hibernate
| Nome da Propriedade | Propósito |
|---|---|
| hibernate.connection.datasource | datasource JNDI name |
| hibernate.jndi.url | URL do fornecedor JNDI (opcional) |
| hibernate.jndi.class | classe de JNDI InitialContextFactory (opcional) |
| hibernate.connection.username | usuário de banco de dados (opcional) |
| hibernate.connection.password | senha de usuário de banco de dados (opcional) |
Eis um exemplo de arquivo hibernate.properties para um servidor de aplicação fornecedor de fontes de dados JNDI:
hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialectConexões JDBC obtidas de um datasource JNDI irão automaticamente participar das transações gerenciadas pelo recipiente no servidor de aplicação.
As propriedades de conexão arbitrárias podem ser acrescentandas ao "hibernate.connnection" ao nome da propriedade. Por exemplo, você deve especificar a propriedade de conexão charSet usando hibernate.connection.charSet.
Você pode definir sua própria estratégia de plugin para obter conexões JDBC implementando a interface org.hibernate.connection.ConnectionProvider e especificando sua implementação customizada através da propriedade hibernate.connection.provider_class.
Há um grande número de outras propriedades que controlam o comportamento do Hibernate em tempo de execução. Todos são opcionais e têm valores padrão lógicos.
Algumas destas propriedades são somente em nível de sistema.. As propriedades em nível de sistema podem ser determinadas somente via java -Dproperty=value ou hibernate.properties. Elas não podem ser configuradas por outras técnicas descritas acima.
Tabela 3.3. Propriedades de Configuração do Hibernate
| Nome da Propriedade | Propósito |
|---|---|
| hibernate.dialect | O nome da classe de um Hibernate org.hibernate.dialect.Dialect que permite o Hibernate gerar SQL otimizado para um banco de dados relacional em particular. e.g. Na maioria dos casos, o Hibernate irá atualmente estar apto a escolher a implementação |
| hibernate.show_sql | Escreve todas as instruções SQL no console. Esta é uma alternativa para configurar a categoria de log org.hibernate.SQL to debug. e.g. |
| hibernate.format_sql | Imprime o SQL formatado no log e recipiente. e.g. |
| hibernate.default_schema | Qualifica no SQL gerado, os nome das tabelas desqualificadas com o esquema/espaço da tabela dado. e.g. |
| hibernate.default_catalog | Qualifica no SQL gerado, os nome das tabelas desqualificadas com catálogo dado. e.g. |
| hibernate.session_factory_name | O org.hibernate.SessionFactory irá automaticamente se ligar a este nome no JNDI depois de ter sido criado. e.g. |
| hibernate.max_fetch_depth | Estabelece a "profundidade" máxima para árvore de busca de união externa para associações finais únicas (um para um, muitos para um). Um 0 desativa por padrão a busca de união externa. eg. valores recomendados entre |
| hibernate.default_batch_fetch_size | Determina um tamanho padrão para busca de associações em lotes do Hibernate. eg. valores recomendados |
| hibernate.default_entity_mode | Determina um modo padrão para representação de entidade para todas as sessões abertas desta SessionFactory
|
| hibernate.order_updates | Força o Hibernate a ordenar os updates SQL pelo valor da chave primária dos ítens a serem atualizados. Isto resultará em menos deadlocks nas transações em sistemas altamente concorrente. e.g. |
| hibernate.generate_statistics | Se habilitado, o Hibernate coletará estatísticas úteis para o ajuste do desempenho. e.g. |
| hibernate.use_identifier_rollback | Se habilitado, propriedades identificadoras geradas serão zeradas para os valores padrão quando os objetos forem apagados. e.g. |
| hibernate.use_sql_comments | Se ligado, o Hibernate irá gerar comentários dentro do SQL, para facilitar a depuração, o valor padrão é false e.g. |
Tabela 3.4. JDBC Hibernate e Propriedades de Conexão
| Nome da Propriedade | Propósito |
|---|---|
| hibernate.jdbc.fetch_size | Um valor maior que zero determina o tamanho da buscado JDBC (chamadas Statement.setFetchSize()). |
| hibernate.jdbc.batch_size | Um valor maior que zero habilita o uso das atualizações em lotes JDBC2 pelo Hibernate. ex. valores recomentados entre |
| hibernate.jdbc.batch_versioned_data | Set this property to true if your JDBC driver returns correct row counts from executeBatch(). It is usually safe to turn this option on. Hibernate will then use batched DML for automatically versioned data. Defaults to false. e.g. |
| hibernate.jdbc.factory_class | Escolher um org.hibernate.jdbc.Batcher. Muitas aplicações não irão precisar desta propriedade de configuração. exemplo |
| hibernate.jdbc.use_scrollable_resultset | Habilita o uso dos resultados de ajustes roláveis do JDBC2 pelo Hibernate. Essa propriedade somente é necessária quando se usa Conexões JDBC providas pelo usuário. Do contrário, o Hibernate os os metadados da conexão. e.g. |
| hibernate.jdbc.use_streams_for_binary | Utilize fluxos para escrever/ler tipos binary ou tipos serializable para/do JDBC. *system-level property* e.g. |
| hibernate.jdbc.use_get_generated_keys | Possibilita o uso do PreparedStatement.getGeneratedKeys() JDBC3 para recuperar chaves geradas de forma nativa depois da inserção. Requer driver JDBC3+ e JRE1.4+, ajuste para falso se seu driver tiver problemas com gerador de indentificadores Hibernate. Por padrão, tente determinar o driver capaz de usar metadados da conexão. exemplo |
| hibernate.connection.provider_class | O nome da classe de um org.hibernate.connection.ConnectionProvider, do qual proverá conexões JDBC para o Hibernate. exemplo |
| hibernate.connection.isolation | Determina o nível de isolamento de uma transação JDBC. Verifique java.sql.Connection para valores significativos mas note que a maior parte dos bancos de dados não suportam todos os isolamentos que não são padrões. exemplo |
| hibernate.connection.autocommit | Habilita o auto-commit para conexões no pool JDBC (não recomendado). e.g. |
| hibernate.connection.release_mode | Especifica quando o Hibernate deve liberar conexões JDBC. Por padrão, uma conexão JDBC é retida até a sessão estar explicitamente fechada ou desconectada. Para uma fonte de dados JTA do servidor de aplicação, você deve usar after_statement para forçar a liberação da conexões depois de todas as chamadas JDBC. Para uma conexão não-JTA, freqüentemente faz sentido liberar a conexão ao fim de cada transação, usando after_transaction. O auto escolherá after_statement para as estratégias de transaçãoes JTA e CMT e after_transaction para as estratégias de transação JDBC. exemplo This setting only affects |
| hibernate.connection.<propertyName> | Passar a propriedade JDBC <propertyName> para DriverManager.getConnection(). |
| hibernate.jndi.<propertyName> | Passar a propriedade <propertyName> para o JNDI InitialContextFactory. |
Tabela 3.5. Propriedades de Cachê do Hibernate
| Nome da Propriedade | Propósito |
|---|---|
hibernate.cache.provider_class
| O nome da classe de um CacheProvider personalizado. exemplo |
hibernate.cache.use_minimal_puts
| Otimizar operação de cachê de segundo nível para minimizar escritas, ao custo de leituras mais freqüentes. Esta configuração é mais útil para cachês em cluster e, no Hibernate3, é habilitado por padrão para implementações de cache em cluster. exemplo |
hibernate.cache.use_query_cache
| Habilita a cache de consultas. Mesmo assim, consultas individuais ainda têm que ser habilitadas para o cache. exemplo |
hibernate.cache.use_second_level_cache
| Pode ser utilizado para desabilitar completamente o cache de segundo nível, o qual é habilitado por padrão para as classes que especificam um mapeamento <cache>. exemplo |
hibernate.cache.query_cache_factory
| O nome de classe de uma interface personalizada QueryCache, padroniza para o StandardQueryCache criado automaticamente. exemplo |
hibernate.cache.region_prefix
| Um prefixo para usar em nomes regionais de cachê de segundo nível exemplo |
hibernate.cache.use_structured_entries
| Força o Hibernate a armazenar dados no cachê de segundo nível em um formato mais humanamente amigável. exemplo |
Tabela 3.6. Propriedades de Transação do Hibernate
| Nome da Propriedade | Propósito |
|---|---|
hibernate.transaction.factory_class
| O nome da classe de uma TransactionFactory para usar com API do Hibernate Transaction ( por padrãoJDBCTransactionFactory ). exemplo |
jta.UserTransaction
| Um nome JNDI usado pelo JTATransactionFactorypara obter uma UserTransaction JTA a partir do servidor de aplicação. e.g. |
hibernate.transaction.manager_lookup_class
| O nome da classe de um TransactionManagerLookup. Ele é requerido quando o caching a nível JVM estiver habilitado ou quando estivermos usando um gerador hilo em um ambiente JTA. exemplo |
hibernate.transaction.flush_before_completion
| If enabled, the session will be automatically flushed during the before completion phase of the transaction. Built-in and automatic session context management is preferred, see Seção 2.5, “Sessões Contextuais”. e.g. |
hibernate.transaction.auto_close_session
| If enabled, the session will be automatically closed during the after completion phase of the transaction. Built-in and automatic session context management is preferred, see Seção 2.5, “Sessões Contextuais”. e.g. |
Tabela 3.7. Propriedades Variadas
| Nome da Propriedade | Propósito |
|---|---|
hibernate.current_session_context_class
| Supply a custom strategy for the scoping of the "current" Session. See Seção 2.5, “Sessões Contextuais” for more information about the built-in strategies. exemplo |
hibernate.query.factory_class
| Escolha a implementação de análise HQL. exemplo |
hibernate.query.substitutions
| Mapeamento a partir de símbolos em consultas do Hibernate para para símbolos SQL (símbolos devem ser por exemplo, funções ou nome literais). exemplo |
hibernate.hbm2ddl.auto
| Automaticamente valida ou exporta DDL esquema para o banco de dados quando o SessionFactory é criado. Com create-drop, o esquema do banco de dados será excluido quando a SessionFactory for fechada explicitamente. exemplo |
hibernate.bytecode.use_reflection_optimizer
|
Enables the use of bytecode manipulation instead of runtime reflection. This is a System-level property and cannot be set in e.g. |
hibernate.bytecode.provider
| Both javassist or cglib can be used as byte manipulation engines; the default is e.g. |
Você deve sempre determinar a propriedade hibernate.dialect para a subclasse de org.hibernate.dialect.Dialect correta de seu banco de dados. Se você especificar um dialeto, o Hibernate usará padrões lógicos para qualquer um das outras propriedades listadas abaixo, reduzindo o esforço de especificá-los manualmente.
Tabela 3.8. Dialetos SQL do Hibernate (hibernate.dialect)
| RDBMS | Dialeto |
|---|---|
| DB2 | org.hibernate.dialect.DB2Dialect |
| DB2 AS/400 | org.hibernate.dialect.DB2400Dialect |
| DB2 OS390 | org.hibernate.dialect.DB2390Dialect |
| PostgreSQL | org.hibernate.dialect.PostgreSQLDialect |
| Meu SQL | org.hibernate.dialect.MySQLDialect |
| MeuSQL com InnoDB | org.hibernate.dialect.MySQLInnoDBDialect |
| Meu SQL com MeuISAM | org.hibernate.dialect.MySQLMyISAMDialect |
| Oracle (qualquer versão) | org.hibernate.dialect.OracleDialect |
| Oracle 9i | org.hibernate.dialect.Oracle9iDialect |
| Oracle 10g | org.hibernate.dialect.Oracle10gDialect |
| Sybase | org.hibernate.dialect.SybaseDialect |
| Sybase Qualquer lugar | org.hibernate.dialect.SybaseAnywhereDialect |
| Servidor Microsoft SQL | org.hibernate.dialect.SQLServerDialect |
| SAP DB | org.hibernate.dialect.SAPDBDialect |
| Informix | org.hibernate.dialect.InformixDialect |
| HypersonicSQL | org.hibernate.dialect.HSQLDialect |
| Ingres | org.hibernate.dialect.IngresDialect |
| Progresso | org.hibernate.dialect.ProgressDialect |
| Mckoi SQL | org.hibernate.dialect.MckoiDialect |
| Interbase | org.hibernate.dialect.InterbaseDialect |
| Base Ponto | org.hibernate.dialect.PointbaseDialect |
| Base Frontal | org.hibernate.dialect.FrontbaseDialect |
| Firebird | org.hibernate.dialect.FirebirdDialect |
Se seu banco de dados suporta união externa no estilo ANSI, Oracle ou Sybase, a outer join fetching freqüentemente aumentará o desempenho limitando o número de chamadas (round trips) para e a partir do banco de dados. No entanto, isto ao custo de possivelmente mais trabalho desempenhado pelo próprio banco de dados. A busca por união externa (outer join fetching) permite um gráfico completo de objetos conectados por associações muitos-para-um, um-para-muitos, muitos-para-muitos e um-para-um para serem recuperadas em uma simples instrução SQL SELECT.
A busca por união externa pode ser desabilitada globalmente configurando a propriedade hibernate.max_fetch_depth para 0. Um valor 1 ou maior habilita a busca por união externa para associações um-para-um e muitos-para-um, cujos quais têm sido mapeados com fetch="join".
See Seção 20.1, “Estratégias de Busca ” for more information.
O Oracle limita o tamanho de matrizes de byte que podem ser passadas para/do driver JDBC. Se você desejar usar grandes instâncias de tipos binary ou serializable, você deve habilitar hibernate.jdbc.use_streams_for_binary. Essa é uma configuração que só pode ser feita em nível de sistema.
The properties prefixed by hibernate.cache allow you to use a process or cluster scoped second-level cache system with Hibernate. See the Seção 20.2, “O Cachê de Segundo Nível” for more information.
Você pode definir novos símbolos de consulta Hibernate usando hibernate.query.substitutions. Por exemplo:
hibernate.query.substitutions true=1, false=0
Isto faria com que os símbolos true e false passasem a ser traduzidos para literais inteiros no SQL gerado.
hibernate.query.substitutions toLowercase=LOWER
Isto permitirá que você renomeie a função LOWER no SQL.
Se você habilitar hibernate.generate_statistics, o Hibernate exibirá um número de métricas bastante útil ao ajustar um sistema via SessionFactory.getStatistics(). O Hibernate pode até ser configurado para exibir essas estatísticas via JMX. Leia o Javadoc da interface org.hibernate.stats para mais informações.
O Hibernate utiliza o Simple Logging Facade for Java (SLF4J) com o objetivo de registrar os diversos eventos de sistema. O SLF4J pode direcionar a sua saída de logging a diversos frameworks de logging (NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL ou logback) dependendo de sua escolha de vinculação. Com o objetivo de determinar o seu logging, você precisará do slf4j-api.jar em seu classpatch juntamente com o arquivo jar para a sua vinculação preferida - slf4j-log4j12.jar no caso do Log4J. Consulte o SLF4J documentation para maiores detalhes. Para usar o Log4j você precisará também colocar um arquivo log4j.properties em seu classpath. Um exemplo do arquivo de propriedades está distribuído com o Hibernate no diretório src/.
Nós recomendamos que você se familiarize-se com mensagens de log do Hibernate. Tem sido um árduo trabalho fazer o log Hibernate tão detalhado quanto possível, sem fazê-lo ilegível. É um dispositivo de controle de erros essencial. As categorias de log mais interessantes são as seguintes:
Tabela 3.9. Categorias de Log do Hibernate
| Categoria | Função |
|---|---|
org.hibernate.SQL | Registra todas as instruções SQL DML a medida que elas são executadas |
org.hibernate.type | Registra todos os parâmetros JDBC |
org.hibernate.tool.hbm2ddl | Registra todas as instruções SQL DDL a medida que elas são executadas |
org.hibernate.pretty | Registra o estado de todas as entidades (máximo 20 entidades) associadas à sessão no momento da liberação (flush). |
org.hibernate.cache | Registra todas as atividades de cachê de segundo nível |
org.hibernate.transaction | Registra atividades relacionada à transação |
org.hibernate.jdbc | Registra todas as requisições de recursos JDBC |
org.hibernate.hql.ast.AST | Registra instruções SQL e HQL durante a análise da consultas |
org.hibernate.secure | Registra todas as requisições de autorização JAAS |
org.hibernate | Registra tudo. Apesar de ter muita informação, é muito útil para o problema de inicialização. |
Ao desenvolver aplicações com Hibernate, você deve quase sempre trabalhar com o depurador debug habilitado para a categoria org.hibernate.SQL, ou, alternativamente, com a propriedade hibernate.show_sql habilitada.
A interface org.hibernate.cfg.NamingStrategy permite que você especifique um "padrão de nomeação" para objetos do banco de dados e elementos de esquema.
Você deve criar regras para a geração automaticamente de identificadores do banco de dados a partir de identificadores Java ou para processar colunas "lógicas" e nomes de tabelas dado o arquivo de mapeamento para nomes "físicos" de tabelas e colunas. Este recurso ajuda a reduzir a verbosidade do documento de mapeamento, eliminando interferências repetitivas (TBL_ prefixos, por exemplo). A estratégia padrão usada pelo Hibernate é bastante mínima.
Você pode especificar uma estratégia diferente ao chamar Configuration.setNamingStrategy() antes de adicionar os mapeamentos:
SessionFactory sf = new Configuration()
.setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
.addFile("Item.hbm.xml")
.addFile("Bid.hbm.xml")
.buildSessionFactory();
org.hibernate.cfg.ImprovedNamingStrategy é uma estratégia interna que pode ser um ponto inicial útil para algumas aplicações.
Uma maneira alternativa de configuração é especificar uma configuração completa em um arquivo chamado hibernate.cfg.xml. Este arquivo pode ser usado como um substituto para o arquivo hibernate.properties ou, se ambos estiverem presentes, para substituir propriedades.
O arquivo XML de configuração deve ser encontrado na raíz do seu CLASSPATH. Veja um exemplo:
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<!-- a SessionFactory instance listed as /jndi/name -->
<session-factory
name="java:hibernate/SessionFactory">
<!-- properties -->
<property name="connection.datasource"
>java:/comp/env/jdbc/MyDB</property>
<property name="dialect"
>org.hibernate.dialect.MySQLDialect</property>
<property name="show_sql"
>false</property>
<property name="transaction.factory_class">
org.hibernate.transaction.JTATransactionFactory
</property>
<property name="jta.UserTransaction"
>java:comp/UserTransaction</property>
<!-- mapping files -->
<mapping resource="org/hibernate/auction/Item.hbm.xml"/>
<mapping resource="org/hibernate/auction/Bid.hbm.xml"/>
<!-- cache settings -->
<class-cache class="org.hibernate.auction.Item" usage="read-write"/>
<class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
<collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>
</session-factory>
</hibernate-configuration
>
Como você pode ver, a vantagem deste enfoque é a externalização dos nomes dos arquivos de mapeamento para configuração. O hibernate.cfg.xml também é mais conveniente caso você tenha que ajustar o cache do Hibernate. Note que a escolha é sua em usar hibernate.properties ou hibernate.cfg.xml, ambos são equivalentes, exceto os acima mencionados de usar a sintaxe de XML.
Com a configuração do XML, iniciar o Hibernate é então tão simples quanto:
SessionFactory sf = new Configuration().configure().buildSessionFactory();
Você poderá escolher um arquivo de configuração XML diferente, utilizando:
SessionFactory sf = new Configuration()
.configure("catdb.cfg.xml")
.buildSessionFactory();
O Hibernate tem os seguintes pontos da integração para a infraestrutura de J2EE:
DataSources gerenciados pelo container: O Hibernate pode usar conexões JDBC gerenciadas pelo Container e fornecidas pela JNDI. Geralmente, um TransactionManager compatível com JTA e um ResourceManager cuidam do gerenciamento da transação (CMT), especialmente em transações distribuídas, manipuladas através de vários DataSources. Naturalmente, você também pode demarcar os limites das transações programaticamente (BMT) ou você poderia querer usar a API opcional do Hibernate Transaction para esta manter seu código portável.
Vinculação (binding) automática à JNDI: O Hibernate pode associar sua SessionFactory a JNDI depois de iniciado.
Vinculação (binding) da Sessão na JTA: A Session do Hibernate pode automaticamente ser ligada ao escopo da transações JTA. Simplesmente localizando a SessionFactory da JNDI e obtendo a Session corrente. Deixe o Hibernate cuidar da liberação e encerramento da Session quando as transações JTA terminarem. A Demarcação de transação pode ser declarativa (CMT) ou programática (BMT/Transação do usuário).
JMX deployment: Se você usa um JMX servidor de aplicações capaz (ex. Jboss AS), você pode fazer a instalação do Hibernate como um MBean controlado. Isto evita ter que iniciar uma linha de código para construir sua SessionFactory de uma Configuration. O container iniciará seu HibernateService, e também cuidará das dependências de serviços (DataSources, têm que estar disponíveis antes do Hibernate iniciar, etc.).
Dependendo do seu ambiente, você pode ter que ajustar a opção de configuração hibernate.connection.aggressive_release para verdadeiro ( true ), se seu servidor de aplicações lançar exeções "retenção de conexão".
A API Hibernate Session é independente de qualquer sistema de demarcação de transação em sua arquitetura. Se você deixar o Hibernate usar a JDBC diretamente, através de um pool de conexões, você pode inicializar e encerrar suas transações chamando a API JDBC. Se você rodar em um servidor de aplicações J2EE, você poderá usar transações controladas por beans e chamar a API JTA e UserTransaction quando necessário.
Para manter seu código portável entre estes dois (e outros) ambientes, recomendamos a API Hibernate Transaction, que envolve e esconde o sistema subjacente. Você tem que especificar uma classe construtora para instâncias Transaction ajustando a propriedade de configuração do hibernate.transaction.factory_class.
Existem três escolhas, ou internas, padrões:
org.hibernate.transaction.JDBCTransactionFactorydelega as transações (JDBC) para bases de dados (Padrão)
org.hibernate.transaction.JTATransactionFactorydelega para uma transação à um container gerenciado se uma transação existente estiver de acordo neste contexto (ex: método bean de sessão EJB). No entanto, uma nova transação será iniciada e serão usadas transações controladas por um bean.
org.hibernate.transaction.CMTTransactionFactorydelega para um container gerenciador de transações JTA
Você também pode definir suas próprias estratégias de transação (para um serviço de transação CORBA, por exemplo).
Algumas características no Hibernate (ex., o cache de segundo nível, sessões contextuais com JTA, etc.) requerem acesso a JTA TransactionManager em um ambiente controlado. Em um servidor de aplicação você tem que especificar como o Hibernate pode obter uma referência para a TransactionManager, pois o J2EE não padroniza um mecanismo simples:
Tabela 3.10. Gerenciadores de transações JTA
| Factory de Transação | Servidor de Aplicação |
|---|---|
org.hibernate.transaction.JBossTransactionManagerLookup | JBoss |
org.hibernate.transaction.WeblogicTransactionManagerLookup | Weblogic |
org.hibernate.transaction.WebSphereTransactionManagerLookup | WebSphere |
org.hibernate.transaction.WebSphereExtendedJTATransactionLookup | WebSphere 6 |
org.hibernate.transaction.OrionTransactionManagerLookup | Orion |
org.hibernate.transaction.ResinTransactionManagerLookup | Resin |
org.hibernate.transaction.JOTMTransactionManagerLookup | JOTM |
org.hibernate.transaction.JOnASTransactionManagerLookup | JOnAS |
org.hibernate.transaction.JRun4TransactionManagerLookup | JRun4 |
org.hibernate.transaction.BESTransactionManagerLookup | Borland ES |
Uma SessionFactory de Hibernate vinculada à JNDI pode simplificar a localização da fábrica e a criação de novas Sessions. Observe que isto não está relacionado a um Datasource ligado a JNDI, simplesmente ambos usam o mesmo registro.
Se você desejar ter uma SessionFactory limitada a um nome de espaço de JNDI, especifique um nome (ex.: java:hibernate/SessionFactory) usando a propriedade hibernate.session_factory_name. Se esta propriedade for omitida, a SessionFactory não será limitada ao JNDI. Isto é muito útil em ambientes com uma implementação padrão JNDI de somente leitura (ex.: Tomcat).
Ao vincular a SessionFactory ao JNDI, o Hibernate irá utilizar os valores de hibernate.jndi.url, hibernate.jndi.class para instanciar um contexto inicial. Se eles não forem especificados, será usado o padrão InitialContext.
O Hibernate colocará automaticamente a SessionFactory no JNDI depois que você chamar a cfg.buildSessionFactory(). Isto significa que você terá esta chamada em pelo menos algum código de inicialização (ou classe de utilidade) em seu aplicativo, a não ser que você use a implementação JMX com o HibernateService (discutido mais tarde).
Se você usar um JNDI SessionFactory, o EJB ou qualquer outra classe obterá a SessionFactory utilizando um localizador JNDI.
Recomendamos que você vincule a SessionFactory ao JNDI em um ambiente gerenciado e utilize um singleton static. Para proteger seu código de aplicativo destes detalhes, também recomendamos que esconda o código de localização atual para uma SessionFactory em uma classe de ajuda, assim como o HibernateUtil.getSessionFactory(). Note que tal classe é também uma forma bastante conveniente de inicializar o Hibernate— veja o capítulo 1.
The easiest way to handle Sessions and transactions is Hibernate's automatic "current" Session management. For a discussion of contextual sessions see Seção 2.5, “Sessões Contextuais”. Using the "jta" session context, if there is no Hibernate Session associated with the current JTA transaction, one will be started and associated with that JTA transaction the first time you call sessionFactory.getCurrentSession(). The Sessions retrieved via getCurrentSession() in the "jta" context are set to automatically flush before the transaction completes, close after the transaction completes, and aggressively release JDBC connections after each statement. This allows the Sessions to be managed by the life cycle of the JTA transaction to which it is associated, keeping user code clean of such management concerns. Your code can either use JTA programmatically through UserTransaction, or (recommended for portable code) use the Hibernate Transaction API to set transaction boundaries. If you run in an EJB container, declarative transaction demarcation with CMT is preferred.
A linha cfg.buildSessionFactory() ainda precisa ser executada em algum local para conseguir uma SessionFactory em JNDI. Você pode escolher fazer isto em um bloqueio de inicializador static, como aquele em HibernateUtil, ou implementar o Hibernate como serviço gerenciado.
O Hibernate é distribuído com o org.hibernate.jmx.HibernateService para implementação em um servidor de aplicativo com capacidades JMX, tal como o JBoss AS. A implementação atual e configuração é comercial. Segue aqui um exemplo do jboss-service.xml para o JBoss 4.0.x:
<?xml version="1.0"?>
<server>
<mbean code="org.hibernate.jmx.HibernateService"
name="jboss.jca:service=HibernateFactory,name=HibernateFactory">
<!-- Required services -->
<depends
>jboss.jca:service=RARDeployer</depends>
<depends
>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>
<!-- Bind the Hibernate service to JNDI -->
<attribute name="JndiName"
>java:/hibernate/SessionFactory</attribute>
<!-- Datasource settings -->
<attribute name="Datasource"
>java:HsqlDS</attribute>
<attribute name="Dialect"
>org.hibernate.dialect.HSQLDialect</attribute>
<!-- Transaction integration -->
<attribute name="TransactionStrategy">
org.hibernate.transaction.JTATransactionFactory</attribute>
<attribute name="TransactionManagerLookupStrategy">
org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
<attribute name="FlushBeforeCompletionEnabled"
>true</attribute>
<attribute name="AutoCloseSessionEnabled"
>true</attribute>
<!-- Fetching options -->
<attribute name="MaximumFetchDepth"
>5</attribute>
<!-- Second-level caching -->
<attribute name="SecondLevelCacheEnabled"
>true</attribute>
<attribute name="CacheProviderClass"
>org.hibernate.cache.EhCacheProvider</attribute>
<attribute name="QueryCacheEnabled"
>true</attribute>
<!-- Logging -->
<attribute name="ShowSqlEnabled"
>true</attribute>
<!-- Mapping files -->
<attribute name="MapResources"
>auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>
</mbean>
</server
>
Este arquivo é implementado em um diretório chamado META-INF e envolto em um arquivo JAR com a extensão .sar (arquivo de serviço). Você também pode precisar envolver o Hibernate, suas bibliotecas de terceiros solicitadas, suas classes persistentes compiladas, assim como seus arquivos de mapeamento no mesmo arquivo. Seus beans de empresa (geralmente beans de sessão) podem ser mantidos em seus próprios arquivos JAR, mas você poderá incluir estes arquivos EJB JAR no arquivo de serviço principal para conseguir uma única unidade de (hot)-deployable. Consulte a documentação do JBoss AS para maiores informações sobre o serviço JMX e implementação EJB.
Copyright © 2004 Red Hat, Inc.