Nhibernate Tutorial: Dominando o Framework NHibernate

Por que eu devo ler este artigo:

Neste artigo, teremos uma introduç�o ao NHibernate que � um framework de ORM portado para a plataforma .NET origin�rio do framework Hibernate, um framework de bastante sucesso e utilizado at� ent�o, para a linguagem Java.

O que � NHibernate?

NHibernate � uma das soluç�es de Mapeamento objeto-relacional (ORM) para a plataforma de desenvolvimento Microsoft .NET, um framework que fornece o mapeamento do modelo relacional para a orientaç�o a objeto.

O NHibernate � livre e de c�digo aberto (open source) e � a vers�o portada do Java para o Microsoft .NET do Hibernate.

Guia do NHibernate:

Estrutura do NHibernate
Classes POCO para uso com o NHibernate
Mapeamento do NHibernate
- Mapeamento por Arquivo XML
- Mapeamento por Anotaç�o/Atributo
Arquivo de Configuraç�o do NHibernate
Acessando a Base de Dados atrav�s do NHibernate
Conclus�o

Ele lida com plano de persist�ncia para objetos e de um subjacentes de dados relacionais. Dando uma descriç�o XML de suas entidades e relacionamentos, NHibernate gera automaticamente c�digos SQL para carregar e guardar os objetos. Opcionalmente, voc� pode descrever o seu mapeamento de metadados com atributos em seu c�digo fonte.

Suporta persist�ncia transparente, o seu objeto classes n�o t�m de seguir um modelo de programaç�o restritiva. Classes persistentes n�o precisam implementar nenhuma interface ou herdar de uma classe especial base. Isto torna poss�vel desenvolver a l�gica empresarial utilizando o plano de objetos .NET (CLR) e Orientaç�o a Objetos.

Originalmente sendo uma parte do Hibernate 2.1, o NHibernate API � muito semelhante ao do Hibernate. Todo o conhecimento e documentaç�o existente �, portanto, diretamente aplic�vel ao NHibernate.

Diante deste port, o NHibernate ainda � um projeto novo em constante evoluç�o, tanto que ainda n�o acompanha seu �irm�o� mais famoso com as grandes facilidades e opç�es de mapeamento mais r�pido, principalmente com o uso de anotaç�es, que em .NET s�o chamados de atributos - S�o interfaces que s�o utilizadas para �decorar� Classes, um substituo dos arquivos XML, t�o odiados pelos programadores que facilitam muito o dia-a-dia.

Tal framework foi criado pela JBoss, criadora do Hibernate, por�m, com o tempo foi criada a NHForge que cuida diretamente do controle deste framework em site diferenciado, o NHForge.org, agora foi para esse site.

Estrutura do NHibernate

Vemos a estrutura b�sica do NHibernate na Figura 1.

Figura 1. Diagrama arquitet�nico do NHibernate

Na Figura 1, podemos observar que o NHibernate � acoplado diretamente entre O Banco de Dados a sua aplicaç�o, por�m, podemos observar tamb�m que os objetos persistentes - persistent objects - s�o utilizados atrav�s da aplicaç�o e, atrav�s de conex�o com o NHibernate, nos d� a entender que s�o as peças mais importantes desta engrenagem. Podemos tamb�m observar que dentro do dom�nio do NHibernate vemos o mapeamento em arquivos XML - Seç�o XML Mappings e o arquivo de configuraç�o do .NET, App.config ou Web.config. Fique certo de que o NHibernate, como uma Camada de Acesso aos Dados e, posteriormente de persist�ncia, de sua aplicaç�o, est�o fortemente acoplados porque todas as outras camadas, caso existam, s�o totalmente dependentes destes objetos de persist�ncia para E/S de dados. Seria muito interessante mostrar uma vis�o mais detalhada da arquitetura em tempo de execuç�o do NHibernate, por�m isso n�o � poss�vel pelas formas diferentes de abordagens e configuraç�es, destas separamos duas: As arquiteturas simples e detalhada.

