hibernate-orm/doc/reference/fr/modules/architecture.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="architecture">

    <title>Architecture</title>

    <sect1 id="architecture-overview" revision="1">
        <title>G<EFBFBD>n<EFBFBD>ralit<EFBFBD>s</title>
        
        <para>
            Voici une vue (tr<74>s) haut niveau de l'architecture d'Hibernate :
        </para>

        <mediaobject>
            <imageobject role="fo">
                <imagedata fileref="images/overview.svg" format="SVG" align="center"/>
            </imageobject>
            <imageobject role="html">
                <imagedata fileref="../shared/images/overview.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>

        <para>
            Ce diagramme montre Hibernate utilisant une base de donn<6E>es et des donn<6E>es
            de configuration pour fournir un service de persistance (et des objets
            persistants) <20> l'application.
        </para>

        <para>
            Nous aimerions d<>crire une vue plus d<>taill<6C>e de l'architecture. Malheureusement,
            Hibernate est flexible et supporte diff<66>rentes approches. Nous allons en
            montrer les deux extr<74>mes. L'architecture l<>g<EFBFBD>re laisse l'application fournir
            ses propres connexions JDBC et g<>rer ses propres transactions. Cette approche
            utilise le minimum des APIs Hibernate :
        </para>

        <mediaobject>
            <imageobject role="fo">
                <imagedata fileref="images/lite.svg" format="SVG" align="center"/>
            </imageobject>
            <imageobject role="html">
                <imagedata fileref="../shared/images/lite.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>

        <para>
            L'architecture la plus compl<70>te abstrait l'application des APIs JDBC/JTA 
            sous-jacentes et laisse Hibernate s'occuper des d<>tails.
        </para>

        <mediaobject>
            <imageobject role="fo">
                <imagedata fileref="images/full_cream.svg" format="SVG" align="center"/>
            </imageobject>
            <imageobject role="html">
                <imagedata fileref="../shared/images/full_cream.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>

        <para>
            Voici quelques d<>finitions des objets des diagrammes :

            <variablelist spacing="compact">
                <varlistentry>
                    <term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term>
                    <listitem>
                        <para>
                            Un cache threadsafe (immuable) des mappings vers une (et une seule) base 
                            de donn<6E>es. Une factory (fabrique) de <literal>Session</literal> et un client
                            de <literal>ConnectionProvider</literal>. Peut contenir un cache optionnel de
                            donn<6E>es (de second niveau) qui est r<>utilisable entre les diff<66>rentes transactions
                            que cela soit au sein du m<>me processus (JVLM) ou par plusieurs n<>uds d'un cluster.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Session (<literal>org.hibernate.Session</literal>)</term>
                    <listitem>
                        <para>
                            Un objet mono-thread<61>, <20> dur<75>e de vie courte, qui repr<70>sente une conversation
                            entre l'application et l'entrep<65>t de persistance. Encapsule une connexion JDBC.
                            Factory (fabrique) des objets <literal>Transaction</literal>. Contient un cache
                            (de premier niveau) des objets persistants, ce cache est obligatoire. Il est 
                            utilis<69> lors de la navigation dans le graphe d'objets ou lors de la r<>cup<75>ration
                            d'objets par leur identifiant.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Objets et Collections persistants</term>
                    <listitem>
                        <para>
                            Objets mono-thread<61>s <20> vie courte contenant l'<27>tat de persistance
                            et la fonction m<>tier. Ceux-ci sont en g<>n<EFBFBD>ral les objets de type JavaBean
                            (ou POJOs) ; la seule particularit<69> est qu'ils sont associ<63>s avec une (et
                            une seule) <literal>Session</literal>. D<>s que la <literal>Session</literal>
                            est ferm<72>e, ils seront d<>tach<63>s et libres d'<27>tre utilis<69>s par n'importe laquelle
                            des couches de l'application (ie. de et vers la pr<70>sentation en tant que Data 
                            Transfer Objects - DTO : objet de transfert de donn<6E>es).
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Objets et collections transients</term>
                    <listitem>
                        <para>
                            Instances de classes persistantes qui ne sont actuellement pas associ<63>es <20>
                            une <literal>Session</literal>. Elles ont pu <20>tre instanci<63>es par l'application
                            et ne pas avoir (encore) <20>t<EFBFBD> persist<73>es ou elle ont pu <20>tre instanci<63>es par
                            une <literal>Session</literal> ferm<72>e.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Transaction (<literal>org.hibernate.Transaction</literal>)</term>
                    <listitem>
                        <para>
                            (Optionnel) Un objet mono-thread<61> <20> vie courte utilis<69> par l'application
                            pour d<>finir une unit<69> de travail atomique. Abstrait l'application des
                            transactions sous-jacentes qu'elles soient JDBC, JTA ou CORBA. Une
                            <literal>Session</literal> peut fournir plusieurs <literal>Transaction</literal>s
                            dans certains cas. Toutefois, la d<>limitation des transactions, via l'API d'Hibernate
                            ou par la <literal>Transaction</literal> sous-jacente, n'est jamais optionnelle!
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term>
                    <listitem>
                        <para>
                            (Optionnel) Une fabrique de (pool de) connexions JDBC. Abstrait l'application
                            de la <literal>Datasource</literal> ou du <literal>DriverManager</literal> sous-jacent.
                            Non expos<6F> <20> l'application, mais peut <20>tre <20>tendu/impl<70>ment<6E> par le d<>veloppeur.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term>
                    <listitem>
                        <para>
                            (Optionnel) Une fabrique d'instances de <literal>Transaction</literal>. Non
                            expos<6F> <20> l'application, mais peut <20>tre <20>tendu/impl<70>ment<6E> par le d<>veloppeur.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Interfaces d'extension</emphasis></term>
                    <listitem>
                        <para>
                            Hibernate fournit de nombreuses interfaces d'extensions optionnelles que 
                            vous pouvez impl<70>menter pour personnaliser le comportement de votre couche de persistance.
                            Reportez vous <20> la documentation de l'API pour plus de d<>tails.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>

        <para>
            Dans une architecture l<>g<EFBFBD>re, l'application n'aura pas <20> utiliser les APIs
            <literal>Transaction</literal>/<literal>TransactionFactory</literal>
            et/ou n'utilisera pas les APIs <literal>ConnectionProvider</literal>
            pour utiliser JTA ou JDBC.
        </para>
    </sect1>

    <sect1 id="architecture-states" revision="1">
        <title>Etats des instances</title>
        <para>
            Une instance d'une classe persistante peut <20>tre dans l'un des trois <20>tats suivants,
            d<>finis par rapport <20> un <emphasis>contexte de persistance</emphasis>.
            L'objet <literal>Session</literal> d'hibernate correspond <20> ce concept de 
            contexte de persistance :
        </para>
        
       <variablelist spacing="compact">
            <varlistentry>
                <term>passager (transient)</term>
                <listitem>
                    <para>
                        L'instance n'est pas et n'a jamais <20>t<EFBFBD> associ<63>e <20> un contexte
                        de persistance. Elle ne poss<73>de pas d'identit<69> persistante (valeur de cl<63> primaire)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>persistant</term>
                <listitem>
                    <para>
                        L'instance est associ<63>e au contexte de persistance.
                        Elle poss<73>de une identit<69> persistante (valeur de cl<63> primaire)
                        et, peut-<2D>tre, un enregistrement correspondant dans la base.
                        Pour un contexte de persistance particulier, Hibernate
                        <emphasis>garantit</emphasis> que l'identit<69> persistante
                        est <20>quivalente <20> l'identit<69> Java (emplacement m<>moire de l'objet)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d<EFBFBD>tach<EFBFBD></term>
                <listitem>
                    <para>
                        L'instance a <20>t<EFBFBD> associ<63>e au contexte de persistance mais ce
                        contexte a <20>t<EFBFBD> ferm<72>, ou l'instance a <20>t<EFBFBD> s<>rialis<69>e vers un
                        autre processus. Elle poss<73>de une identit<69> persistante et
                        peut-<2D>tre un enregistrement correspondant dans la base.
                        Pour des instances d<>tach<63>es, Hibernate ne donne aucune
                        garantie sur la relation entre l'identit<69> persistante et
                        l'identit<69> Java.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect1>    

    <sect1 id="architecture-jmx" revision="1">
        <title>Int<EFBFBD>gration JMX</title>
        <para>
            JMX est le standard J2EE de gestion des composants Java. 
            Hibernate peut <20>tre g<>r<EFBFBD> via un service JMX standard. Nous fournissons une impl<70>mentation
            d'un MBean dans la distribution : <literal>org.hibernate.jmx.HibernateService</literal>.
        </para>
        
        <para>
            Pour avoir un exemple sur la mani<6E>re de d<>ployer Hibernate en tant que service JMX dans le
            serveur d'application JBoss Application Server, r<>f<EFBFBD>rez vous au guide utilisateur JBoss (JBoss User Guide).
            Si vous d<>ployez Hibernate via JMX sur JBoss AS, vous aurez <20>galement les b<>n<EFBFBD>fices suivants :
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Gestion de la session :</emphasis> Le cycle de vie de la <literal>Session</literal>
                    Hibernate peut <20>tre automatiquement limit<69>e <20> la port<72>e d'une transaction JTA.
                    Cela signifie que vous n'avez plus besoin d'ouvrir et de fermer la <literal>Session</literal>
                    manuellement, cela devient le travail de l'intercepteur EJB de JBoss. Vous n'avez
                    pas non plus <20> vous occuper des d<>marcations des transactions dans votre code (sauf
                    si vous voulez <20>crire une couche de persistance qui soit portable, dans ce cas vous
                    pouvez utiliser l'API optionnelle <literal>Transaction</literal> d'Hibernate).
                    Vous appelez l'<literal>HibernateContext</literal> pour acc<63>der <20> la <literal>Session</literal>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>D<EFBFBD>ploiement HAR :</emphasis> Habituellement vous d<>ployez le service JMX
                    Hibernate en utilisant le descripteur de d<>ploiement de JBoss (dans un fichier EAR et/ou un SAR),
                    il supporte toutes les options de configuration usuelles d'une <literal>SessionFactory</literal>
                    Hibernate. Cependant, vous devez toujours nommer tous vos fichiers de mapping dans le
                    descripteur de d<>ploiement. Si vous d<>cidez d'utiliser le d<>ploiement optionnel sous forme
                    de HAR, JBoss d<>tectera automatiquement tous vos fichiers de mapping dans votre fichier HAR.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Consultez le guide d'utilisation de JBoss AS pour plus d'informations sur ces options.
        </para>

        <para>
            Les statistiques pendant l'ex<65>cution d'Hibernate (au runtime) sont une 
            autre fonctionnalit<69> disponible en tant que service JMX. Voyez pour cela
            <xref linkend="configuration-optional-statistics"/>.
        </para>
    </sect1>

    <sect1 id="architecture-jca" revision="1">
        <title>Support JCA</title>
        <para>
            Hibernate peut aussi <20>tre configur<75> en tant que connecteur JCA. R<>f<EFBFBD>rez-vous au site
            web pour de plus amples d<>tails. Il est important de noter que le support JCA d'Hibernate
            est encore consid<69>r<EFBFBD> comme exp<78>rimental.
        </para>
    </sect1>
    
    <sect1 id="architecture-current-session" revision="2">
        <title>Sessions Contextuelles</title>
        <para>
            Certaines applications utilisant Hibernate ont besoin d'une sorte de session "contextuelle", o<>
            une session est li<6C>e <20> la port<72>e d'un contexte particulier. Cependant, les applications ne d<>finissent
            pas toutes la notion de contexte de la m<>me mani<6E>re, et diff<66>rents contextes d<>finissent diff<66>rentes
            port<72>es <20> la notion de "courant". Les applications <20> base d'Hibernate, versions pr<70>c<EFBFBD>dentes <20> la 3.0
            utilisaient g<>n<EFBFBD>ralement un principe maison de sessions contextuelles bas<61>es sur le <literal>ThreadLocal</literal>,
            ainsi que sur des classes utilitaires comme <literal>HibernateUtil</literal>, ou utilisaient des
            framework tiers (comme Spring ou Pico) qui fournissaient des sessions contextuelles bas<61>es sur 
            l'utilisation de proxy/interception.
        </para>
        <para>
        	A partir de la version 3.0.1, Hibernate a ajout<75> la m<>thode <literal>SessionFactory.getCurrentSession()</literal>.
        	Initialement, cela demandait l'usage de transactions <literal>JTA</literal>, o<> la
        	transaction <literal>JTA</literal> d<>finissait la port<72>e et le contexte de la session courante.
        	L'<27>quipe Hibernate pense que, <20>tant donn<6E>e la maturit<69> des impl<70>mentations de <literal>JTA TransactionManager</literal> ,
        	la plupart (sinon toutes) des applications devraient utiliser la gestion des transactions par <literal>JTA</literal> 
        	qu'elles soient ou non d<>ploy<6F>es dans un conteneur <literal>J2EE</literal>. Par cons<6E>quent,
        	vous devriez toujours contextualiser vos sessions, si vous en avez besoin, via la m<>thode bas<61>e sur JTA.
        </para>
        <para>
            Cependant, depuis la version 3.1, la logique derri<72>re
            <literal>SessionFactory.getCurrentSession()</literal> est d<>sormais branchable.  
            A cette fin, une nouvelle interface d'extension (<literal>org.hibernate.context.CurrentSessionContext</literal>)
            et un nouveau param<61>tre de configuration (<literal>hibernate.current_session_context_class</literal>)
            ont <20>t<EFBFBD> ajout<75>s pour permettre de configurer d'autres moyens de d<>finir la port<72>e et le contexte des
            sessions courantes.
        </para>
        <para>
            Allez voir les Javadocs de l'interface <literal>org.hibernate.context.CurrentSessionContext</literal>
            pour une description d<>taill<6C>e de son contrat. Elle d<>finit une seule m<>thode,
            <literal>currentSession()</literal>, depuis laquelle l'impl<70>mentation est responsable
            de traquer la session courante du contexte. Hibernate fournit deux impl<70>mentation 
            de cette interface.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <literal>org.hibernate.context.JTASessionContext</literal> - les sessions courantes sont
                    associ<63>es <20> une transaction <literal>JTA</literal>.  La logique est la m<>me que
                    l'ancienne approche bas<61>e sur JTA. Voir les javadocs pour les d<>tails.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>org.hibernate.context.ThreadLocalSessionContext</literal> - les sessions
                    courantes sont associ<63>es au thread d'ex<65>cution. Voir les javadocs pour les d<>tails.
                </para>
            </listitem>
			<listitem>
                <para>
                    <literal>org.hibernate.context.ManagedSessionContext</literal> - les sessions
                    courantes sont traqu<71>es par l'ex<65>cution du thread. Toutefois, vous <20>tes responsable
                    de lier et d<>lier une instance de <literal>Session</literal> avec les m<>thodes
                    statiques de cette classes, qui n'ouvre, ne flush ou ne ferme jamais de <literal>Session</literal>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Les deux impl<70>mentations fournissent un mod<6F>le de programmation de type "une session - une transaction
            <20> la base de donn<6E>es", aussi connu sous le nom de <emphasis>session-per-request</emphasis>. 
            Le d<>but et la fin d'une session Hibernate sont d<>finis par la dur<75>e d'une transaction de base de donn<6E>es.
            Si vous utilisez une d<>marcation programmatique de la transaction (par exemple sous J2SE ou JTA/UserTransaction/BMT),
            nous vous conseillons d'utiliser l'API Hibernate <literal>Transaction</literal> pour masquer le syst<73>me
            de transaction utilis<69>. Si vous ex<65>cutez sous un conteneur EJB qui supporte CMT, vous n'avez besoin d'aucune
            op<6F>rations de d<>marcations de session ou transaction dans votre code puisque tout
            est g<>r<EFBFBD> de mani<6E>re d<>clarative. R<>f<EFBFBD>rez vous <20> <xref linkend="transactions"/> pour plus d'informations
            et des exemples de code.
        </para>

        <para>
            Le param<61>tre de configuration <literal>hibernate.current_session_context_class</literal> 
            d<>finit quelle impl<70>mentation de <literal>org.hibernate.context.CurrentSessionContext</literal> 
            doit <20>tre utilis<69>e. Notez que pour assurer la compatibilit<69> avec les versions pr<70>c<EFBFBD>dentes, si
            ce param<61>tre n'est pas d<>fini mais qu'un <literal>org.hibernate.transaction.TransactionManagerLookup</literal> 
            est configur<75>, Hibernate utilisera le <literal>org.hibernate.context.JTASessionContext</literal>.
            La valeur de ce param<61>tre devrait juste nommer la classe d'impl<70>mentation <20> utiliser, 
            pour les deux impl<70>mentations fournies, il y a cependant deux alias correspondant: "jta" et "thread".
        </para>
        
    </sect1>

</chapter>