Hibernate.orgCommunity Documentation

Capítulo 3. Configuration

3.1. Configuração programática
3.2. Obtendo uma SessionFactory
3.3. Conexões JDBC
3.4. Propriedades opcionais de configuração
3.4.1. Dialetos SQL
3.4.2. Busca por união externa (Outer Join Fetching)
3.4.3. Fluxos Binários (Binary Streams)
3.4.4. Cachê de segundo nível e consulta
3.4.5. Substituição na Linguagem de Consulta
3.4.6. Estatísticas do Hibernate
3.5. Logging
3.6. Implementando um NamingStrategy
3.7. Implementing a PersisterClassProvider
3.8. Arquivo de configuração XML
3.9. Java EE Application Server integration
3.9.1. Configuração de estratégia de transação
3.9.2. SessionFactory vinculada à JNDI
3.9.3. Gerenciamento de contexto de Sessão atual com JTA
3.9.4. implementação JMX

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:

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:


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:


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.PostgreSQLDialect

Conexõ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.

Tabela 3.3. Propriedades de Configuração do Hibernate

Nome da PropriedadePropósito
hibernate.dialectO 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. full.classname.of.Dialect

Na maioria dos casos, o Hibernate irá atualmente estar apto a escolher a implementação org.hibernate.dialect.Dialect correta baseada no JDBC metadata retornado pelo JDBC driver.

hibernate.show_sqlEscreve todas as instruções SQL no console. Esta é uma alternativa para configurar a categoria de log org.hibernate.SQL to debug.

e.g. true | false

hibernate.format_sqlImprime o SQL formatado no log e recipiente.

e.g. true | false

hibernate.default_schemaQualifica no SQL gerado, os nome das tabelas desqualificadas com o esquema/espaço da tabela dado.

e.g. SCHEMA_NAME

hibernate.default_catalogQualifica no SQL gerado, os nome das tabelas desqualificadas com catálogo dado.

e.g. CATALOG_NAME

hibernate.session_factory_nameO org.hibernate.SessionFactory irá automaticamente se ligar a este nome no JNDI depois de ter sido criado.

e.g. jndi/composite/name

hibernate.max_fetch_depthEstabelece 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 entre0 e 3

hibernate.default_batch_fetch_sizeDetermina um tamanho padrão para busca de associações em lotes do Hibernate.

eg. valores recomendados 4, 8, 16

hibernate.default_entity_modeDetermina um modo padrão para representação de entidade para todas as sessões abertas desta SessionFactory

dynamic-map, dom4j, pojo

hibernate.order_updatesForç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. true | false

hibernate.generate_statisticsSe habilitado, o Hibernate coletará estatísticas úteis para o ajuste do desempenho.

e.g. true | false

hibernate.use_identifier_rollbackSe habilitado, propriedades identificadoras geradas serão zeradas para os valores padrão quando os objetos forem apagados.

e.g. true | false

hibernate.use_sql_commentsSe ligado, o Hibernate irá gerar comentários dentro do SQL, para facilitar a depuração, o valor padrão é false

e.g. true | false

hibernate.id.new_generator_mappingsSetting is relevant when using @GeneratedValue. It indicates whether or not the new IdentifierGenerator implementations are used for javax.persistence.GenerationType.AUTO, javax.persistence.GenerationType.TABLE and javax.persistence.GenerationType.SEQUENCE. Default to false to keep backward compatibility.

e.g. true | false


Nota

We recommend all new projects which make use of to use @GeneratedValue to also set hibernate.id.new_generator_mappings=true as the new generators are more efficient and closer to the JPA 2 specification semantic. However they are not backward compatible with existing databases (if a sequence or a table is used for id generation).

Tabela 3.4. JDBC Hibernate e Propriedades de Conexão

Nome da PropriedadePropósito
hibernate.jdbc.fetch_sizeUm valor maior que zero determina o tamanho da buscado JDBC (chamadas Statement.setFetchSize()).
hibernate.jdbc.batch_sizeUm valor maior que zero habilita o uso das atualizações em lotes JDBC2 pelo Hibernate.

ex. valores recomentados entre 5 e 30

hibernate.jdbc.batch_versioned_dataSet 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. true | false

hibernate.jdbc.factory_classEscolher um org.hibernate.jdbc.Batcher. Muitas aplicações não irão precisar desta propriedade de configuração.

exemplo classname.of.BatcherFactory

hibernate.jdbc.use_scrollable_resultsetHabilita 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. true | false

