1526 lines
64 KiB
XML
1526 lines
64 KiB
XML
<chapter id="objectstate">
|
|
<title>Working with objects</title>
|
|
|
|
<para>
|
|
Hibernate is a full object/relational mapping solution that not only shields
|
|
the developer from the details of the underlying database management
|
|
system, but also offers <emphasis>state management</emphasis> of objects. This is,
|
|
contrary to the management of SQL <literal>statements</literal> in common JDBC/SQL
|
|
persistence layers, a very natural object-oriented view of persistence in Java
|
|
applications.
|
|
</para>
|
|
|
|
<para>
|
|
In other words, Hibernate application developers should always think about the
|
|
<emphasis>state</emphasis> of their objects, and not necessarily about the
|
|
execution of SQL statements. This part is taken care of by Hibernate and is only
|
|
relevant for the application developer when tuning the performance of the system.
|
|
</para>
|
|
|
|
<sect1 id="objectstate-overview">
|
|
<title>Hibernate object states</title>
|
|
|
|
<para>
|
|
Hibernate defines and supports the following object states:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Transient</emphasis> - an object is transient if it has just
|
|
been instantiated using the <literal>new</literal> operator, and it
|
|
is not associated with a Hibernate <literal>Session</literal>. It has no
|
|
persistent representation in the database and no identifier value has been
|
|
assigned. Transient instances will be destroyed by the garbage collector of
|
|
the application doesn't hold a reference anymore. Use the Hibernate
|
|
<literal>Session</literal> to make an object persisent (and let Hibernate
|
|
take care of the SQL statements that need to be executed for this transition).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Persistent</emphasis> - a persistent instance has a representation
|
|
in the database and an identifier value. It might just have been saved or loaded,
|
|
however, it is by definition in the scope of a <literal>Session</literal>.
|
|
Hibernate will detect any changes made to an object in persistent state and
|
|
synchronize the state with the database when the unit of work completes.
|
|
Developers don't execute manual <literal>UPDATE</literal> statements, or
|
|
<literal>DELETE</literal> statements when an object should be made transient.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Detached</emphasis> - a detached instance is an object that has been
|
|
persistent, but its <literal>Session</literal> has been closed. The reference
|
|
to the object is still valid, of course, and the detached instance might even
|
|
be modified in this state. A detached instance can be reattached to a new
|
|
<literal>Session</literal> at a later point in time, making it (and all the
|
|
modifications) persistent again. This feature enables a programming model for
|
|
long running units of work that require user think-time. We call them
|
|
<emphasis>application transactions</emphasis>, i.e. a unit of work from the
|
|
point of view of the user.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
We'll know discuss the states and state transitions (and the Hibernate methods that
|
|
trigger a transition) in more detail.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-makingpersistent" revision="1">
|
|
<title>Making objects persistent</title>
|
|
|
|
<para>
|
|
Newly instantiated instances of a a persistent class are considered
|
|
<emphasis>transient</emphasis> by Hibernate. We can make a transient
|
|
instance <emphasis>persistent</emphasis> by associating it with a
|
|
session:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DomesticCat fritz = new DomesticCat();
|
|
fritz.setColor(Color.GINGER);
|
|
fritz.setSex('M');
|
|
fritz.setName("Fritz");
|
|
Long generatedId = (Long) sess.save(fritz);]]></programlisting>
|
|
|
|
<para>
|
|
If <literal>Cat</literal> has a generated identifier, the identifier is
|
|
generated and assigned to the <literal>cat</literal> when <literal>save()</literal>
|
|
is called. If <literal>Cat</literal> has an <literal>assigned</literal>
|
|
identifier, or a composite key, the identifier should be assigned to
|
|
the <literal>cat</literal> instance before calling <literal>save()</literal>.
|
|
You may also use <literal>create()</literal> instead of <literal>save()</literal>,
|
|
with the semantics defined in the EJB3 early draft.
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, you may assign the identifier using an overloaded version
|
|
of <literal>save()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DomesticCat pk = new DomesticCat();
|
|
pk.setColor(Color.TABBY);
|
|
pk.setSex('F');
|
|
pk.setName("PK");
|
|
pk.setKittens( new HashSet() );
|
|
pk.addKitten(fritz);
|
|
sess.save( pk, new Long(1234) );]]></programlisting>
|
|
|
|
<para>
|
|
If the object you make persistent has associated objects (e.g. the
|
|
<literal>kittens</literal> collection role) in the previous example),
|
|
these objects may be made persistent in any order you like unless you
|
|
have a <literal>NOT NULL</literal> constraint upon a foreign key column.
|
|
There is never a risk of violating foreign key constraints. However, you
|
|
might violate a <literal>NOT NULL</literal> constraint if you
|
|
<literal>save()</literal> the objects in the wrong order.
|
|
</para>
|
|
|
|
<para>
|
|
Usually you don't bother with this detail, as you'd very likely use Hibernate's
|
|
<emphasis>transitive persistence</emphasis> feature to save the associated
|
|
objects automatically. Then, <literal>NOT NULL</literal>
|
|
constraint violations are impossible - Hibernate will take care of everything.
|
|
Transitive persistence is discussed later in this chapter.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-loading">
|
|
<title>Loading an object</title>
|
|
|
|
<para>
|
|
The <literal>load()</literal> methods of <literal>Session</literal> gives you
|
|
a way to retrieve a persistent instance if you already know its identifier.
|
|
<literal>load()</literal> takes a class object and will load the state into
|
|
a newly instantiated instance of that class, in persistent state.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat fritz = (Cat) sess.load(Cat.class, generatedId);]]></programlisting>
|
|
|
|
<programlisting><![CDATA[// you need to wrap primitive identifiers
|
|
long pkId = 1234;
|
|
DomesticCat pk = (DomesticCat) sess.load( Cat.class, new Long(pkId) );]]></programlisting>
|
|
|
|
<para>
|
|
Alternatively, you can load state into a given instance:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat cat = new DomesticCat();
|
|
// load pk's state into cat
|
|
sess.load( cat, new Long(pkId) );
|
|
Set kittens = cat.getKittens();]]></programlisting>
|
|
|
|
<para>
|
|
Note that <literal>load()</literal> will throw an unrecoverable exception if
|
|
there is no matching database row. If the class is mapped with a proxy,
|
|
<literal>load()</literal> just returns an uninitialized proxy and does not
|
|
actually hit the database until you invoke a method of the proxy. This
|
|
behaviour is very useful if you wish to create an association to an object
|
|
without actually loading it from the database. It also allows multiple
|
|
instances to be loaded as a batch if <literal>batch-size</literal> is
|
|
defined for the class mapping.
|
|
</para>
|
|
|
|
<para>
|
|
If you are not certain that a matching row exists, you should use the
|
|
<literal>get()</literal> method, which hits the database immediately and
|
|
returns null if there is no matching row.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id);
|
|
if (cat==null) {
|
|
cat = new Cat();
|
|
sess.save(cat, id);
|
|
}
|
|
return cat;]]></programlisting>
|
|
|
|
<para>
|
|
You may even load an object using an SQL <literal>SELECT ... FOR UPDATE</literal>,
|
|
using a <literal>LockMode</literal>. See the API documentation for more information.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);]]></programlisting>
|
|
|
|
<para>
|
|
Note that any associated instances or contained collections are
|
|
<emphasis>not</emphasis> selected <literal>FOR UPDATE</literal>, unless you decide
|
|
to specify <literal>lock</literal> or <literal>all</literal> as a
|
|
cascade style for the association.
|
|
</para>
|
|
|
|
<para>
|
|
It is possible to re-load an object and all its collections at any time, using the
|
|
<literal>refresh()</literal> method. This is useful when database triggers are used to
|
|
initialize some of the properties of the object.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[sess.save(cat);
|
|
sess.flush(); //force the SQL INSERT
|
|
sess.refresh(cat); //re-read the state (after the trigger executes)]]></programlisting>
|
|
|
|
<para>
|
|
An important question usually appears at this point: How much does Hibernate load
|
|
from the database and how many SQL <literal>SELECT</literal>s will it use? This
|
|
depends on the <emphasis>fetching strategy</emphasis> and is explained in
|
|
<xref linkend="performance-fetching"/>.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-querying" revision="1">
|
|
<title>Querying</title>
|
|
|
|
<para>
|
|
If you don't know the identifiers of the objects you are looking for,
|
|
you need a query. Hibernate supports an easy-to-use but powerful object
|
|
oriented query language (HQL). For programmatic query creation, Hibernate
|
|
supports a sophisticated Criteria and Example query feature (QBC and QBE).
|
|
You may also express your query in the native SQL of your database, with
|
|
optional support from Hibernate for result set conversion into objects.
|
|
</para>
|
|
|
|
<sect2 id="objectstate-querying-executing">
|
|
<title>Executing queries</title>
|
|
|
|
<para>
|
|
HQL and native SQL queries are represented with an instance of <literal>org.hibernate.Query</literal>.
|
|
This interface offers methods for parameter binding, result set handling, and for the execution
|
|
of the actual query. You always obtain a <literal>Query</literal> using the current
|
|
<literal>Session</literal>:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = session.createQuery(
|
|
"from Cat as cat where cat.birthdate < ?")
|
|
.setDate(0, date)
|
|
.list();
|
|
|
|
List mothers = session.createQuery(
|
|
"select mother from Cat as cat join cat.mother as mother where cat.name = ?")
|
|
.setString(0, name)
|
|
.list();
|
|
|
|
List kittens = session.createQuery(
|
|
"from Cat as cat where cat.mother = ?")
|
|
.setEntity(0, pk)
|
|
.list();
|
|
|
|
Cat mother = (Cat) session.createQuery(
|
|
"select cat.mother from Cat as cat where cat = ?")
|
|
.setEntity(0, izi)
|
|
.uniqueResult();]]></programlisting>
|
|
|
|
<para>
|
|
A query is usually executed by invoking <literal>list()</literal>, the
|
|
result of the query will be loaded completely into a collection in memory.
|
|
Entity instance retrieved by a query are in persistent state. The
|
|
<literal>uniqueResult()</literal> method offers a shortcut if you
|
|
know your query will only return a single object.
|
|
</para>
|
|
|
|
<sect3 id="objectstate-querying-executing-iterate">
|
|
<title>Iterating results</title>
|
|
|
|
<para>
|
|
Occasionally, you might be able to achieve better performance by
|
|
executing the query using the <literal>iterate()</literal> method.
|
|
This will only usually be the case if you expect that the actual
|
|
entity instances returned by the query will already be in the session
|
|
or second-level cache. If they are not already cached,
|
|
<literal>iterate()</literal> will be slower than <literal>list()</literal>
|
|
and might require many database hits for a simple query, usually
|
|
<emphasis>1</emphasis> for the initial select which only returns identifiers,
|
|
and <emphasis>n</emphasis> additional selects to initialize the actual instances.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[// fetch ids
|
|
Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate();
|
|
while ( iter.hasNext() ) {
|
|
Qux qux = (Qux) iter.next(); // fetch the object
|
|
// something we couldnt express in the query
|
|
if ( qux.calculateComplicatedAlgorithm() ) {
|
|
// delete the current instance
|
|
iter.remove();
|
|
// dont need to process the rest
|
|
break;
|
|
}
|
|
}]]></programlisting>
|
|
|
|
<para>
|
|
Hibernate queries sometimes return tuples of objects, in which case each tuple
|
|
is returned as an array:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Iterator kittensAndMothers = sess.createQuery(
|
|
"select kitten, mother from Cat kitten join kitten.mother mother")
|
|
.list()
|
|
.iterator();
|
|
|
|
while ( kittensAndMothers.hasNext() ) {
|
|
Object[] tuple = (Object[]) kittensAndMothers.next();
|
|
Cat kitten = tuple[0];
|
|
Cat mother = tuple[1];
|
|
....
|
|
}]]></programlisting>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="objectstate-querying-executing-scalar">
|
|
<title>Scalar results</title>
|
|
|
|
<para>
|
|
Queries may specify a property of a class in the <literal>select</literal> clause.
|
|
They may even call SQL aggregate functions. Properties or aggregates are considered
|
|
"scalar" results (and not entities in persistent state).
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Iterator results = sess.createQuery(
|
|
"select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
|
|
"group by cat.color")
|
|
.list()
|
|
.iterator();
|
|
|
|
while ( results.hasNext() ) {
|
|
Object[] row = results.next();
|
|
Color type = (Color) row[0];
|
|
Date oldest = (Date) row[1];
|
|
Integer count = (Integer) row[2];
|
|
.....
|
|
}]]></programlisting>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="objectstate-querying-executing-parameters">
|
|
<title>Bind parameters</title>
|
|
|
|
<para>
|
|
Methods on <literal>Query</literal> are provided for binding values to
|
|
named parameters or JDBC-style <literal>?</literal> parameters. Named parameters
|
|
are identifiers of the form <literal>:name</literal> in the query string.
|
|
<emphasis>Contrary to JDBC, Hibernate numbers parameters from zero.</emphasis>
|
|
The advantages of named parameters are:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
named parameters are insensitive to the order they occur in the
|
|
query string
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
they may occur multiple times in the same query
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
they are self-documenting
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<programlisting><![CDATA[//named parameter (preferred)
|
|
Query q = sess.createQuery("from DomesticCat cat where cat.name = :name");
|
|
q.setString("name", "Fritz");
|
|
Iterator cats = q.iterate();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[//positional parameter
|
|
Query q = sess.createQuery("from DomesticCat cat where cat.name = ?");
|
|
q.setString(0, "Izi");
|
|
Iterator cats = q.iterate();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[//named parameter list
|
|
List names = new ArrayList();
|
|
names.add("Izi");
|
|
names.add("Fritz");
|
|
Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)");
|
|
q.setParameterList("namesList", names);
|
|
List cats = q.list();]]></programlisting>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="objectstate-querying-executing-pagination">
|
|
<title>Pagination</title>
|
|
|
|
<para>
|
|
If you need to specify bounds upon your result set (the maximum number of rows
|
|
you want to retrieve and / or the first row you want to retrieve) you should
|
|
use methods of the <literal>Query</literal> interface:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Query q = sess.createQuery("from DomesticCat cat");
|
|
q.setFirstResult(20);
|
|
q.setMaxResults(10);
|
|
List cats = q.list();]]></programlisting>
|
|
|
|
<para>
|
|
Hibernate knows how to translate this limit query into the native
|
|
SQL of your DBMS.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="objectstate-querying-executing-scrolling">
|
|
<title>Scrollable iteration</title>
|
|
|
|
<para>
|
|
If your JDBC driver supports scrollable <literal>ResultSet</literal>s, the
|
|
<literal>Query</literal> interface may be used to obtain a
|
|
<literal>ScrollableResults</literal> object, which allows flexible
|
|
navigation of the query results.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " +
|
|
"order by cat.name");
|
|
ScrollableResults cats = q.scroll();
|
|
if ( cats.first() ) {
|
|
|
|
// find the first name on each page of an alphabetical list of cats by name
|
|
firstNamesOfPages = new ArrayList();
|
|
do {
|
|
String name = cats.getString(0);
|
|
firstNamesOfPages.add(name);
|
|
}
|
|
while ( cats.scroll(PAGE_SIZE) );
|
|
|
|
// Now get the first page of cats
|
|
pageOfCats = new ArrayList();
|
|
cats.beforeFirst();
|
|
int i=0;
|
|
while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) );
|
|
|
|
}
|
|
cats.close()]]></programlisting>
|
|
|
|
<para>
|
|
Note that an open database connection (and cursor) is required for this
|
|
functionality, use <literal>setMaxResult()</literal>/<literal>setFirstResult()</literal>
|
|
if you need offline pagination functionality.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="objectstate-querying-executing-named">
|
|
<title>Externalizing named queries</title>
|
|
|
|
<para>
|
|
You may also define named queries in the mapping document. (Remember to use a
|
|
<literal>CDATA</literal> section if your query contains characters that could
|
|
be interpreted as markup.)
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<query name="eg.DomesticCat.by.name.and.minimum.weight"><![CDATA[
|
|
from eg.DomesticCat as cat
|
|
where cat.name = ?
|
|
and cat.weight > ?
|
|
] ]></query>]]></programlisting>
|
|
|
|
<para>
|
|
Parameter binding and executing is done programatically:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Query q = sess.getNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
|
|
q.setString(0, name);
|
|
q.setInt(1, minWeight);
|
|
List cats = q.list();]]></programlisting>
|
|
|
|
<para>
|
|
Note that the actual program code is independent of the query language that
|
|
is used, you may also define native SQL queries in metadata, or migrate
|
|
existing queries to Hibernate by placing them in mapping files.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="objectstate-filtering" revision="1">
|
|
<title>Filtering collections</title>
|
|
<para>
|
|
A collection <emphasis>filter</emphasis> is a special type of query that may be applied to
|
|
a persistent collection or array. The query string may refer to <literal>this</literal>,
|
|
meaning the current collection element.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Collection blackKittens = session.createFilter(
|
|
pk.getKittens(),
|
|
"where this.color = ?")
|
|
.setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) )
|
|
.list()
|
|
);]]></programlisting>
|
|
|
|
<para>
|
|
The returned collection is considered a bag, and its a copy of the given
|
|
collection. The original collection is not modified (this is contrary to
|
|
the implication of the name "filter", but consistent with expected behavior).
|
|
</para>
|
|
|
|
<para>
|
|
Observe that filters do not require a <literal>from</literal> clause (though they may have
|
|
one if required). Filters are not limited to returning the collection elements themselves.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Collection blackKittenMates = session.createFilter(
|
|
pk.getKittens(),
|
|
"select this.mate where this.color = eg.Color.BLACK.intValue")
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Even an empty filter query is useful, e.g. to load a subset of elements in a
|
|
huge collection:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Collection tenKittens = session.createFilter(
|
|
mother.getKittens(), "")
|
|
.setFirstResult(0).setMaxResults(10)
|
|
.list();]]></programlisting>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="objecstate-querying-criteria" revision="1">
|
|
<title>Criteria queries</title>
|
|
|
|
<para>
|
|
HQL is extremely powerful but some developers prefer to build queries dynamically,
|
|
using an object-oriented API, rather than building query strings. Hibernate provides
|
|
an intuitive <literal>Criteria</literal> query API for these cases:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Criteria crit = session.createCriteria(Cat.class);
|
|
crit.add( Expression.eq( "color", eg.Color.BLACK ) );
|
|
crit.setMaxResults(10);
|
|
List cats = crit.list();]]></programlisting>
|
|
|
|
<para>
|
|
The <literal>Criteria</literal> and the associated <literal>Example</literal>
|
|
API are discussed in more detail in <xref linkend="querycriteria"/>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="objectstate-querying-nativesql" revision="2">
|
|
<title>Queries in native SQL</title>
|
|
|
|
<para>
|
|
You may express a query in SQL, using <literal>createSQLQuery()</literal> and
|
|
let Hibernate take care of the mapping from result sets to objects. Note
|
|
that you may at any time call <literal>session.connection()</literal> and
|
|
use the JDBC <literal>Connection</literal> directly. If you chose to use the
|
|
Hibernate API, you must enclose SQL aliases in braces:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = session.createSQLQuery(
|
|
"SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10",
|
|
"cat",
|
|
Cat.class
|
|
).list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List cats = session.createSQLQuery(
|
|
"SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " +
|
|
"{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " +
|
|
"FROM CAT {cat} WHERE ROWNUM<10",
|
|
"cat",
|
|
Cat.class
|
|
).list()]]></programlisting>
|
|
|
|
<para>
|
|
SQL queries may contain named and positional parameters, just like Hibernate queries.
|
|
More information about native SQL queries in Hibernate can be found in
|
|
<xref linkend="querysql"/>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-modifying" revision="1">
|
|
<title>Modifying persistent objects</title>
|
|
|
|
<para>
|
|
<emphasis>Transactional persistent instances</emphasis> (ie. objects loaded, saved, created or
|
|
queried by the <literal>Session</literal>) may be manipulated by the application
|
|
and any changes to persistent state will be persisted when the <literal>Session</literal>
|
|
is <emphasis>flushed</emphasis> (discussed later in this chapter). There is no need
|
|
to call a particular method (like <literal>update()</literal>, which has a different
|
|
purpose) to make your modifications persistent. So the most straightforward way to update
|
|
the state of an object is to <literal>load()</literal> it,
|
|
and then manipulate it directly, while the <literal>Session</literal> is open:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(69) );
|
|
cat.setName("PK");
|
|
sess.flush(); // changes to cat are automatically detected and persisted]]></programlisting>
|
|
|
|
<para>
|
|
Sometimes this programming model is inefficient since it would require both an SQL
|
|
<literal>SELECT</literal> (to load an object) and an SQL <literal>UPDATE</literal>
|
|
(to persist its updated state) in the same session. Therefore Hibernate offers an
|
|
alternate approach, using detached instances.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>Note that Hibernate does not offer its own API for direct execution of
|
|
<literal>UPDATE</literal> or <literal>DELETE</literal> statements. Hibernate is a
|
|
<emphasis>state management</emphasis> service, you don't have to think in
|
|
<emphasis>statements</emphasis> to use it. JDBC is a perfect API for executing
|
|
SQL statements, you can get a JDBC <literal>Connection</literal> at any time
|
|
by calling <literal>session.connection()</literal>. Furthermore, the notion
|
|
of mass operations conflicts with object/relational mapping for online
|
|
transaction processing-oriented applications. Future versions of Hibernate
|
|
may however provide special mass operation functions.</emphasis>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-detached" revision="2">
|
|
<title>Modifying detached objects</title>
|
|
|
|
<para>
|
|
Many applications need to retrieve an object in one transaction, send it to the
|
|
UI layer for manipulation, then save the changes in a new transaction.
|
|
Applications that use this kind of approach in a high-concurrency environment
|
|
usually use versioned data to ensure isolation for the "long" unit of work.
|
|
</para>
|
|
|
|
<para>
|
|
Hibernate supports this model by providing for reattachment of detached instances
|
|
using the <literal>Session.update()</literal> or <literal>Session.merge()</literal>
|
|
methods:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[// in the first session
|
|
Cat cat = (Cat) firstSession.load(Cat.class, catId);
|
|
Cat potentialMate = new Cat();
|
|
firstSession.save(potentialMate);
|
|
|
|
// in a higher layer of the application
|
|
cat.setMate(potentialMate);
|
|
|
|
// later, in a new session
|
|
secondSession.update(cat); // update cat
|
|
secondSession.update(mate); // update mate]]></programlisting>
|
|
|
|
<para>
|
|
If the <literal>Cat</literal> with identifier <literal>catId</literal> had already
|
|
been loaded by <literal>secondSession</literal> when the application tried to
|
|
reattach it, an exception would have been thrown.
|
|
</para>
|
|
|
|
<para>
|
|
Use <literal>update()</literal> if you are sure that the session does
|
|
not contain an already persistent instance with the same identifier, and
|
|
<literal>merge()</literal> if you want to merge your modifications at any time
|
|
without consideration of the state of the session. In other words, <literal>update()</literal>
|
|
is usually the first method you would call in a fresh session, ensuring that
|
|
reattachment of your detached instances is the first operation that is executed.
|
|
</para>
|
|
|
|
<para>
|
|
The application should individually <literal>update()</literal> detached instances
|
|
reachable from the given detached instance if and <emphasis>only</emphasis> if it wants
|
|
their state also updated. This can be automated of course, using <emphasis>transitive
|
|
persistence</emphasis>, see <xref linkend="objectstate-transitive"/>.
|
|
</para>
|
|
|
|
<para>
|
|
The <literal>lock()</literal> method also allows an application to reassociate
|
|
an object with a new session. However, the detached instance has to be unmodified!
|
|
</para>
|
|
|
|
<programlisting><![CDATA[//just reassociate:
|
|
sess.lock(fritz, LockMode.NONE);
|
|
//do a version check, then reassociate:
|
|
sess.lock(izi, LockMode.READ);
|
|
//do a version check, using SELECT ... FOR UPDATE, then reassociate:
|
|
sess.lock(pk, LockMode.UPGRADE);]]></programlisting>
|
|
|
|
<para>
|
|
Note that <literal>lock()</literal> can be used with various
|
|
<literal>LockMode</literal>s, see the API documentation and the
|
|
chapter on transaction handling for more information. Reattachment is not
|
|
the only usecase for <literal>lock()</literal>.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-saveorupdate">
|
|
<title>Automatic state detection</title>
|
|
|
|
<para>
|
|
TODO: discuss new unsaved check defaults, the rest of this section is probably obsolete
|
|
</para>
|
|
|
|
<para>
|
|
Hibernate users have requested a general purpose method that either saves a
|
|
transient instance by generating a new identifier or updates/reattaches
|
|
the detached instances associated with its current identifier.
|
|
The <literal>saveOrUpdate()</literal> method implements this functionality.
|
|
</para>
|
|
|
|
<para>
|
|
Hibernate distinguishes "new" transient instances from detached instances by the
|
|
value of the identifier (or version, or timestamp) property. The <literal>unsaved-value</literal>
|
|
attribute of the <literal><id></literal> (or <literal><version></literal>,
|
|
or <literal><timestamp></literal>) mapping specifies which values should
|
|
be interpreted as representing a new transient instance.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<id name="id" type="long" column="uid" unsaved-value="null">
|
|
<generator class="hilo"/>
|
|
</id>]]></programlisting>
|
|
|
|
<para>
|
|
The allowed values of <literal>unsaved-value</literal> are:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>any</literal> - always save
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>none</literal> - always update
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>null</literal> - save when identifier is null (this is the default)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
valid identifier value - save when identifier is null or the given value
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>undefined</literal> - the default for <literal>version</literal> or
|
|
<literal>timestamp</literal>, then identifier check is used
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<programlisting><![CDATA[// in the first session
|
|
Cat cat = (Cat) firstSession.load(Cat.class, catID);
|
|
|
|
// in a higher tier of the application
|
|
Cat mate = new Cat();
|
|
cat.setMate(mate);
|
|
|
|
// later, in a new session
|
|
secondSession.saveOrUpdate(cat); // update existing state (cat has a non-null id)
|
|
secondSession.saveOrUpdate(mate); // save the new instance (mate has a null id)]]></programlisting>
|
|
|
|
<para>
|
|
The usage and semantics of <literal>saveOrUpdate()</literal> seems to be confusing
|
|
for new users. Firstly, so long as you are not trying to use instances from one session
|
|
in another new session, you should not need to use <literal>update()</literal>,
|
|
<literal>saveOrUpdate()</literal>, or <literal>merge()</literal>. Some whole
|
|
applications will never use either of these methods.
|
|
</para>
|
|
|
|
<para>
|
|
Usually <literal>update()</literal> or <literal>saveOrUpdate()</literal> are used in
|
|
the following scenario:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
the application loads an object in the first session
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the object is passed up to the UI tier
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
some modifications are made to the object
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the object is passed back down to the business logic tier
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the application persists these modifications by calling
|
|
<literal>update()</literal> in a second session
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
<literal>saveOrUpdate()</literal> does the following:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
if the object is already persistent in this session, do nothing
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if the object has no identifier property, <literal>save()</literal> it
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if the object's identifier matches the criteria specified by
|
|
<literal>unsaved-value</literal>, <literal>save()</literal> it
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if the object is versioned (<literal>version</literal> or
|
|
<literal>timestamp</literal>), then the version will take precedence
|
|
to identifier check, unless the versions
|
|
<literal>unsaved-value="undefined"</literal> (default value)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if another object associated with the session has the same
|
|
identifier, throw an exception
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
and <literal>merge()</literal> is very different:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
copies the state of the given object onto the already persistent
|
|
object with the same identifier
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
if there is no persistent instance currently associated with
|
|
the session, it will be loaded
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
returns the persistent instance
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the given instance does not become associated with the session, it
|
|
stays detached
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-deleting" revision="1">
|
|
<title>Deleting persistent objects</title>
|
|
|
|
<para>
|
|
<literal>Session.delete()</literal> will remove an object's state from the database.
|
|
Of course, your application might still hold a reference to a deleted object.
|
|
It's best to think of <literal>delete()</literal> as making a persistent instance
|
|
transient.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[sess.delete(cat);]]></programlisting>
|
|
|
|
<para>
|
|
You may also delete many objects at once by passing a Hibernate query string to
|
|
<literal>delete()</literal>. Note that Hibernate will always load the objects
|
|
before deletion, to execute lifecycle and any kind of user-defined interception
|
|
on them (use direct JDBC for mass operations).
|
|
</para>
|
|
|
|
<para>
|
|
You may delete objects in any order you like, without risk of foreign key
|
|
constraint violations. Of course, it is still possible to violate a <literal>NOT
|
|
NULL</literal> constraint on a foreign key column by deleting objects in
|
|
the wrong order, e.g. if you delete the parent, but forget to delete the
|
|
children.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-flushing">
|
|
<title>Flushing the Session</title>
|
|
|
|
<para>
|
|
From time to time the <literal>Session</literal> will execute the SQL statements
|
|
needed to synchronize the JDBC connection's state with the state of objects held in
|
|
memory. This process, <emphasis>flush</emphasis>, occurs by default at the following
|
|
points
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
from some invocations of <literal>find()</literal> or <literal>iterate()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
from <literal>org.hibernate.Transaction.commit()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
from <literal>Session.flush()</literal>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The SQL statements are issued in the following order
|
|
</para>
|
|
|
|
<orderedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
all entity insertions, in the same order the corresponding objects
|
|
were saved using <literal>Session.save()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all entity updates
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all collection deletions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all collection element deletions, updates and insertions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all collection insertions
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
all entity deletions, in the same order the corresponding objects
|
|
were deleted using <literal>Session.delete()</literal>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
(An exception is that objects using <literal>native</literal> ID generation are
|
|
inserted when they are saved.)
|
|
</para>
|
|
|
|
<para>
|
|
Except when you explicity <literal>flush()</literal>, there are absolutely no
|
|
guarantees about <emphasis>when</emphasis> the <literal>Session</literal> executes
|
|
the JDBC calls, only the <emphasis>order</emphasis> in which they are executed.
|
|
However, Hibernate does guarantee that the <literal>Session.find(..)</literal>
|
|
methods will never return stale data; nor will they return the wrong data.
|
|
</para>
|
|
|
|
<para>
|
|
It is possible to change the default behavior so that flush occurs less frequently.
|
|
The <literal>FlushMode</literal> class defines three different modes: only flush
|
|
at commit time (and only when the Hibernate <literal>Transaction</literal> API
|
|
is used), flush automatically using the explained routine, or never flush unless
|
|
<literal>flush()</literal> is called explicitely. The last mode is useful for long running
|
|
units of work, where a <literal>Session</literal> is kept open and disconnected for
|
|
a long time (see <xref linkend="transactions-disconnection"/>).
|
|
</para>
|
|
|
|
<programlisting><![CDATA[sess = sf.openSession();
|
|
Transaction tx = sess.beginTransaction();
|
|
sess.setFlushMode(FlushMode.COMMIT); // allow queries to return stale state
|
|
|
|
Cat izi = (Cat) sess.load(Cat.class, id);
|
|
izi.setName(iznizi);
|
|
|
|
// might return stale data
|
|
sess.find("from Cat as cat left outer join cat.kittens kitten");
|
|
|
|
// change to izi is not flushed!
|
|
...
|
|
tx.commit(); // flush occurs]]></programlisting>
|
|
|
|
<para>
|
|
During flush, an exception might occur (e.g. if a DML operation violates a constraint).
|
|
Since handling exceptions involves some understanding of Hibernate's transactional behavior,
|
|
we discuss it in <xref linkend="transactions"/>.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-transitive">
|
|
<title>Transitive persistence</title>
|
|
|
|
<para>
|
|
It is quite cumbersome to save, delete, or reattach individual objects,
|
|
especially if you deal with a graph of associated objects. A common case is
|
|
a parent/child relationship. Consider the following example:
|
|
</para>
|
|
|
|
<para>
|
|
If the children in a parent/child relationship would be value typed (e.g. a collection
|
|
of addresses or strings), their lifecycle would depend on the parent and no
|
|
further action would be required for convenient "cascading" of state changes.
|
|
When the parent is saved, the value-typed child objects are saved as
|
|
well, when the parent is deleted, the children will be deleted, etc. This
|
|
even works for operations such as the removal of a child from the collection;
|
|
Hibernate will detect this and, since value-typed objects can't have shared
|
|
references, delete the child from the database.
|
|
</para>
|
|
|
|
<para>
|
|
Now consider the same scenario with parent and child objects being entities,
|
|
not value-types (e.g. categories and items, or parent and child cats). Entities
|
|
have their own lifecycle, support shared references (so removing an entity from
|
|
the collection does not mean it can be deleted), and there is by default no
|
|
cascading of state from one entity to any other associated entities. Hibernate
|
|
does not implement <emphasis>persistence by reachability</emphasis> by default.
|
|
</para>
|
|
|
|
<para>
|
|
To save or update all objects in a graph of associated entities, you must either
|
|
</para>
|
|
|
|
<para>
|
|
TODO: Document the new cascading styles
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>save()</literal>, <literal>saveOrUpdate()</literal> or
|
|
<literal>update()</literal> each individual object OR
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
map associated objects using or <literal>cascade="save-update"</literal>,
|
|
<literal>cascade="all"</literal> or <literal>cascade="all-delete-orphan"</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Likewise, to delete all objects in a graph, either
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>delete()</literal> each individual object OR
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
map associated objects using <literal>cascade="all"</literal>,
|
|
<literal>cascade="all-delete-orphan"</literal> or
|
|
<literal>cascade="delete"</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Recommendation:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
If the child object's lifespan is bounded by the lifespan of the of the parent
|
|
object make it a <emphasis>lifecycle object</emphasis> by specifying
|
|
<literal>cascade="all"</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise, <literal>save()</literal> and <literal>delete()</literal> it
|
|
explicitly from application code. If you really want to save yourself some
|
|
extra typing, use <literal>cascade="save-update"</literal> and explicit
|
|
<literal>delete()</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Mapping an association (many-to-one, or collection) with <literal>cascade="all"</literal>
|
|
marks the association as a <emphasis>parent/child</emphasis> style relationship where
|
|
save/update/deletion of the parent results in save/update/deletion of the child(ren).
|
|
Futhermore, a mere reference to a child from a persistent parent will result in save / update
|
|
of the child. The metaphor is incomplete, however. A child which becomes unreferenced by its
|
|
parent is <emphasis>not</emphasis> automatically deleted, except in the case of a
|
|
<literal><one-to-many></literal> association mapped with
|
|
<literal>cascade="all-delete-orphan"</literal>. The precise semantics of cascading operations
|
|
are as follows:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
If a parent is saved, all children are passed to <literal>saveOrUpdate()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If a parent is passed to <literal>update()</literal> or <literal>saveOrUpdate()</literal>,
|
|
all children are passed to <literal>saveOrUpdate()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If a transient or detached child becomes referenced by a persistent parent,
|
|
it is passed to <literal>saveOrUpdate()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If a parent is deleted, all children are passed to <literal>delete()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If a child is dereferenced by a persistent parent, <emphasis>nothing
|
|
special happens</emphasis> (the application should explicitly delete
|
|
the child if necessary) unless <literal>cascade="all-delete-orphan"</literal>,
|
|
in which case the "orphaned" child is deleted.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Hibernate does, even if you enable all cascading options, not fully implement "persistence
|
|
by reachability", which would imply (inefficient) persistent garbage collection (i.e.
|
|
detected references by scanning all tables in the database).
|
|
</para>
|
|
|
|
<para>
|
|
TODO: The following doesn't make much sense. Better we don't talk about persistence by
|
|
reachability anymore, its a bad idea from ODBMS vendors anyway...
|
|
</para>
|
|
|
|
<para>
|
|
However, due to popular demand,
|
|
Hibernate does support the notion of entities becoming persistent when referenced
|
|
by another persistent object. Associations marked
|
|
<literal>cascade="save-update"</literal> behave in this way. If you wish to use this
|
|
approach throughout your application, its easier to specify the
|
|
<literal>default-cascade</literal> attribute of the
|
|
<literal><hibernate-mapping></literal> element.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-filters">
|
|
<title>Application filters</title>
|
|
|
|
<para>
|
|
Hibernate3 adds the ability to pre-define filter criteria and attach those filters at both
|
|
a class and a collection level. A filter criteria is the ability to define a restriction clause
|
|
very similiar to the existing "where" attribute available on the class and various collection
|
|
elements. Except these filter conditions can be parameterized. The application can then make
|
|
the decision at runtime whether given filters should be enabled and what their parameter
|
|
values should be. Filters can be used like database views, but parameterized inside the
|
|
application.
|
|
</para>
|
|
|
|
<para>
|
|
In order to use filters, they must first be defined and then attached to the appropriate
|
|
mapping elements. To define a filter, use the <literal><filter-def/></literal> element
|
|
within a <literal><hibernate-mapping/></literal> element:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<filter-def name="myFilter">
|
|
<filter-param name="myFilterParam" type="string"/>
|
|
</filter-def>]]></programlisting>
|
|
|
|
<para>
|
|
Then, this filter can be attached to a class:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<class name="myClass" ...>
|
|
...
|
|
<filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
|
|
</class>]]></programlisting>
|
|
|
|
<para>
|
|
or, to a collection:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<set ...>
|
|
<filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
|
|
</set>]]></programlisting>
|
|
|
|
<para>
|
|
or, even to both (or multiples of each) at the same time.
|
|
</para>
|
|
|
|
<para>
|
|
The methods on <literal>Session</literal> are: <literal>enableFilter(String filterName)</literal>,
|
|
<literal>getEnabledFilter(String filterName)</literal>, and <literal>disableFilter(String filterName)</literal>.
|
|
By default, filters are <emphasis>not</emphasis> enabled for a given session; they must be explcitly
|
|
enabled through use of the <literal>Session.enabledFilter()</literal> method, which returns an
|
|
instance of the <literal>Filter</literal> interface. Using the simple filter defined above, this
|
|
would look like:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");]]></programlisting>
|
|
|
|
<para>
|
|
Note that methods on the org.hibernate.Filter interface do allow the method-chaining common to much of Hibernate.
|
|
</para>
|
|
|
|
<para>
|
|
A full example, using temporal data with an effective record date pattern:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<filter-def name="effectiveDate">
|
|
<filter-param name="asOfDate" type="date"/>
|
|
</filter-def>
|
|
|
|
<class name="Employee" ...>
|
|
...
|
|
<many-to-one name="department" column="dept_id" class="Department"/>
|
|
<property name="effectiveStartDate" type="date" column="eff_start_dt"/>
|
|
<property name="effectiveEndDate" type="date" column="eff_end_dt"/>
|
|
...
|
|
<!--
|
|
Note that this assumes non-terminal records have an eff_end_dt set to
|
|
a max db date for simplicity-sake
|
|
-->
|
|
<filter name="effectiveDate"
|
|
condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
|
|
</class>
|
|
|
|
<class name="Department" ...>
|
|
...
|
|
<set name="employees" lazy="true">
|
|
<key column="dept_id"/>
|
|
<one-to-many class="Employee"/>
|
|
<filter name="effectiveDate"
|
|
condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
|
|
</set>
|
|
</class>]]></programlisting>
|
|
|
|
<para>
|
|
Then, in order to ensure that you always get back currently effective records, simply
|
|
enable the filter on the session prior to retrieving employee data:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Session session = ...;
|
|
session.enabledFilter("effectiveDate").setParameter("asOfDate", new Date());
|
|
List results = session.createQuery("from Employee as e where e.salary > :targetSalary")
|
|
.setLong("targetSalary", new Long(1000000))
|
|
.list();
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
In the HQL above, even though we only explicitly mentioned a salary constraint on the results,
|
|
because of the enabled filter the query will return only currently active employees who have
|
|
a salary greater than a million dollars.
|
|
</para>
|
|
|
|
<para>
|
|
Note: if you plan on using filters with outer joining (either through HQL or load fetching) be
|
|
careful of the direction of the condition expression. Its safest to set this up for left
|
|
outer joining; in general, place the parameter first followed by the column name(s) after
|
|
the operator.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-interceptors" revision="1">
|
|
<title>Interceptors</title>
|
|
|
|
<para>
|
|
The <literal>Interceptor</literal> 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</literal> automatically sets the <literal>createTimestamp</literal>
|
|
when an <literal>Auditable</literal> is created and updates the
|
|
<literal>lastUpdateTimestamp</literal> property when an <literal>Auditable</literal> is
|
|
updated.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[package org.hibernate.test;
|
|
|
|
import java.io.Serializable;
|
|
import java.util.Date;
|
|
import java.util.Iterator;
|
|
|
|
import org.hibernate.Interceptor;
|
|
import org.hibernate.type.Type;
|
|
|
|
public class AuditInterceptor implements Interceptor, Serializable {
|
|
|
|
private int updates;
|
|
private int creates;
|
|
|
|
public void onDelete(Object entity,
|
|
Serializable id,
|
|
Object[] state,
|
|
String[] propertyNames,
|
|
Type[] types) {
|
|
// do nothing
|
|
}
|
|
|
|
public boolean onFlushDirty(Object entity,
|
|
Serializable id,
|
|
Object[] currentState,
|
|
Object[] previousState,
|
|
String[] propertyNames,
|
|
Type[] types) {
|
|
|
|
if ( entity instanceof Auditable ) {
|
|
updates++;
|
|
for ( int i=0; i < propertyNames.length; i++ ) {
|
|
if ( "lastUpdateTimestamp".equals( propertyNames[i] ) ) {
|
|
currentState[i] = new Date();
|
|
return true;
|
|
}
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
|
|
public boolean onLoad(Object entity,
|
|
Serializable id,
|
|
Object[] state,
|
|
String[] propertyNames,
|
|
Type[] types) {
|
|
return false;
|
|
}
|
|
|
|
public boolean onSave(Object entity,
|
|
Serializable id,
|
|
Object[] state,
|
|
String[] propertyNames,
|
|
Type[] types) {
|
|
|
|
if ( entity instanceof Auditable ) {
|
|
creates++;
|
|
for ( int i=0; i<propertyNames.length; i++ ) {
|
|
if ( "createTimestamp".equals( propertyNames[i] ) ) {
|
|
state[i] = new Date();
|
|
return true;
|
|
}
|
|
}
|
|
}
|
|
return false;
|
|
}
|
|
|
|
public void postFlush(Iterator entities) {
|
|
System.out.println("Creations: " + creates + ", Updates: " + updates);
|
|
}
|
|
|
|
public void preFlush(Iterator entities) {
|
|
updates=0;
|
|
creates=0;
|
|
}
|
|
|
|
...
|
|
|
|
}]]></programlisting>
|
|
|
|
<para>
|
|
The interceptor would be specified when a session is created.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]></programlisting>
|
|
|
|
<para>
|
|
You may also set an interceptor on a global level, using the <literal>Configuration</literal>:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[new Configuration().setInterceptor( new AuditInterceptor() );]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-events">
|
|
<title>Event system</title>
|
|
|
|
<para>
|
|
If you have to react to particular events in your persistence layer, you may
|
|
also use the Hibernate3 <emphasis>event</emphasis> architecture. The event
|
|
system can be used in addition or as a replacement for interceptors.
|
|
</para>
|
|
|
|
<para>
|
|
Essentially all of the methods of the <literal>Session</literal> interface correlate
|
|
to an event. You have a <literal>LoadEvent</literal>, a <literal>FlushEvent</literal>, etc
|
|
(consult the XML configuration-file DTD or the <literal>org.hibernate.event</literal>
|
|
package for the full list of defined event types). When a request is made of one of
|
|
these methods, the Hibernate <literal>Session</literal> generates an appropriate
|
|
event and passes it to the configured event listener 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</literal> is processed by the registered implemenation
|
|
of the <literal>LoadEventListener</literal> interface), in which case their
|
|
implementation would be responsible for processing any <literal>load()</literal> requests
|
|
made of the <literal>Session</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The listeners should be considered effectively singletons; meaning, they are shared between
|
|
requests, and thus should not save any state as instance variables. The event objects
|
|
themselves, however, do hold a lot of the context needed for processing as they are unique
|
|
to each request. Custom event listeners may also make use of the event's context for storage
|
|
of any needed processing variables. The context is a simple map, but the default listeners
|
|
don't use the context map at all, so don't worry about over-writing internally required
|
|
context variables.
|
|
</para>
|
|
|
|
<para>
|
|
A custom listener should implement 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 programatically through the
|
|
<literal>Configuration</literal> object, or specified in the Hibernate configuration
|
|
XML (declarative configuration through the properties file is not supported). Here's an
|
|
example of a custom load event listener:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[public class MyLoadListener extends DefaultLoadEventListener {
|
|
// this is the single method defined by the LoadEventListener interface
|
|
public Object onLoad(LoadEvent event, LoadEventListener.LoadType loadType)
|
|
throws HibernateException {
|
|
if ( !MySecurity.isAuthorized( event.getEntityClassName(), event.getEntityId() ) ) {
|
|
throw MySecurityException("Unauthorized access");
|
|
}
|
|
return super.onLoad(event, loadType);
|
|
}
|
|
}]]></programlisting>
|
|
|
|
<para>
|
|
You also need a configuration entry telling Hibernate to use the listener instead
|
|
of the default listener:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<hibernate-configuration>
|
|
<session-factory>
|
|
...
|
|
<listener type="load" class="MyLoadListener"/>
|
|
</session-factory>
|
|
</hibernate-configuration>]]></programlisting>
|
|
|
|
<para>
|
|
Instead, you may register it programatically:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Configuration cfg = new Configuration();
|
|
cfg.getSessionEventListenerConfig().setLoadEventListener( new MyLoadListener() );]]></programlisting>
|
|
|
|
<para>
|
|
Listeners registered declaratively cannot share instances. If the same class name is
|
|
used in multiple <literal><listener/></literal> elements, each reference will
|
|
result in a seperate instance of that class. If you need the capability to share
|
|
listener instances between listener types you must use the programatic registration
|
|
approach.
|
|
</para>
|
|
|
|
<para>
|
|
Why implement an interface and define the specific type during configuration? Well, 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>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="objectstate-metadata">
|
|
<title>Using metadata</title>
|
|
|
|
<para>
|
|
Hibernate requires a very rich meta-level model of all entity and value types. From time
|
|
to time, this model is very useful to the application itself. For example, the application
|
|
might use Hibernate's metadata to implement a "smart" deep-copy algorithm that understands
|
|
which objects should be copied (eg. mutable value types) and which should not (eg.
|
|
immutable value types and, possibly, associated entities).
|
|
</para>
|
|
<para>
|
|
Hibernate exposes metadata via the <literal>ClassMetadata</literal> and
|
|
<literal>CollectionMetadata</literal> interfaces and the <literal>Type</literal>
|
|
hierarchy. Instances of the metadata interfaces may be obtained from the
|
|
<literal>SessionFactory</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat fritz = ......;
|
|
Long id = (Long) catMeta.getIdentifier(fritz);
|
|
ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.class);
|
|
Object[] propertyValues = catMeta.getPropertyValues(fritz);
|
|
String[] propertyNames = catMeta.getPropertyNames();
|
|
Type[] propertyTypes = catMeta.getPropertyTypes();
|
|
// get a Map of all properties which are not collections or associations
|
|
// TODO: what about components?
|
|
Map namedValues = new HashMap();
|
|
for ( int i=0; i<propertyNames.length; i++ ) {
|
|
if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].isCollectionType() ) {
|
|
namedValues.put( propertyNames[i], propertyValues[i] );
|
|
}
|
|
}]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|