Na sua arquitetura simples, faz com que a aplicaç�o disponibilize suas pr�prias conex�es utilizando o ADO.NET e gerencie suas pr�prias transaç�es. Esta abordagem usa um pequeno conjunto de APIs do NHibernate, como podemos verificar na figura 2.

Figura 2. Subconjunto de APIs do NHibernate

Na arquitetura Detalhada, existe uma abstraç�o da aplicaç�o totalmente diferente do uso das APIs do ADO.NET e deixa o NHibernate controlar e cuidar dos detalhes, permitindo assim que o mesmo cumpra o seu papel de Framework ORM, estes objetos dos quais o NHibernate faz uso internamente mostrados na Figura 3 e posteriormente explicados um a um.

Figura 3. Objetos presentes na Arquitetura Detalhada do NHibernate

Abaixo, listamos alguns dos objetos mais importantes presentes na figura 3:

ISession (NHibernate.ISession)

Um objeto single-threaded, ou seja, exclusivo por inst�ncia, e de curta duraç�o que representa a conversa entre a aplicaç�o e a unidade de persist�ncia. Encapsula uma conex�o ADO.NET. � uma factory para ITransaction. Mant�m um cache de primeiro n�vel, mandat�rio, ou seja, sob demanda, de objetos persistentes. Este cache � utilizado quando o grafo de objetos � utilizado ou busca de objetos por identificador.

Persistent Objects and Collections

S�o objetos contendo estados de persist�ncia e funç�es de neg�cio, tais objetos s�o sempre de curta duraç�o e single-threaded. Estes podem ser Classes POCO, o que mais importa sobre estes � que s�o sempre associados com uma, somente uma ISession. Assim que uma ISession � finalizada, eles s�o desconectados e liberados para serem utilizados por quaisquer camadas na aplicaç�o, isto quer dizer que pode ser utilizados como um DTO para transfer�ncia de dados de/para a Camada de Apresentaç�o.

Transient Objects and Collections

Objetos Transientes (de curta duraç�o, n�o persistidos em Banco de Dados) e Coleç�es s�o inst�ncias de Classes que n�o est�o atualmente associados com uma ISession. Eles podem ser instanciados ou n�o pela aplicaç�o e sendo assim n�o foram ainda persistidos ou podem ser instanciados por uma ISession fechada.

ITransaction (NHibernate.ITransaction)

Esta Interface � opcional. � um objeto utilizado pela aplicaç�o para especificar unidades de trabalho at�micas ou n�o. Aplica abstraç�o de uma transaç�o encapsulada do ADO.NET. Um ISession pode se utilizar de v�rias ITransaction em alguns casos.

IConnectionProvider (NHibernate.Connection.IConnectionProvider)

O Uso desta interface � opcional. Uma Factory para conex�es e comandos ADO.NET. Aplica abstraç�o de uma implementaç�o espec�fica e concreta de IDbConnection e IDbCommand. N�o � exposto para a aplicaç�o, mas, pode ser extendido/implementado pelo desenvolvedor.

IDriver (NHibernate.Driver.IDriver)

Uma interface que encapsula provedores ADO.NET diferentes, tais como convenç�es para nomes de par�metros e convenç�es suportadas para uso com o ADO.NET. Seu uso � opcional.

ITransactionFactory (NHibernate.Transaction.ITransactionFactory)

Uma Factory para instancia de ITransaction. N�o � exposta a aplicaç�o, mas pode ser extendida/implementada pelo desenvolvedor. Seu uso � opcional.

Ao usar a arquitetura simples, a aplicaç�o n�o utiliza nem ITransaction/ITransactionFactory e muito menos IConnectionProvider para utilizar o ADO.NET diretamente.

Neste artigo n�o utilizaremos todos estes objetos.

Classes POCO para uso com o NHibernate

Existem 4 regras principais para Classes POCO serem �reconhecidas� pelo NHibernate:

Use propriedades para campos persistentes.
Implemente um construtor padr�o, ou seja, vazio.
Crie uma propriedade Identificadora, ou Id.
Utilize classes que n�o sejam sealed e use m�todos virtuais.

Mapeamento do NHibernate

