Hibernate example source code file (events.xml)

This example Hibernate source code file (events.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, cdata, cdata, hibernate, hibernate, io, java, java, object, serializable, this, type, util, xml, xml, you

The Hibernate events.xml source code

<?xml version='1.0' encoding="UTF-8"?>
<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
  ~
  ~ 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" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent">
%BOOK_ENTITIES;

]>

<chapter id="events">
    <title>Interceptors and events

    <para>
        It is useful for the application to react to certain events that occur
        inside Hibernate. This allows for the implementation of generic 
        functionality and the extension of Hibernate functionality.
    </para>

    <section id="objectstate-interceptors" revision="3">
        <title>Interceptors

        <para>
            The <literal>Interceptor interface provides callbacks from the session to the 
            application, allowing the application to inspect and/or manipulate properties of a
            persistent object before it is saved, updated, deleted or loaded. One 
            possible use for this is to track auditing information. For example, the following 
            <literal>Interceptor automatically sets the  createTimestamp 
            when an <literal>Auditable is created and updates the 
            <literal>lastUpdateTimestamp property when an Auditable is 
            updated.
        </para>

        <para>
            You can either implement <literal>Interceptor directly or extend
            <literal>EmptyInterceptor.
        </para>

        <programlisting role="JAVA">

        <para>
            There are two kinds of inteceptors: <literal>Session-scoped and
            <literal>SessionFactory-scoped.
        </para>

        <para>
            A <literal>Session-scoped interceptor is specified
            when a session is opened using one of the overloaded SessionFactory.openSession()
            methods accepting an <literal>Interceptor.
        </para>

        <programlisting role="JAVA">

        <para>
            A <literal>SessionFactory-scoped interceptor is registered with the Configuration
            object prior to building the <literal>SessionFactory.  Unless
            a session is opened explicitly specifying the interceptor to use, the supplied interceptor
            will be applied to all sessions opened from that <literal>SessionFactory.  SessionFactory-scoped
            interceptors must be thread safe. Ensure that you do not store session-specific states, since multiple
            sessions will use this interceptor potentially concurrently.
        </para>
    
        <programlisting role="JAVA">

    </section>

     <section id="objectstate-events" revision="4">
        <title>Event system

        <para>
            If you have to react to particular events in your persistence layer, you can
            also use the Hibernate3 <emphasis>event architecture. The event
            system can be used in addition, or as a replacement, for interceptors.
        </para>

        <para>
            All the methods of the <literal>Session interface correlate
            to an event. You have a <literal>LoadEvent, a FlushEvent, etc.
            Consult the XML configuration-file DTD or the <literal>org.hibernate.event
            package for the full list of defined event types. When a request is made of one of
            these methods, the Hibernate <literal>Session generates an appropriate
            event and passes it to the configured event listeners for that type. Out-of-the-box,
            these listeners implement the same processing in which those methods always resulted.
            However, you are free to implement a customization of one of the listener interfaces
            (i.e., the <literal>LoadEvent is processed by the registered implementation
            of the <literal>LoadEventListener interface), in which case their
            implementation would be responsible for processing any <literal>load() requests
            made of the <literal>Session.
        </para>

        <para>
            The listeners should be considered singletons. This means they are shared between
            requests, and should not save any state as instance variables.
        </para>

        <para>
            A custom listener implements the appropriate interface for the event it wants to
            process and/or extend one of the convenience base classes (or even the default event
            listeners used by Hibernate out-of-the-box as these are declared non-final for this
            purpose). Custom listeners can either be registered programmatically through the
            <literal>Configuration object, or specified in the Hibernate configuration
            XML. Declarative configuration through the properties file is not supported. Here is an
            example of a custom load event listener:
        </para>

        <programlisting role="JAVA">

        <para>
            You also need a configuration entry telling Hibernate to use the listener in addition
            to the default listener:
        </para>

<programlisting role="XML">
    <session-factory>
        ...
        <event type="load">
            <listener class="com.eg.MyLoadListener"/>
            <listener class="org.hibernate.event.def.DefaultLoadEventListener"/>
        </event>
    </session-factory>
</hibernate-configuration>]]>

        <para>
            Instead, you can register it programmatically:
        </para>

        <programlisting role="JAVA">

        <para>
            Listeners registered declaratively cannot share instances. If the same class name is
            used in multiple <literal><listener/> elements, each reference will
            result in a separate instance of that class. If you need to share
            listener instances between listener types you must use the programmatic registration
            approach.
        </para>

        <para>
            Why implement an interface and define the specific type during configuration? A
            listener implementation could implement multiple event listener interfaces. Having the
            type additionally defined during registration makes it easier to turn custom listeners on
            or off during configuration.
        </para>

    </section>
    
    <section id="objectstate-decl-security" revision="2">
        <title>Hibernate declarative security
        <para>
            Usually, declarative security in Hibernate applications is managed in a session facade
            layer. Hibernate3 allows certain actions to be permissioned via JACC, and authorized 
            via JAAS. This is an optional functionality that is built on top of the event architecture.
        </para>
        
        <para>
            First, you must configure the appropriate event listeners, to enable the use of JAAS
            authorization.
        </para>
        
        <programlisting role="XML">
<listener type="pre-update" class="org.hibernate.secure.internal.JACCPreUpdateEventListener"/>
<listener type="pre-insert" class="org.hibernate.secure.internal.JACCPreInsertEventListener"/>
<listener type="pre-load" class="org.hibernate.secure.internal.JACCPreLoadEventListener"/>]]>

        <para>
            Note that <literal><listener type="..." class="..."/> is shorthand
            for <literal><event type="..."><listener class="..."/></event>
            when there is exactly one listener for a particular event type.
        </para>

        <para>
            Next, while still in <literal>hibernate.cfg.xml, bind the permissions to roles:
        </para>
        
        <programlisting role="XML">
<grant role="su" entity-name="User" actions="*"/>]]>
        
        <para>
            The role names are the roles understood by your JACC provider.
        </para>
       
    </section>

</chapter>