A Configuration object is created once, typically as part of the launching process of your application. The primary task of a Configuration object is to load and process the various *.hbm.xml files, binding them to the relevant persistent code, and returning an appropriately configured SessionFactory.

The list of methods in Table 6.1 is not complete. For a complete list, refer to the Hibernate javadoc (Hibernate_install_dir docapiindex.html). The summary shown in Table 6.1 illustrates the range of options available for storing configuration data.

If you are using a hibernate.cfg.xml (or one of the configure() methods), you will define the connectivity properties in that file. Otherwise, these properties may be set at runtime using a java.util.Properties object via Configuration.addProperties(), Configuration .setProperties(), or individually using Configuration.set Property().

Alternatively, the connectivity may be configured using a hibernate .properties file placed on the class path.

Tables 6.3 through 6.6 describe additional options for the configuration of Hibernate.

hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost/hibernate
hibernate.connection.username=root
hibernate.connection.password=
hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect
hibernate.show_sql=true

If you wish to use Hibernate (perhaps in conjunction with a pooling driver, as described in Chapter 10) to manage obtaining and releasing connections, you will want to set the properties as shown in Table 6.2.

If you wish to use Hibernate in the context of an application server, you will probably rely on the application server's built-in JNDI-based datasource mechanism for managing connections. Table 6.3 shows the properties that must be set to allow Hibernate to connect to JNDI datasources.

Hibernate also offers a wide variety of configurable options, as shown in Table 6.4. You can use them to provide additional database connectivity options or to set performance options.

Typically, Hibernate is able to automatically detect the proper SQL dialect to use based on the JDBC driver. You may wish to manually set the SQL dialect, either to ensure the proper dialect or for schema management (as described in Chapter 11). Table 6.5 shows the possible values for hibernate.dialect.

Similarly, Hibernate offers support for JTA to manage your transactions. Table 6.6 shows the supported JTA transaction managers.

Listing 6.2 shows an example of the use of the Configuration object to obtain a Session.

Configuration myConfiguration = new Configuration();

myConfiguration.addClass(Exam.class);
myConfiguration.addClass(Examresult.class);
myConfiguration.addClass(Course.class);
myConfiguration.addClass(Student.class);

// Sets up the session factory (used in the rest
// of the application).
sessionFactory = myConfiguration.buildSessionFactory();

Once a SessionFactory has been obtained, you will store this object somewhere (typically in a static variable) and use it throughout the rest of your application.

Most commonly, openSession()is the only method of a SessionFactory that you will use. The no-argument version will use the mechanism as described by the Configuration properties to connect to the database (usually the preferred mechanism).

Once you have obtained a session, you have access to a variety of options for manipulating data, as shown in Figure 6.2.

Figure 6.2. Session

Generally speaking, the methods of a session are concerned with the traditional create, retrieve, update, and delete operations.

TRANSACTIONS

You'll want to wrap calls to the session using method beginTransaction() and then calling Transaction.commit() when finished. Note that Hibernate will sometimes not actually flush SQL statements to the transaction until after the transaction is committed, which can on occasion lead to unwanted reordering of the SQL execution. For more information on flushing statements as part of a transaction, see Chapter 9.

Figure 6.1. SessionFactory

In other words, Hibernate may not execute the SQL in the order in which you issue the commands in the session. To avoid this, use the session.flush() when executing statements to ensure the proper order of execution (see Chapter 9 for more information).

As shown in examples throughout this book, make sure that you are using try/catch/finally blocks to properly commit or roll back transactions as needed and that sessions are closed properly.

Creating objects in Hibernate is straightforward. Simply allocate the persistent objects using new, set the properties, and then use Session.save().

A complication may arise when you are creating objects with collections, however. The important thing to remember is that collection elements added to a parent where the collection is set to inverse="true" are not persisted automatically—you must manually save them and add them to the inverse="false" end of the relationship to persist them.

Unfortunately, Hibernate does not allow both sides of a collection to be set to inverse="false". This means that you must think carefully about your needs in order to decide which side of an association to map as inverse="false". To complicate matters somewhat, this is also true when objects are deleted—it's easy to manually delete the associations, as long as the proper side of the relationship is used. You can work around this when working with the “wrong end” of a bi-directional association by using the outer-join-as-inverse-of-inner technique described in Chapter 8.

Session methods that are useful when you are saving objects are shown in Table 6.7.

Hibernate offers a wide variety of options for retrieving objects from the database, including HQL, the Criteria API, and using SQL directly (or even mixing different strategies). For more information, see Chapter 8.

The various methods available for retrieving objects via HQL (as described in Chapter 8) are shown in Table 6.8. These methods are routinely expected to return no results (for example, a query for the number of students in a class may legitimately return no students if there are none enrolled). If you wish to view the inability to retrieve an object as an application failure use load(), described under Refreshing Objects below, instead of get().