Atualmente, o mapeamento no NHibernate pode ser executado utilizando um arquivo XML ou com um novo projeto onde s�o utilizados atributos para decorarem as classes, primeiramente, vamos ao mapeamento utilizando o XML.

Mapeamento por Arquivo XML

O Mapeamento XML � a primeira etapa para a persist�ncia com o NHibernate � onde tudo começa, na listagem 1, temos um exemplo de cabeçalho est�vel para uso com o NHibernate. Por motivos de compilaç�o, o NHibernate solicita que os arquivos para mapeamento contenham tamb�m a extens�o .hbm como forma de ser reconhecido pelo assembly do ORM. Estes arquivos precisam ter sua propriedade Build Action setados como Embedded Resource, posto que no momento da compilaç�o do c�digo, o arquivo seja reconhecido e convertido para um hierarquia de classes utilizando ponto, por exemplo: temos que mapear a Classe Pessoa para persist�ncia, ent�o criamos o arquivo pessoa.hbm.xml e nas suas propriedades, colocamos o atributo Build Action como Embedded Resource, como mostrado na Figura 3.


<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
   assembly="DAL"
   namespace="DAL.Entidade">
...
...
...
....
...
</hibernate-mapping>

Listagem 1. Cabeçalho de XML para mapeamento

Como podemos ver na listagem 1, temos 2 atributos na tag hibernate-mapping que s�o assembly e namespace.

Assembly informa em qual Projeto est�o localizadas as Classes a serem buscadas pelo NHibernate no qual est� sendo apontada neste arquivo XML.
Namespace � o caminho completo de onde tais classes est�o dentro de um Projeto. Lembrando que quanto mais informaç�o neste sentido � menos tempo em que o compilador perde buscando as Classes para Mapeamento em mem�ria.

Figura 4. Arquivo XML configuraç�o e nomenclatura padr�o NHibernate.

Neste ponto, j� podemos mapear as nossas Classes de Persist�ncia. N�o � obrigat�rio criar um arquivo para cada Classe, podemos em um arquivo s� inserir todas, mas, como melhor pr�tica, � bom que seja criado um arquivo para cada Classe, desta forma, o entendimento do Sistema fica melhor e separa bem as responsabilidades. Na Listagem 2, temos um exemplo de Entidade na qual vamos mapear via XML.


public class Carro
    {
        #region atributos

        private Int32 id;
        private String modelo;
        private String motor;

        #endregion

        #region Propriedades

        public virtual Int32 Id
        {
            get { return this.id; }
            set { this.id = value; }
        }

        public virtual String Modelo
        {
            get { return this.modelo; }
            set { this.modelo = value; }
        }

        public virtual String Motor
        {
            get { return this.motor; }
            set { this.motor = value; }
        }

        #endregion

        #region Construtores

        public Carro()
        {

        }

        public Carro(String modelo, String motor)
        {
            this.Modelo = modelo;
            this.Motor = motor;
        }
        #endregion

        #region Sobrescritas
        public override string ToString()
        {
            return this.id + ", " + this.modelo + ", " + this.motor;
        }
        #endregion
    }
}

Listagem 2. Classe Carro

Para o correto mapeamento da Entidade, mapeamos apenas as Propriedades para o arquivo XML, como descrito na Listagem 3.


<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"
                   assembly="DAL"
                   namespace="DAL.Entidade">
 
  <class name="Carro" table="Carro">
    <id name="Id" column="id">
      <generator class="identity" />
    </id>
 
    <property name="Modelo" column="modelo" />
    <property name="Motor" column="motor" />
    
  </class>
  
</hibernate-mapping>

Listagem 3. Arquivo XML Carro.hbm.xml.

Na Listagem 3, temos algumas informaç�es importantes, a tag id significa que estamos mapeando a propriedade de identificaç�o �nica da Entidade, ou seja, valor exclusivo que identifica os dados gravados na Classe. Dentro desta tag, temos uma tag generator que como no Banco de Dados ela � um tipo de auto incremento, utilizamos o valor de atributo identity. Os valores poss�veis e permitidos pela tag generator dentro do atributo class s�o:

increment - Gera identificadores de qualquer tipo desde que sejam �nicos e que nenhum outro processo esteja inserindo dados na mesma tabela. N�o use este valor com um Cluster.
identity - Suporta campos do tipo identity, ou seja, auto incremento nos Bancos de Dados DB2, MySQL, MS SQL Server e Sybase. O identificador que � devolvido pelo Banco de Dados � convertido para o tipo da propriedade usando Convert.ChangeType. Qualquer propriedade inteira � permitida.
sequence - Usa uma Sequence criada em DB2, PostgreSQL, Oracle ou um generator do Firebird. O identificador retornado pelo Banco de Dados � convertido para o tipo da propriedade usando Convert.ChangeType. Qualquer propriedade inteira � permitida.
hilo - Usa um algoritmo de hi/lo para gerar de forma bem eficiente qualquer tipo inteiro de qualquer Tabela ou campo (por padr�o, hibernate_unique_key e next_hi respectivamente) como uma fonte de valores hi. O Algoritmo de hi/lo gera identificadores que s�o �nicos apenas para um Banco de Dados em espec�fico. N�o use este hilo com uma conex�o gerenciada pelo usu�rio, ou seja, quando as threads n�o s�o as mesmas.

Voc� pode usar o par�metro "where" para especificar um registro usado em uma tabela. Isto � muito �til se voc� quer usar uma tabela �nica para seus identificadores, com registros diferentes de cada tabela.

seqhilo - Usa um algoritmo de hi/lo para gerar de forma bem eficiente qualquer tipo inteiro, dada uma SEQUENCE criada no Banco de Dados.
uuid.hex - Usa System.Guid e seu m�todo ToString para gerar identificadores do tipo String. O tamanho da String depende do formato selecionado.
uuid.string - Usa um novo System.Guid para criar um tipo byte[] que � convertido para String.
guid - Usa um novo System.Guid como identificador.
guid.comb - Usa o algoritmo para gerar um novo System.Guid.
native - captura tipos identity, sequence ou hilo dependendo das capacidade existentes no Banco de Dados.
assigned - Deixa a aplicaç�o decidir por um identificador para o objeto antes de Save() ser chamado.
foreign - Usa o identificador de outro objeto associado. Normalmente usado em conjunç�o com uma associaç�o com chave prim�ria com a tag

A Tag property, n�o � necess�ria muita informaç�o, s�o as propriedades da Classe Carro que refletem os campos da Tabela.

Mapeamento por Anotaç�o/Atributo

Todos n�s j� sabemos que o NHibernate precisa de mapeamentos efetuados atrav�s de arquivos XML para que possa colocar em mem�ria o ORM para a persist�ncia. Para facilitar este trabalho foi criado um Projeto desenvolvido inicialmente por John Morris e que depois passou �s m�os de Pierre Henri Kuat�, mais conhecido como KPixel. Este projeto decora as Classes com atributos o que torna o arquivo XML desnecess�rio posto que o Projeto gera um Stream para a mem�ria como o XML faria, este projeto se chamado NHibernate Attributes que utiliza o assmbly NHibernate.Mapping.Attribute. Um exemplo de Classe mapeada com o assembly NHibernate.Mapping.Attributes na Listagem 4.


[Serializable]
[Class(Schema = "RevistaArtigo02", Table = "Carro")]
public class Carro

{
    #region atributos
    
    private Int32 id;
    private String modelo;
    private String motor;

    #endregion

    #region Propriedades
    [Id(Name="Id",Column="id"),Generator(1,Class="identity")]
    public virtual Int32 Id
    {
        get { return this.id; }
        set { this.id = value; }
    }

    [Property(Column="modelo")]
    public virtual String Modelo
    {
        get { return this.modelo; }
        set { this.modelo = value; }
    }

    [Property(Column="motor")]
    public virtual String Motor
    {
        get { return this.motor; }
        set { this.motor = value; }
    }

    #endregion

    #region Construtores

    public Carro()
    {

    }

    public Carro(String modelo, String motor)
    {
        this.Modelo = modelo;
        this.Motor = motor;
    }
    #endregion

