245 lines
11 KiB
XML
245 lines
11 KiB
XML
<chapter id="architecture">
|
|
|
|
<title>Architecture</title>
|
|
|
|
<sect1 id="architecture-overview" revision="1">
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
A (very) high-level view of the Hibernate architecture:
|
|
</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>
|
|
This diagram shows Hibernate using the database and configuration data to
|
|
provide persistence services (and persistent objects) to the application.
|
|
</para>
|
|
|
|
<para>
|
|
We would like to show a more detailed view of the runtime architecture.
|
|
Unfortunately, Hibernate is flexible and supports several approaches. We will
|
|
show the two extremes. The "lite" architecture has the application
|
|
provide its own JDBC connections and manage its own transactions. This approach
|
|
uses a minimal subset of Hibernate's APIs:
|
|
</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>
|
|
The "full cream" architecture abstracts the application away from the
|
|
underlying JDBC/JTA APIs and lets Hibernate take care of the details.
|
|
</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>
|
|
Heres some definitions of the objects in the diagrams:
|
|
|
|
<variablelist spacing="compact">
|
|
<varlistentry>
|
|
<term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term>
|
|
<listitem>
|
|
<para>
|
|
A threadsafe (immutable) cache of compiled mappings for a single database.
|
|
A factory for <literal>Session</literal> and a client of
|
|
<literal>ConnectionProvider</literal>. Might hold an optional (second-level)
|
|
cache of data that is reusable between transactions, at a
|
|
process- or cluster-level.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Session (<literal>org.hibernate.Session</literal>)</term>
|
|
<listitem>
|
|
<para>
|
|
A single-threaded, short-lived object representing a conversation between
|
|
the application and the persistent store. Wraps a JDBC connection. Factory
|
|
for <literal>Transaction</literal>. Holds a mandatory (first-level) cache
|
|
of persistent objects, used when navigating the object graph or looking up
|
|
objects by identifier.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Persistent objects and collections</term>
|
|
<listitem>
|
|
<para>
|
|
Short-lived, single threaded objects containing persistent state and business
|
|
function. These might be ordinary JavaBeans/POJOs, the only special thing about
|
|
them is that they are currently associated with (exactly one)
|
|
<literal>Session</literal>. As soon as the <literal>Session</literal> is closed,
|
|
they will be detached and free to use in any application layer (e.g. directly
|
|
as data transfer objects to and from presentation).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Transient and detached objects and collections</term>
|
|
<listitem>
|
|
<para>
|
|
Instances of persistent classes that are not currently associated with a
|
|
<literal>Session</literal>. They may have been instantiated by
|
|
the application and not (yet) persisted or they may have been instantiated by a
|
|
closed <literal>Session</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Transaction (<literal>org.hibernate.Transaction</literal>)</term>
|
|
<listitem>
|
|
<para>
|
|
(Optional) A single-threaded, short-lived object used by the application to
|
|
specify atomic units of work. Abstracts application from underlying JDBC,
|
|
JTA or CORBA transaction. A <literal>Session</literal> might span several
|
|
<literal>Transaction</literal>s in some cases. However, transaction demarcation,
|
|
either using the underlying API or <literal>Transaction</literal>, is never
|
|
optional!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term>
|
|
<listitem>
|
|
<para>
|
|
(Optional) A factory for (and pool of) JDBC connections. Abstracts application from
|
|
underlying <literal>Datasource</literal> or <literal>DriverManager</literal>.
|
|
Not exposed to application, but can be extended/implemented by the developer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term>
|
|
<listitem>
|
|
<para>
|
|
(Optional) A factory for <literal>Transaction</literal> instances. Not exposed to the
|
|
application, but can be extended/implemented by the developer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><emphasis>Extension Interfaces</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Hibernate offers many optional extension interfaces you can implement to customize
|
|
the behavior of your persistence layer. See the API documentation for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Given a "lite" architecture, the application bypasses the
|
|
<literal>Transaction</literal>/<literal>TransactionFactory</literal> and/or
|
|
<literal>ConnectionProvider</literal> APIs to talk to JTA or JDBC directly.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="architecture-states" revision="1">
|
|
<title>Instance states</title>
|
|
<para>
|
|
An instance of a persistent classes may be in one of three different states,
|
|
which are defined with respect to a <emphasis>persistence context</emphasis>.
|
|
The Hibernate <literal>Session</literal> object is the persistence context:
|
|
</para>
|
|
|
|
<variablelist spacing="compact">
|
|
<varlistentry>
|
|
<term>transient</term>
|
|
<listitem>
|
|
<para>
|
|
The instance is not, and has never been associated with
|
|
any persistence context. It has no persistent identity
|
|
(primary key value).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>persistent</term>
|
|
<listitem>
|
|
<para>
|
|
The instance is currently associated with a persistence
|
|
context. It has a persistent identity (primary key value)
|
|
and, perhaps, a corresponding row in the database. For a
|
|
particular persistence context, Hibernate
|
|
<emphasis>guarantees</emphasis> that persistent identity
|
|
is equivalent to Java identity.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>detached</term>
|
|
<listitem>
|
|
<para>
|
|
The instance is was once associated with a persistence
|
|
context, but that context was closed, or the instance
|
|
was serialized to another process. It has a persistent
|
|
identity and, perhaps, a corrsponding row in the database.
|
|
For detached instances, Hibernate makes no guarantees
|
|
about the relationship between persistent identity and
|
|
Java identity.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="architecture-jmx" revision="1">
|
|
<title>JMX Integration</title>
|
|
|
|
<para>
|
|
JMX is the J2EE standard for management of Java components. Hibernate may be managed via
|
|
a JMX standard MBean but because most application servers do not yet support JMX, Hibernate
|
|
also affords some non-standard configuration mechanisms.
|
|
</para>
|
|
|
|
<para>
|
|
Please see the Hibernate website for more information on how to configure Hibernate to
|
|
run as a JMX component inside JBoss. Integration with other JMX containers is also
|
|
possible.
|
|
</para>
|
|
|
|
<!-- TODO: More documentation about JMX integration. -->
|
|
<para>
|
|
TODO: More documentation about JMX integration.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="architecture-jca">
|
|
<title>JCA Support</title>
|
|
<para>
|
|
Hibernate may also be configured as a JCA connector. Please see the website for more
|
|
details.
|
|
</para>
|
|
|
|
<!-- TODO: More documentation about JCA integration. -->
|
|
<para>
|
|
TODO: More documentation about JCA integration.
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|