hibernate.jdbc.use_streams_for_binaryUtilize fluxos para escrever/ler tipos binary ou tipos serializable para/do JDBC. *system-level property*

e.g. true | false

hibernate.jdbc.use_get_generated_keysPossibilita 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 true|false

hibernate.connection.provider_classO nome da classe de um org.hibernate.connection.ConnectionProvider, do qual proverá conexões JDBC para o Hibernate.

exemploclassname.of.ConnectionProvider

hibernate.connection.isolationDetermina 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 1, 2, 4, 8

hibernate.connection.autocommitHabilita o auto-commit para conexões no pool JDBC (não recomendado).

e.g. true | false

hibernate.connection.release_modeEspecifica 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 auto (padrão) | on_close | after_transaction | after_statement

This setting only affects Sessions returned from SessionFactory.openSession. For Sessions obtained through SessionFactory.getCurrentSession, the CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions. See Seção 2.3, “Sessões Contextuais”

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 PropriedadePropósito
hibernate.cache.provider_classO nome da classe de um CacheProvider personalizado.

exemplo classname.of.CacheProvider

hibernate.cache.use_minimal_putsOtimizar 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 true|false

hibernate.cache.use_query_cacheHabilita a cache de consultas. Mesmo assim, consultas individuais ainda têm que ser habilitadas para o cache.

exemplo true|false

hibernate.cache.use_second_level_cachePode 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 true|false

hibernate.cache.query_cache_factoryO nome de classe de uma interface personalizada QueryCache, padroniza para o StandardQueryCache criado automaticamente.

exemplo classname.of.QueryCache

hibernate.cache.region_prefixUm prefixo para usar em nomes regionais de cachê de segundo nível

exemplo prefix

hibernate.cache.use_structured_entriesForça o Hibernate a armazenar dados no cachê de segundo nível em um formato mais humanamente amigável.

exemplo true|false

hibernate.cache.default_cache_concurrency_strategySetting used to give the name of the default org.hibernate.annotations.CacheConcurrencyStrategy to use when either @Cacheable or @Cache is used. @Cache(strategy="..") is used to override this default.


Tabela 3.7. Propriedades Variadas

Nome da PropriedadePropósito
hibernate.current_session_context_classSupply a custom strategy for the scoping of the "current" Session. See Seção 2.3, “Sessões Contextuais” for more information about the built-in strategies.

exemplo jta | thread | managed | custom.Class

hibernate.query.factory_classEscolha a implementação de análise HQL.

exemplo org.hibernate.hql.ast. ASTQueryTranslatorFactory ou org.hibernate.hql.classic. ClassicQueryTranslatorFactory

hibernate.query.substitutionsMapeamento 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 hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.autoAutomaticamente 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 validate | update | create | create-drop

hibernate.hbm2ddl.import_files

Comma-separated names of the optional files containing SQL DML statements executed during the SessionFactory creation. This is useful for testing or demoing: by adding INSERT statements for example you can populate your database with a minimal set of data when it is deployed.

File order matters, the statements of a give file are executed before the statements of the following files. These statements are only executed if the schema is created ie if hibernate.hbm2ddl.auto is set to create or create-drop.

e.g. /humans.sql,/dogs.sql

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 hibernate.cfg.xml. Reflection can sometimes be useful when troubleshooting. Hibernate always requires either CGLIB or javassist even if you turn off the optimizer.

e.g. true | false

hibernate.bytecode.provider

Both javassist or cglib can be used as byte manipulation engines; the default is javassist.

e.g. javassist | cglib


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.


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:


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.

You can configure the persister implementation used to persist your entities and collections:

The latter in the list the higher in priority.

You can pass the PersisterClassProvider instance to the Configuration object.

SessionFactory sf = new Configuration()

    .setPersisterClassProvider(customPersisterClassProvider)
    .addAnnotatedClass(Order.class)
    .buildSessionFactory();

The persister class provider methods, when returning a non null persister class, override the default Hibernate persisters. The entity name or the collection role are passed to the methods. It is a nice way to centralize the overriding logic of the persisters instead of spreading them on each entity or collection mapping.

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://www.hibernate.org/dtd/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:

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:

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:


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.

It is recommended that you bind the SessionFactory to JNDI in a managed environment and use a static singleton otherwise. To shield your application code from these details, we also recommend to hide the actual lookup code for a SessionFactory in a helper class, such as HibernateUtil.getSessionFactory(). Note that such a class is also a convenient way to startup Hibernate—see chapter 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.3, “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.