    #region Sobrescritas
    public override string ToString()
    {
        return this.id + ", " + this.modelo + ", " + this.motor;
    }
    #endregion
}
}

Listagem 4. Classe �decorada� com atributos NHibernate

Arquivo de Configuraç�o do NHibernate

O Nhibernate � um framework bastante vers�til no qual permite que o configuremos via C�digo ou via arquivo XML, neste artigo vamos abordar o mapeamento via XML, para maiores informaç�es sobre a inicializaç�o do NHibernate. O Nhibernate precisa ser inicializado atrav�s da interface ISessionFactory, com ela, todas as Entidades s�o compiladas e colocadas na mem�ria, assim como os comandos deste arquivo XML s�o aceitos e colocados em mem�ria aguardando sua execuç�o. Como padr�o, o NHibernate aceita como arquivo de configuraç�o contendo a extens�o .cfg.xml, normalmente cria-se um arquivo na raiz do Projeto chamada hibernate.cfg.xml. Neste arquivo, registramos inclusive a string de conex�o, dialeto envolvido e outras configuraç�es de ambiente. Na Listagem 6, vemos um exemplo deste arquivo.


<?xml version="1.0" encoding="utf-8" ?>
<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
  <session-factory>
 
    <property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>
      <property name="connection.driver_class">NHibernate.Driver.SqlClientDriver</property>
    
      <!-- Aqui voc� deve coloca o seu Connectio String -->
      <property name="connection.connection_string">
        Data Source=ALLSPARK\SQLEXPRESS;Initial Catalog=RevistaArtigo02;Integrated Security=True
      </property>
    
      <property name="dialect">NHibernate.Dialect.MsSql2008Dialect</property>
    <property name="show_sql">true</property>
    <property name="current_session_context_class">thread</property>
  </session-factory>
</hibernate-configuration>

Listagem 6. Arquivo de configuraç�o hibernate.cfg.xml

Diante desta informaç�o, j� podemos instanciar a nossa ISessionFactory, que funciona como uma fachada. O mais importante � que devemos sempre prezar pela performance, � necess�rio que criemos uma Classe que gere um Singleton para que o NHibernate possa ser carregado e controlado de forma independente e desacoplada do c�digo, na Listagem 6, temos um exemplo de Classe que cont�m este padr�o de Projeto. Esta Classe acessa o arquivo de configuraç�o e faz com que toda a �m�gica� do que fizemos at� agora aconteça e que faça a conex�o com o Banco de Dados.


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
using NHibernate;
using NHibernate.Cfg;
 
namespace DAL.Reuso
{
    public sealed class NHibernateUtil
    {
        #region Atributos
 
        private static readonly ISessionFactory fabricaDeSessao;
        private const String CodSessaoAtual = "nhibernate.current_session";
 
        #endregion
 
        #region Construtor
 
        static NHibernateUtil()
        {
            try
            {
                ISessionFactory fabrica = new Configuration().Configure()
                .AddAssembly("DAL").BuildSessionFactory();
                
            }
            catch (Exception)
            {
                
                throw;
            }
        }
 
        #endregion
 
        #region M�todos de Controle
 
        public static ISession PegaSessaoEmUso()
        {
            ISession sessao = fabricaDeSessao.GetCurrentSession();
 
            if (sessao == null)
            {
                sessao = fabricaDeSessao.OpenSession();
            }
 
            return sessao;  
        }
 
        public static void FecharSessao()
        {
            ISession sessao = fabricaDeSessao.GetCurrentSession();
 
            if (sessao != null)
            {
                sessao.Close();
            }
        }
 
        public static void FecharFabricaDeSessao()
        {
            if (fabricaDeSessao != null || !fabricaDeSessao.IsClosed){
                fabricaDeSessao.Close();
            }
        }
 
        #endregion
 
    }
}

Listagem 6. Classe NHibernateUtil

Esta Classe, o leitor pode j� utiliz�-la como est� em seus projetos e at� aprimor�-la mais para que fique mais gen�rica a seu uso, assim como em futuros artigos que faremos de forma mais pr�tica demonstrando o uso de Generics, Fachadas e outros padr�es de projeto que facilitem a implementaç�o nos projetos de nossos leitores. J� criamos uma Classe que ir� e muito facilitar o nosso trabalho de acesso a base de dados, diante disto, vamos mostrar a melhor forma de utiliz�-la.

