|
| 1 | +<?xml version='1.0' encoding="UTF-8"?> |
| 2 | + |
| 3 | +<!-- |
| 4 | + ~ Hibernate, Relational Persistence for Idiomatic Java |
| 5 | + ~ |
| 6 | + ~ License: GNU Lesser General Public License (LGPL), version 2.1 or later. |
| 7 | + ~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>. |
| 8 | + --> |
| 9 | +<chapter xml:id="architecture" xmlns="http://docbook.org/ns/docbook"> |
| 10 | + |
| 11 | + <title>Architecture</title> |
| 12 | + |
| 13 | + <section xml:id="architecture-overview"> |
| 14 | + <title>Overview</title> |
| 15 | + |
| 16 | + <mediaobject> |
| 17 | + <imageobject role="fo"> |
| 18 | + <imagedata fileref="images/overview.svg" format="SVG" align="center"/> |
| 19 | + </imageobject> |
| 20 | + <imageobject role="html"> |
| 21 | + <imagedata fileref="images/overview.png" format="PNG" align="center"/> |
| 22 | + </imageobject> |
| 23 | + </mediaobject> |
| 24 | + |
| 25 | + <para> |
| 26 | + Hibernate, as an ORM solution, effectively "sits between" the Java application and the Relational |
| 27 | + Database, as can be seen in the diagram above. The Java application makes use of the Hibernate APIs |
| 28 | + to load, store, query, etc its domain data. Here we will introduce the essential Hibernate APIs. |
| 29 | + This will be a brief introduction; we will discuss these contracts in detail later. |
| 30 | + |
| 31 | + <variablelist spacing="compact"> |
| 32 | + <varlistentry> |
| 33 | + <term>SessionFactory (<interfacename>org.hibernate.SessionFactory</interfacename>)</term> |
| 34 | + <listitem> |
| 35 | + <para> |
| 36 | + A thread-safe (and immutable) representation of the mapping of the application |
| 37 | + domain model to a database. Acts as a factory for |
| 38 | + <interfacename>org.hibernate.Session</interfacename> instances. |
| 39 | + </para> |
| 40 | + <para> |
| 41 | + A SessionFactory is very expensive to create; there should be only |
| 42 | + one SessionFactory for an application for a given database. Maintains |
| 43 | + services that Hibernate uses across all Sessions such as second level caches, |
| 44 | + connection pools, transaction system integrations, etc. |
| 45 | + </para> |
| 46 | + </listitem> |
| 47 | + </varlistentry> |
| 48 | + <varlistentry> |
| 49 | + <term>Session (<interfacename>org.hibernate.Session</interfacename>)</term> |
| 50 | + <listitem> |
| 51 | + <para> |
| 52 | + A single-threaded, short-lived object conceptually modeling a |
| 53 | + "Unit of Work"<citation>PoEAA</citation>. |
| 54 | + </para> |
| 55 | + <para> |
| 56 | + Wraps a JDBC <interfacename>java.sql.Connection</interfacename>. Acts as a factory for |
| 57 | + <interfacename>org.hibernate.Transaction</interfacename> instances. Maintains a |
| 58 | + generally "repeatable read" persistence context (first level cache) of the application's |
| 59 | + domain model. |
| 60 | + </para> |
| 61 | + </listitem> |
| 62 | + </varlistentry> |
| 63 | + <varlistentry> |
| 64 | + <term>Transaction (<interfacename>org.hibernate.Transaction</interfacename>)</term> |
| 65 | + <listitem> |
| 66 | + <para> |
| 67 | + A single-threaded, short-lived object used by the application to demarcate individual |
| 68 | + physical transaction boundaries. It acts as an abstraction API to isolate the application |
| 69 | + from the underling transaction system in use (JDBC, JTA, CORBA, etc). |
| 70 | + </para> |
| 71 | + </listitem> |
| 72 | + </varlistentry> |
| 73 | + </variablelist> |
| 74 | + </para> |
| 75 | + </section> |
| 76 | + |
| 77 | + <section xml:id="architecture-current-session" revision="2"> |
| 78 | + <title>Contextual sessions</title> |
| 79 | + <para> |
| 80 | + Most applications using Hibernate need some form of "contextual" session, where a given |
| 81 | + session is in effect throughout the scope of a given context. However, across applications |
| 82 | + the definition of what constitutes a context is typically different; different contexts |
| 83 | + define different scopes to the notion of current. Applications using Hibernate prior |
| 84 | + to version 3.0 tended to utilize either home-grown <literal>ThreadLocal</literal>-based |
| 85 | + contextual sessions, helper classes such as <literal>HibernateUtil</literal>, or utilized |
| 86 | + third-party frameworks, such as Spring or Pico, which provided proxy/interception-based contextual sessions. |
| 87 | + </para> |
| 88 | + <para> |
| 89 | + Starting with version 3.0.1, Hibernate added the <literal>SessionFactory.getCurrentSession()</literal> |
| 90 | + method. Initially, this assumed usage of <literal>JTA</literal> transactions, where the |
| 91 | + <literal>JTA</literal> transaction defined both the scope and context of a current session. |
| 92 | + Given the maturity of the numerous stand-alone |
| 93 | + <literal>JTA TransactionManager</literal> implementations, most, if not all, |
| 94 | + applications should be using <literal>JTA</literal> transaction management, whether or not |
| 95 | + they are deployed into a <literal>J2EE</literal> container. Based on that, the |
| 96 | + <literal>JTA</literal>-based contextual sessions are all you need to use. |
| 97 | + </para> |
| 98 | + <para> |
| 99 | + However, as of version 3.1, the processing behind |
| 100 | + <literal>SessionFactory.getCurrentSession()</literal> is now pluggable. To that |
| 101 | + end, a new extension interface, <literal>org.hibernate.context.spi.CurrentSessionContext</literal>, |
| 102 | + and a new configuration parameter, <literal>hibernate.current_session_context_class</literal>, |
| 103 | + have been added to allow pluggability of the scope and context of defining current sessions. |
| 104 | + </para> |
| 105 | + <para> |
| 106 | + See the Javadocs for the <literal>org.hibernate.context.spi.CurrentSessionContext</literal> |
| 107 | + interface for a detailed discussion of its contract. It defines a single method, |
| 108 | + <literal>currentSession()</literal>, by which the implementation is responsible for |
| 109 | + tracking the current contextual session. Out-of-the-box, Hibernate comes with three |
| 110 | + implementations of this interface: |
| 111 | + </para> |
| 112 | + |
| 113 | + <itemizedlist> |
| 114 | + <listitem> |
| 115 | + <para> |
| 116 | + <literal>org.hibernate.context.internal.JTASessionContext</literal>: current sessions |
| 117 | + are tracked and scoped by a <literal>JTA</literal> transaction. The processing |
| 118 | + here is exactly the same as in the older JTA-only approach. See the Javadocs |
| 119 | + for details. |
| 120 | + </para> |
| 121 | + </listitem> |
| 122 | + <listitem> |
| 123 | + <para> |
| 124 | + <literal>org.hibernate.context.internal.ThreadLocalSessionContext</literal>:current |
| 125 | + sessions are tracked by thread of execution. See the Javadocs for details. |
| 126 | + </para> |
| 127 | + </listitem> |
| 128 | + <listitem> |
| 129 | + <para> |
| 130 | + <literal>org.hibernate.context.internal.ManagedSessionContext</literal>: current |
| 131 | + sessions are tracked by thread of execution. However, you are responsible to |
| 132 | + bind and unbind a <literal>Session</literal> instance with static methods |
| 133 | + on this class: it does not open, flush, or close a <literal>Session</literal>. |
| 134 | + </para> |
| 135 | + </listitem> |
| 136 | + </itemizedlist> |
| 137 | + |
| 138 | + <para> |
| 139 | + Typically, the value of this parameter would just name the implementation class to |
| 140 | + use. For the three out-of-the-box implementations, however, there are three corresponding |
| 141 | + short names: "jta", "thread", and "managed". |
| 142 | + </para> |
| 143 | + |
| 144 | + <para> |
| 145 | + The first two implementations provide a "one session - one database transaction" programming |
| 146 | + model. This is also known and used as <emphasis>session-per-request</emphasis>. The beginning |
| 147 | + and end of a Hibernate session is defined by the duration of a database transaction. |
| 148 | + If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to |
| 149 | + use the Hibernate <literal>Transaction</literal> API to hide the underlying transaction system |
| 150 | + from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you |
| 151 | + execute in an EJB container that supports CMT, transaction boundaries are defined declaratively |
| 152 | + and you do not need any transaction or session demarcation operations in your code. |
| 153 | + Refer to <xref linkend="transactions"/> for more information and code examples. |
| 154 | + </para> |
| 155 | + |
| 156 | + <para> |
| 157 | + The <literal>hibernate.current_session_context_class</literal> configuration parameter |
| 158 | + defines which <literal>org.hibernate.context.spi.CurrentSessionContext</literal> implementation |
| 159 | + should be used. For backwards compatibility, if this configuration parameter is not set |
| 160 | + but a <literal>org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform</literal> is configured, |
| 161 | + Hibernate will use the <literal>org.hibernate.context.internal.JTASessionContext</literal>. |
| 162 | + </para> |
| 163 | + |
| 164 | + </section> |
| 165 | + |
| 166 | +</chapter> |
| 167 | + |
0 commit comments