Some of these methods return a net.sf.hibernate.Query object instead of an immediate set of results. The net.sf.hibernate.Query object can be used to bind parameters and configure other aspects of the query before execution. The advantages of using an intermediate Query object include:

You may notice that there are two seemingly similar methods for retrieving results: find() and iterate(). The find() method executes immediately, whereas iterator() executes on demand. Therefore, find() methods typically perform better than iterator() methods. If you fear you may retrieve too many results with find(), you would probably be better off using create-Query() to configure the returned results.

In addition to HQL, Chapter 8 describes the use of both the Hibernate Criteria API and raw SQL to access data. Table 6.9 shows these methods.

Sometimes, you know that an object exists, but only have part of the object's information. The most typical example would be a situation in which you know an object's identify reference but don't have the rest of the object information (this is shown in the sample application in Chapter 2). Given an identifier, the load() method can be used to retrieve the rest of the information about an object. The difference between a load() and a get() is that a load() will fail with an exception if the object is not found, whereas a get() will simply return null.

Within the context of a single session, you may expect that the mere act of updating or saving the object will modify the properties. For example, a trigger may modify the data written to a particular column when a record is saved. The refresh() method is used in the context of a single Session to retrieve these changes. In practice, you'll probably use the load() method much more frequently than the refresh() method. The refresh() method can also be used to reassociate objects across transactions with a session (converting a transient object to a persistent object). This is especially important if you wish to take advantage of cascading operations, because Hibernate may not recognize cascading associations if objects are not properly refreshed. For an example of this, see Listing 2.17, Deleting an Author.

Deleting an object is largely a simple matter of passing the object to the session.delete(). You can use HQL to identify a range of records for higher-performance bulk deletes.

Table 6.11. shows the methods available for deleting data.

Much like creating an object, updating an object is a matter of simply modifying a persistent object and passing it to Session.update(). Table 6.12 shows the methods available for updating data.

The first form of identity is expressed in terms of the database key. For example, two records could be considered equal if they have the same primary key value.

The second form of identity is expressed in terms of the Java object reference. We can imagine a situation in which two Java objects contain the same data from the perspective of the developer but are different objects because they are stored in two different places in memory.

Finally, the third form of identity derives from a comparison of all of the data associated with the object. For example, consider an object containing student data. This object might be represented by a primary key (for example, 543), a JVM object reference (for example, 82340), or the values of the associated data (for example, the primary key, 543, the first name, and the last name).

If the student object were to change the value of the last-name property, neither the primary key nor the object reference would be changed, even though the object is clearly no longer equivalent.

Consider the following snippet of code and the different values that may be considered when evaluating equality:

Obviously, these different notions of equality can lead to radically different answers when one is trying to answer the question “Are these two objects equal?”

Hibernate expresses these two different notions of equality by taking advantage of the two different mechanisms for equality built into the Java language. The Java = and == operators rely on the object reference. All Java objects, on the other hand, descend from the base java.lang.Object class, which defines an equals() method. Therefore, Hibernate uses the equals() method to determine persistent identity, and the == method to determine JVM equality.

Let's look at a standard Hibernate equals() implementation, as shown in Listing 6.3. This is declared in a class called Message (as described in more detail later in this chapter). The first order of comparison in the snippet is by class instance. Then the objects are compared for equality by their primary-key value and nothing else (for more information on the Apache Jakarta Commons Lang project's EqualsBuilder class, see http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/builder/EqualsBuilder.html). Therefore, this object will rely on the notion of primary-key values for equality.

public boolean equals(Object other)
{
    if (!(other instanceof Message))
        return false;
    Message castOther = (Message)other;
    return new EqualsBuilder()
        .append(this.getId(), castOther.getId())
        .isEquals();
}

Similarly, Listing 6.4 shows the matching implementation of hashCode().

    public int hashCode()
    {
        return new
HashCodeBuilder().append(getId()).toHashCode();
    }

The documentation for the Apache Jakarta Commons Lang HashCodeBuilder will be found at http://jakarta.apache.org/commons/lang/api/org/apache/commons/lang/builder/HashCodeBuilder.html. The hashCode is principally derived from the primary key id, as in the equals() method.

Hibernate has the very interesting capability of replacing instances that you pass to it with new instances as needed, in order to maintain internal consistency.

This means that you will always get back the same JVM object reference when you perform operations in the context of a single session. For example, consider the Hibernate pseudo-code shown in Listing 6.5.

hibernateSession = sessionFactory.openSession();
Student myStudent = hibernateSession.load(Student.class, new Long(23));
...
Student altStudent = hibernateSession.load(Student.class, new Long(23));
if(myStudent == altStudent)
      System.out.println("Students are equal!");

The snippet in Listing 6.5 will evaluate myStudent == altStudent to true, because Hibernate maintains the object reference as part of the open session.

Conversely, this state is not shared across sessions, and so if myStudent and altStudent were retrieved from different sessions, they may or may not evaluate to true, depending on the session, cache, thread, and other JVM details. All this means that you don't need to worry about object identity or concurrency as long as you don't share a session across threads (virtually never a good idea).

