Hibernate example source code file (architecture.xml)

This example Hibernate source code file (architecture.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

a, api, for, hibernate, in, in, java, java, jta, jta, se, the, this, this

The Hibernate architecture.xml source code

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ Copyright (c) 2010, Red Hat Inc or third-party contributors as
  ~ indicated by the @author tags or express copyright attribution
  ~ statements applied by the authors.  All third-party contributions are
  ~ distributed under license by Red Hat Inc.
  ~
  ~ This copyrighted material is made available to anyone wishing to use, modify,
  ~ copy, or redistribute it subject to the terms and conditions of the GNU
  ~ Lesser General Public License, as published by the Free Software Foundation.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="architecture">
  <title>Architecture

  <section>
    <title>Definitions

    <para>JPA 2 is part of the Java EE 6.0 platform. Persistence in JPA is
    available in containers like EJB 3 or the more modern CDI (Java Context
    and Dependency Injection), as well as in standalone Java SE applications
    that execute outside of a particular container. The following programming
    interfaces and artifacts are available in both environments.</para>

    <variablelist spacing="compact">
      <varlistentry>
        <term>EntityManagerFactory

        <listitem>
          <para>An entity manager factory provides entity manager instances,
          all instances are configured to connect to the same database, to use
          the same default settings as defined by the particular
          implementation, etc. You can prepare several entity manager
          factories to access several data stores. This interface is similar
          to the <literal>SessionFactory in native Hibernate.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>EntityManager

        <listitem>
          <para>The EntityManager API is used to access a
          database in a particular unit of work. It is used to create and
          remove persistent entity instances, to find entities by their
          primary key identity, and to query over all entities. This interface
          is similar to the <literal>Session in Hibernate.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Persistence context

        <listitem>
          <para>A persistence context is a set of entity instances in which
          for any persistent entity identity there is a unique entity
          instance. Within the persistence context, the entity instances and
          their lifecycle is managed by a particular entity manager. The scope
          of this context can either be the transaction, or an extended unit
          of work.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Persistence unit

        <listitem>
          <para>The set of entity types that can be managed by a given entity
          manager is defined by a persistence unit. A persistence unit defines
          the set of all classes that are related or grouped by the
          application, and which must be collocated in their mapping to a
          single data store.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Container-managed entity manager

        <listitem>
          <para>An Entity Manager whose lifecycle is managed by the
          container</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Application-managed entity manager

        <listitem>
          <para>An Entity Manager whose lifecycle is managed by the
          application.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>JTA entity manager

        <listitem>
          <para>Entity manager involved in a JTA transaction
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Resource-local entity manager

        <listitem>
          <para>Entity manager using a resource transaction (not a JTA
          transaction).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>In container environment (eg. EJB 3)

    <section>
      <title>Container-managed entity manager

      <para>The most common and widely used entity manager in a Java EE
      environment is the container-managed entity manager. In this mode, the
      container is responsible for the opening and closing of the entity
      manager (this is transparent to the application). It is also responsible
      for transaction boundaries. A container-managed entity manager is
      obtained in an application through dependency injection or through JNDI
      lookup, A container-managed entity manger requires the use of a JTA
      transaction.</para>
    </section>

    <section>
      <title>Application-managed entity manager

      <para>An application-managed entity manager allows you to control the
      entity manager in application code. This entity manager is retrieved
      through the <literal>EntityManagerFactory API. An application
      managed entity manager can be either involved in the current JTA
      transaction (a JTA entity manager), or the transaction may be controlled
      through the <literal>EntityTransaction API (a resource-local
      entity manager). The resource-local entity manager transaction maps to a
      direct resource transaction (i. e. in Hibernate's case a JDBC
      transaction). The entity manager type (JTA or resource-local) is defined
      at configuration time, when setting up the entity manager
      factory.</para>
    </section>

    <section id="architecture-ejb-persistctxscope">
      <title>Persistence context scope

      <para>An entity manager is the API to interact with the persistence
      context. Two common strategies can be used: binding the persistence
      context to the transaction boundaries, or keeping the persistence
      context available across several transactions.</para>

      <para>The most common case is to bind the persistence context scope to
      the current transaction scope. This is only doable when JTA transactions
      are used: the persistence context is associated with the JTA transaction
      life cycle. When an entity manager is invoked, the persistence context
      is also opened, if there is no persistence context associated with the
      current JTA transaction. Otherwise, the associated persistence context
      is used. The persistence context ends when the JTA transaction
      completes. This means that during the JTA transaction, an application
      will be able to work on managed entities of the same persistence
      context. In other words, you don't have to pass the entity manager's
      persistence context across your managed beans (CDI) or EJBs method
      calls, but simply use dependency injection or lookup whenever you need
      an entity manager.</para>

      <para>You can also use an extended persistence context. This can be
      combined with stateful session beans, if you use a container-managed
      entity manager: the persistence context is created when an entity
      manager is retrieved from dependency injection or JNDI lookup , and is
      kept until the container closes it after the completion of the
      <literal>Remove stateful session bean method. This is a
      perfect mechanism for implementing a "long" unit of work pattern. For
      example, if you have to deal with multiple user interaction cycles as a
      single unit of work (e.g. a wizard dialog that has to be fully
      completed), you usually model this as a unit of work from the point of
      view of the application user, and implement it using an extended
      persistence context. Please refer to the Hibernate reference manual or
      the book Hibernate In Action for more information about this pattern.
      </para>

      <para>JBoss Seam 3 is built on top of CDI and has at it's core concept
      the notion of conversation and unit of work. For an application-managed
      entity manager the persistence context is created when the entity
      manager is created and kept until the entity manager is closed. In an
      extended persistence context, all modification operations (persist,
      merge, remove) executed outside a transaction are queued until the
      persistence context is attached to a transaction. The transaction
      typically occurs at the user process end, allowing the whole process to
      be committed or rollbacked. For application-managed entity manager only
      support the extended persistence context.</para>

      <para>A resource-local entity manager or an entity manager created with
      <literal>EntityManagerFactory.createEntityManager()
      (application-managed) has a one-to-one relationship with a persistence
      context. In other situations <emphasis>persistence context
      propagation</emphasis> occurs.
    </section>

    <section id="architecture-ejb-persistctxpropagation">
      <title>Persistence context propagation

      <para>Persistence context propagation occurs for container-managed
      entity managers.</para>

      <para>In a transaction-scoped container managed entity manager (common
      case in a Java EE environment), the JTA transaction propagation is the
      same as the persistence context resource propagation. In other words,
      container-managed transaction-scoped entity managers retrieved within a
      given JTA transaction all share the same persistence context. In
      Hibernate terms, this means all managers share the same session.</para>

      <para>Important: persistence context are never shared between different
      JTA transactions or between entity manager that do not came from the
      same entity manager factory. There are some noteworthy exceptions for
      context propagation when using extended persistence contexts:</para>

      <itemizedlist>
        <listitem>
          <para>If a stateless session bean, message-driven bean, or stateful
          session bean with a transaction-scoped persistence context calls a
          stateful session bean with an extended persistence context in the
          same JTA transaction, an
          <classname>IllegalStateException is thrown.
        </listitem>

        <listitem>
          <para>If a stateful session bean with an extended persistence
          context calls as stateless session bean or a stateful session bean
          with a transaction-scoped persistence context in the same JTA
          transaction, the persistence context is propagated.</para>
        </listitem>

        <listitem>
          <para>If a stateful session bean with an extended persistence
          context calls a stateless or stateful session bean in a different
          JTA transaction context, the persistence context is not
          propagated.</para>
        </listitem>

        <listitem>
          <para>If a stateful session bean with an extended persistence
          context instantiates another stateful session bean with an extended
          persistence context, the extended persistence context is inherited
          by the second stateful session bean. If the second stateful session
          bean is called with a different transaction context than the first,
          an IllegalStateException is thrown.</para>
        </listitem>

        <listitem>
          <para>If a stateful session bean with an extended persistence
          context calls a stateful session bean with a different extended
          persistence context in the same transaction, an
          <classname>IllegalStateException is thrown.
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="architecture-javase" revision="1">
    <title>Java SE environments

    <para>In a Java SE environment only extended context application-managed
    entity managers are available. You can retrieve an entity manger using the
    <literal>EntityManagerFactory API. Only resource-local entity
    managers are available. In other words, JTA transactions and persistence
    context propagation are not supported in Java SE (you will have to
    propagate the persistence context yourself, e.g. using the thread local
    session pattern popular in the Hibernate community).</para>

    <para>Extended context means that a persistence context is created when
    the entity manager is retrieved (using
    <literal>EntityManagerFactory.createEntityManager(...) ) and
    closed when the entity manager is closed. Many resource-local transaction
    share the same persistence context, in this case.</para>
  </section>
</chapter>