Acessando a Base de Dados atrav�s do NHibernate

Criamos na Listagem 6 uma Classe para acesso a Base de Dados, agora, veremos como que NHibernate se comunica com a Base de Dados para permitir que a persist�ncia seja efetuada.

Inicialmente, como uma melhor pr�tica, o NHibernate trabalha com transaç�es, esta � uma forma bem segura de trabalho, posto que caso algo d� errado, um Rollback pode ser dado, caso contr�rio, um commit grava as titleeraç�es no Banco de Dados e a conex�o � finalizada, salvo para operaç�es de busca, onde a sess�o continua em aberto. Devemos ter isso me mente at� mesmo quando o projeto solicitar que utilizemos mais de uma Classe em uma transaç�o.

O Nhibernate abre uma transaç�o, efetua o trabalho que precisa fazer, trata este trabalho, caso execute com sucesso, executa um commit, caso n�o executa um Rollback e posterimente fecha a sess�o. Uma Sess�o � composta de Transaç�o, execuç�o e Fechamento, o fechamento pode ser um finally com um comado de fechamento ou simplesmente uma execuç�o de operaç�es, neste caso, por exemplo, seria um INSERT, UPDATE e DELETE suficientes para fechar a Sess�o o que tamb�m n�o seria necess�rio que a fech�ssemos, um fragmento deste trabalho, pode ser visto na Listagem 7 j� com o uso de nossa Classe NHibernateUtil.



public void Gravar(Carro carro)
{
    ISession sessao = NHibernateUtil.PegaSessaoEmUso();
    ITransaction transacao = sessao.BeginTransaction();

    sessao.Save(carro);
    transacao.Commit();

    NHibernateUtil.FecharSessao();
}

}

Listagem 7. NHibernate interagindo com o Banco de Dados

Como sabemos, o Banco de Dados isola as operaç�es atrav�s das transaç�es, diante disso, temos um singleton abrindo e fechando a sess�o de forma protegida.

Conclus�o

O NHibernate � mais uma opç�o frente aos outros frameworks ORM existentes no mercado, ele n�o perde em nada com relaç�o ao Microsoft ADO.NET Entity Framework e outros. Vimos neste artigo o poder deste framework que j� faz bastante sucesso no meio Java e que pode tamb�m fazer bastante sucesso no mundo .NET. Vimos apenas 20% de todo o framework e com esta informaç�o, j� podemos trabalhar em um Projeto de m�dio porte. Em artigos pr�ximos, vamos falar de outras partes do NHibernate. Este por ser um framework um tanto extenso se fiz�ssemos aqui a cobertura deste, com certeza ficaria cansativo ao leitor.

Forte Abraço e at� a pr�xima, deixando bem claro que � um grande prazer compartilhar informaç�o.

Links �teis

Site oficial da Oracle

Microsoft .NET: Download Microsoft .NET
Oracle Banco de dados: Site oficial do Banco de dados Oracle

Saiba mais sobre Nhibernate ;)

Mapeamento Objeto-Relacional com NHibernate:
Neste artigo conheceremos um dos principais frameworks de mapeamento objeto-relacional do .NET Framework, o NHibernate, e como realizar o mapeamento fluente utilizando a ferramenta auxiliar Fluent NHibernate.
Mapeamento Objeto-Relacional com NHibernate e Fluent NHibernate:
Saiba o que � e como funciona o NHibernate, bem como o mapeamento objeto-relacional utilizando o projeto Fluent NHibernate.
Persist�ncia de dados com NHibernate:
Veja neste artigo um estudo de caso que aborda a utilizaç�o do framework ORM NHibernate como titleernativa para persist�ncia de dados em v�rios bancos.

Introdu��o ao NHibernate � Framework para Mapeamento Objeto-Relacional

Neste artigo, teremos uma introdução ao NHibernate que é um framework de ORM portado para a plataforma .NET originário do framework Hibernate.