Later in this chapter, we will show how to use Hibernate object life-cycle methods to examine the issues of identity in more detail.

The terms identity and primary key have different meanings, but they are often used interchangeably when working with Hibernate. Object identity refers to the more general notion of identity—a unique value that can be used to retrieve a unique object.

Generally speaking, when a record is stored in a database, it is given a pri mary key as the main indicator of its identity. As a safeguard against possible changes to the application, this primary key typically has no particular business value or association with other data in the record.

In certain instances, however, object identity is not managed by a primary key, but by another mechanism. For example, the records in a collection table may be referred to by a composite key (the fusion of the two collected foreign keys), with no primary key required.

There are several built-in strategies available for primary key generation. Hibernate controls the configuration of identity generation for standard primary keys using the generator tag in the *.hbm.xml mapping file (see the generator tag in Chapter 5 for more information). Hibernate allows you to specify a custom Java class that implements the interface net.sf .hibernate.id.IdentifierGenerator for identity generation, but it also includes a large suite of built-in generation classes.

Hibernate includes many built-in implementations of net.sf.hibernate .id.IdentifierGenerator that allow you to easily support a wide variety of possible key generators. You can refer to these built-in generators either by their fully qualified class names or by their “shortcut” names.

If you are working with an existing database, you'll want to select the generator that matches the current key generation strategy.

Most objects will rely on a built-in generator for key generation. Some objects, however (in particular, those used in collection tables) may rely on composite keys. An example of this is shown in the ownership table in Chapter 3. Listing 6.6 shows the description of the ownership table as given by MySQL. Note that the table has two primary keys. In the discussion that follows, we will assume that the most popular use of composite keys is for collection tables (of course this may not be true for certain applications), and therefore we will discuss them in that context.

mysql> desc ownership;
+-------------+------------+------+-----+---------+-------+
| Field       | Type       | Null | Key | Default | Extra |
+-------------+------------+------+-----+---------+-------+
| owner_id    | bigint(20) |      | PRI | 0       |       |
| artifact_id | bigint(20) |      | PRI | 0       |       |
+-------------+------------+------+-----+---------+-------+

On reflection, you will realize that this makes it difficult to work individual records outside the context of the related objects. Although this is largely a non-issue, it makes working with composite identity records more difficult as you develop certain complex relationships. If you are content to allow Hibernate to manage your collections, and do not impose any additional fields beyond those Hibernate requires for the collection (for example, index columns as needed, but no additional data fields), you may never need to deal with composite identity directly.

Putting this in the context of the example application shown in Chapter 3, you will note that there is no class-level declaration of the ownership table. Instead, all references to the ownership table are made via collection-tag bindings. Listing 6.7 shows one side of this binding from the Artifact.hbm.xml file. A similar (but inverted) binding exists in the Owner.hbm.xml file.

<set name="owners" table="ownership" lazy="false" inverse="true" cascade="none"
 sort="unsorted">
<key column="artifact_id"/>
<many-to-many class="com.cascadetg.ch03.Owner" column="owner_id" outer-join="auto"/>
</set>

Thus, even though this application uses a table with composite identity, there is no need to explicitly deal with the composite-identity as such; Hibernate takes care of this for us.

In certain situations, particularly when working with a legacy database schema, you won't have the luxury of a pure collection table. In situations in which you have a collection table with additional data, you are often best off representing the collection table as an independent class (an example of which is shown in Chapter 4). In this case, the table identity may need to be modeled using a composite identity tag, such as composite-element, composite-id, or composite-index. These tags, described in Chapter 5, are used in combination with nested property tags to declare the columns used to manage the composite identifiers.

It's very important to correctly implement the Object.equals() and Object.hashCode() methods to correctly handle composite identity. The default methods, as shown in Listing 6.3 and Listing 6.4, should include all of the property values required to correctly map the composite identity, not just the getId() methods as shown.

Hibernate offers a feature that allows you to perform a save-or-update with a single method call (as shown in Table 6.7). In other words, let's say that you wish to either update an object (if it exists) or create it (if it doesn't). In order to know whether an object has been created (at least from the perspective of the application running in the JVM), Hibernate will inspect certain values to see if they have been set.

The most immediate and obvious example is the primary key (or id) of the object. For example, perhaps you are using a java.lang.Long to track the primary key of an object. If this field is set to null, then Hibernate knows that the object has not been saved in the database. Similarly, if the value is not null, then Hibernate knows that the object has a primary key and therefore must exist in the database (because null is the unsaved value).

This use of a null is an important reason to use the object version of a value (e.g., java.lang.Long) instead of the primitive form (e.g., long). While null values are sometimes simulated with a primitive (e.g., 0 or -1), this is a fragile and non-standard approach. Normally, this is the most significant impact of the notion of unsaved value, but as you develop complex data models or cope with certain legacy data models, you may find other reasons to change the notion of an unsaved value.