The Cons of Annotations

If you are upgrading from an earlier Hibernate environment, you may already have XML-based mapping files to support your code base. All else being equal, you will not want to reexpress these mappings using annotations just for the sake of it.

If you are migrating from a legacy environment, you may not want to alter the preexisting POJO source code, lest you contaminate known good code with possible bugs.² Annotations are compiled into the class files, after all, and therefore might be considered to be changes to source or delivered artifacts.

If you do not have the source code to your POJOs (because it was generated by an automated tool or something similar), you may prefer the use of external XML-based mappings to the decompilation of class files to obtain Java source code for alteration.

Maintaining the mapping information as external XML files allows that mapping information to be modified to reflect business changes or schema alterations without forcing you to rebuild the application as a whole. However, building an application when you have a build system in place (Maven or Gradle, along with any continuous integration tools you might have) is usually pretty easy, so this isn’t much of a convincing argument either way.

The Pros of Annotations

Having considered the drawbacks, there are some powerful benefits to using annotations.

First, and perhaps most persuasively, we find annotations-based mappings to be far more intuitive than their XML-based alternatives, as they are immediately in the source code along with the properties with which they are associated. Most coders tend to prefer the annotations because fewer files have to be kept synchronized with each other.

Partly as a result of this, annotations are less verbose than their XML equivalents, as evidenced by the contrast between Listings 6-1 and 6-2.

Listing 6-1. A Minimal Class Mapped Using Annotations

import javax.persistence.* ;

@Entity
public class Sample {
    @Id  
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    public Integer id;
    public String name;
}

Listing 6-2. A Minimal Class Mapped Using XML

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE
   hibernate-mapping
   PUBLIC
   "-//Hibernate/Hibernate Mapping DTD//EN"
   "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping default-access="field">
   <class name="Sample">
      <id type="int" column="id">
         <generator class="native"/>
      </id>
      <property name="name" type="string"/>
   </class>
</hibernate-mapping>

Some of the latter’s verbosity is in the nature of XML itself (the tag names and the boilerplate document-type declaration), and some of it is due to the closer integration of annotations with the source code. Here, for example, the XML file must explicitly declare that field access is used in place of property access (i.e., the fields are accessed directly rather than through their get/set methods); but the annotation infers this from the fact that it has been applied to the id field rather than the getId() method.

Hibernate uses and supports the JPA 2 persistence annotations. If you elect not to use Hibernate-specific features in your code and annotations, you will have the freedom to deploy your entities to environments using other ORM tools that support JPA 2.

Finally – and perhaps a minor point – because the annotations are compiled directly into the appropriate class files, there is less risk that a missing or stale mapping file will cause problems at deployment (this point will perhaps prove most persuasive to those who already have some experience with this hazard of the XML technique).

Choosing Which to Use

In general, prefer annotations; the annotations themselves are portable across JPA implementations, and they’re well known. Tools can create the annotated source code directly from a database, so synchronization is less of an issue than it could be, even with a preexisting schema.

The XML mapping can be done either in Hibernate’s proprietary format or JPA’s standard XML configuration, which is similar but not identical; if you somehow find XML to be a preferable configuration format, you’re probably better off using the XML format from the industry-standard JPA configuration.³

Entity Beans with @Entity

The first step is to annotate the Book class as a JPA 2 entity bean. We add the @Entity annotation to the Book class, as follows:

package chapter06.primarykey.after;

import javax.persistence.*;

@Entity
public class Book
    public Book() {
    }

The JPA 2 standard annotations are contained in the javax.persistence package, so we import the appropriate annotations. Some IDEs will use specific imports, as opposed to “star imports,” in situations where few classes in a given package are imported; typically, an entity will use quite a few annotations from this package so chances are it’ll end up with star imports in any event.

The @Entity annotation marks this class as an entity bean, so it must have a no-argument constructor that is visible with at least protected scope.⁴ Hibernate supports package scope as the minimum, but you lose portability to other JPA implementations if you take advantage of this. Other JPA 2 rules for an entity bean class are (a) that the class must not be final, and (b) that the entity bean class must be concrete. Many of the rules for JPA 2 entity bean classes and Hibernate’s persistent objects are the same – partly because the Hibernate team had much input into the JPA 2 design process, and partly because there are only so many ways to design a relatively unobtrusive object-relational persistence solution.

So far, we’ve added the Entity annotation, a constructor, and an import statement. The rest of the POJO has been left alone.

Primary Keys with @Id and @GeneratedValue

Each entity bean has to have a primary key, which you annotate on the class with the @Id annotation . Typically, the primary key will be a single field, though it can also be a composite of multiple fields.

The placement of the @Id annotation determines the default access strategy that Hibernate will use for the mapping. If the annotation is applied to a field as shown in Listing 6-4, then field access will be used.

Listing 6-4. A Class with Field Access

import javax.persistence.*;

@Entity
public class Sample {
   @Id
   int id;

   public int getId() {
      return this.id;
   }

   public void setId(int id) {
      this.id = id;
   }
}

If, instead, the annotation is applied to the accessor for the field, as shown in Listing 6-5, then property access will be used. Property accessmeans that Hibernate will call the mutator instead of actually setting the field directly; this also means the mutator can alter the value as it’s being set, or change other states available in the object. Which one you choose depends on your preference and need; usually field access is enough.⁵

Listing 6-5. The Same Class with Property Access

import javax.persistence.*;

@Entity
public class Sample {
   int id;

   @Id
   public int getId() {
      return this.id;
   }

   public void setId(int id) {
      this.id = id;
   }
}

Here you can see one of the strengths of the annotations approach. Because the annotations are placed inline with the source code, information can be extracted from the context of the mapping in the code, allowing many mapping decisions to be inferred rather than stated explicitly – which helps to further reduce the verbosity of the annotations.

By default, the @Id annotation will not create a primary key generation strategy,⁶ which means that you, as the code’s author, need to determine what valid primary keys are. You can have Hibernate determine primary keys for you through the use of the @GeneratedValue annotation . This takes a pair of attributes: strategy and generator.

The strategy attribute must be a value from the javax.persistence.GenerationType enumeration. If you do not specify a generator type, the default is AUTO. There are four different types of primary key generators on GenerationType, as follows:

• AUTO: Hibernate decides which generator type to use, based on the database’s support for primary key generation.

• IDENTITY: The database is responsible for determining and assigning the next primary key.

• SEQUENCE: Some databases support a SEQUENCE column type. See the “Generating Primary Key Values with @SequenceGenerator” section later in the chapter.

• TABLE: This type keeps a separate table with the primary key values. See the “Generating Primary Key Values with @TableGenerator” section later in the chapter.

The generator attribute allows the use of a custom generation mechanism. Hibernate provides named generators for each of the four strategies in addition to others, such as “hilo,” “uuid,” and “guid.” If you need to use Hibernate-specific primary key generators, you risk forfeiting portability of your application to other JPA 2 environments; that said, the Hibernate generators provide more flexibility and control.

For the Book class, we are going to use the AUTO key generation strategy. Letting Hibernate determine which generator type to use makes your code portable between different databases.

@Id
@GeneratedValue(strategy=GenerationType.AUTO)
int id;

@Id
@SequenceGenerator(name="seq1",sequenceName="HIB_SEQ")
@GeneratedValue(strategy=SEQUENCE,generator="seq1")
int id;

@Id
@TableGenerator(name="tablegen",
                table="ID_TABLE",
                pkColumnName="ID",
                valueColumnName="NEXT_ID")
@GeneratedValue(strategy=TABLE,generator="tablegen")
int id;

Compound Primary Keys with @Id, @IdClass, or @EmbeddedId

While the use of single-column surrogate keys is advantageous for various reasons, you may sometimes be forced to work with business keys. When these are contained in a single column, you can use @Id without specifying a generation strategy (forcing the user to assign a primary key value before the entity can be persisted). However, when the primary key consists of multiple columns, you need to take a different strategy to group these together in a way that allows the persistence engine to manipulate the key values as a single object.

You must create a class to represent this primary key. It will not require a primary key of its own, of course, but it must be a public class, must have a default constructor, must be serializable, and must implement hashCode() and equals() methods to allow the Hibernate code to test for primary key collisions (i.e., they must be implemented with the appropriate database semantics for the primary key values).

Your three strategies for using this primary key class once it has been created are as follows:

1. Mark it as @Embeddable and add to your entity class a normal property for it, marked with @Id.

2. Add to your entity class a normal property for it, marked with @EmbeddableId.

3. Add properties to your entity class for all of its fields, mark them with @Id, and mark your entity class with @IdClass, supplying the class of your primary key class.

All these techniques require the use of an id class because Hibernate must be supplied with a primary key object when various parts of its persistence API are invoked. For example, you can retrieve an instance of an entity by invoking the Session object’s get() method, which takes as its parameter a single serializable object representing the entity’s primary key.

The use of @Id with a class marked as @Embeddable, as shown in Listing 6-6, is the most natural approach. The @Embeddable tag can be used for nonprimary key embeddable values anyway (@Embeddable is discussed in more detail later in the chapter). It allows you to treat the compound primary key as a single property, and it permits the reuse of the @Embeddable class in other tables.

One thing worth pointing out: the embedded primary key classes must be serializable (i.e., they must implement java.io.Serializable, although it’s possible you could use java.io.Externalizable as well⁷).

Listing 6-6. Using the @Idand @Embeddable Annotations to Map a Compound Primary Key: The CPKBook

package chapter06.compoundpk;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class CPKBook {
    @Id
    ISBN id;
    @Column
    String name;

    public CPKBook() {
    }

    public ISBN getId() {
        return id;
    }

    public void setId(ISBN id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String title) {
        this.name = title;
    }
}

The next most natural approach is the use of the @EmbeddedId tag. Here, the primary key class cannot be used in other tables since it is not an @Embeddable entity, but it does allow us to treat the key as a single attribute of the Account class (in Listings 6-7 and 6-8, the implementation of AccountPk is identical to that in Listing 6-6, and is thus omitted for brevity). Note that in Listings 6-7 and 6-8, the AccountPk class is not marked as @Embeddable.

Listing 6-7. Using the @Id and @Embeddable Annotations to Map a Compound Primary Key: The ISBN

package chapter06.compoundpk;

import javax.persistence.Embeddable;
import java.io.Serializable;

@Embeddable
public class ISBN implements Serializable {
    @Column(name=”group_number”) // because “group” is an invalid column name for SQL
    int group;
    int publisher;
    int title;
    int checkdigit;

    public ISBN() {
    }

    public int getGroup() {
        return group;
    }

    public void setGroup(int group) {
        this.group = group;
    }

    public int getPublisher() {
        return publisher;
    }

    public void setPublisher(int publisher) {
        this.publisher = publisher;
    }

    public int getTitle() {
        return title;
    }

    public void setTitle(int title) {
        this.title = title;
    }

    public int getCheckdigit() {
        return checkdigit;
    }

    public void setCheckdigit(int checkdigit) {
        this.checkdigit = checkdigit;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof ISBN)) return false;

        ISBN isbn = (ISBN) o;

        if (checkdigit != isbn.checkdigit) return false;
        if (group != isbn.group) return false;
        if (publisher != isbn.publisher) return false;
        if (title != isbn.title) return false;

        return true;
    }

    @Override
    public int hashCode() {
        int result = group;
        result = 31 * result + publisher;
        result = 31 * result + title;
        result = 31 * result + checkdigit;
        return result;
    }
}

Listing 6-8. Using the @EmbeddedId Annotation to Map a Compound Primary Key

package chapter06.compoundpk;

import javax.persistence.Column;
import javax.persistence.EmbeddedId;
import javax.persistence.Entity;
import java.io.Serializable;

@Entity
public class EmbeddedPKBook {
    @EmbeddedId
    EmbeddedISBN id;
    @Column
    String name;

    static class EmbeddedISBN implements Serializable {
    // looks fundamentally the same as the ISBN class from Listing 6-7
    }
}

Finally, the use of the @IdClass and @Id annotations allows us to map the compound primary key class using properties of the entity itself corresponding to the names of the properties in the primary key class. The names must correspond (there is no mechanism for overriding this), and the primary key class must honor the same obligations as with the other two techniques. The only advantage to this approach is its ability to “hide” the use of the primary key class from the interface of the enclosing entity.

The @IdClass annotation takes a value parameter of Class type, which must be the class to be used as the compound primary key. The fields that correspond to the properties of the primary key class to be used must all be annotated with @Id—note in Listing 6-9 that the getCode() and getNumber() methods of the Account class are so annotated, and the AccountPk class is not mapped as @Embeddable, but it is supplied as the value of the @IdClass annotation.

Listing 6-9. Using the @IdClassand @Id Annotations to Map a Compound Primary Key

package chapter06.compoundpk;

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.IdClass;
import java.io.Serializable;

@Entity
@IdClass(IdClassBook.EmbeddedISBN.class)
public class IdClassBook {
    @Id
    int group;
    @Id
    int publisher;
    @Id
    int title;
    @Id
    int checkdigit;
    String name;

    public IdClassBook() {
    }

    public int getGroup() {
        return group;
    }

    public void setGroup(int group) {
        this.group = group;
    }

    public int getPublisher() {
        return publisher;
    }

    public void setPublisher(int publisher) {
        this.publisher = publisher;
    }

    public int getTitle() {
        return title;
    }

    public void setTitle(int title) {
        this.title = title;
    }

    public int getCheckdigit() {
        return checkdigit;
    }

    public void setCheckdigit(int checkdigit) {
        this.checkdigit = checkdigit;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    static class EmbeddedISBN implements Serializable {
    // identical to EmbeddedISBN from Listing 6-8
    }
}

Regardless of which of these approaches we take to declare our compound primary key, the table that will be used to represent it will require the same set of columns. Listing 6-10 shows the DDL that will be generated from Listings 6-7, 6-8, and 6-9; the other table names would differ, but the DDL for each table would be the same.

Listing 6-10. The DDL Generated from the CPKBook Class

create table CPKBook (
    checkdigit integer not null,
    group_number integer not null,
    publisher integer not null,
    title integer not null,
    name varchar(255),
    primary key (checkdigit, group, publisher, title)
)

Database Table Mapping with @Table and @SecondaryTable

By default, table names are derived from the entity names. Therefore, given a class Book with a simple @Entity annotation, the table name would be “book,” adjusted for the database’s configuration.

If the entity name is changed (by providing a different name in the @Entity annotation, such as @Entity(“BookThing”)), the new name will be used for the table name. (Queries would need to use the entity name; from the user’s perspective, the table name would be irrelevant.)

The table name can be customized further, and other database-related attributes can be configured via the @Table annotation. This annotation allows you to specify many of the details of the table that will be used to persist the entity in the database. As already pointed out, if you omit the annotation, Hibernate will default to using the class name for the table name, so you need only provide this annotation if you want to override that behavior.

The @Table annotation provides four attributes, allowing you to override the name of the table, its catalog, and its schema, and to enforce unique constraints on columns in the table. Typically, you would only provide a substitute table name thus: @Table(name="ORDER_HISTORY"). The unique constraints will be applied if the database schema is generated from the annotated classes, and will supplement any column-specific constraints (see discussions of @Column and @JoinColumn later in this chapter). They are not otherwise enforced.

The @SecondaryTable annotation provides a way to model an entity bean that is persisted across several different database tables. Here, in addition to providing an @Table annotation for the primary database table, your entity can have a @SecondaryTable annotation, or a @SecondaryTables annotation, in turn, containing zero or more @SecondaryTable annotations. The @SecondaryTable annotation takes the same basic attributes as the @Table annotation, with the addition of the join attribute. The join attribute defines the join column for the primary database table. It accepts an array of javax.persistence.PrimaryKeyJoinColumn objects. If you omit the join attribute, then it will be assumed that the tables are joined on identically named primary key columns.

When an attribute in the entity is drawn from the secondary table, it must be marked with the @Column annotation , with a table attribute identifying the appropriate table. Listing 6-11 shows how a property of the Customer entity could be drawn from a second table mapped in this way.

Listing 6-11. An Example of a Field Access Entity Mapped Across Two Tables

package chapter06.twotables;

import javax.persistence.*;

@Entity
@Table(name = "customer")
@SecondaryTable(name = "customer_details")
public class Customer {
    @Id
    public int id;
    public String name;
    @Column(table = "customer_details")
    public String address;

    public Customer() {
    }
}

Columns in the primary or secondary tables can be marked as having unique values within their tables by adding one or more appropriate @UniqueConstraint annotations to @Table or @SecondaryTable’s uniqueConstraints attribute. You may also set uniqueness at the field level with the unique attribute on the @Column attribute. For example, to mark the name field in the preceding declaration as being unique, use the following:

@Entity
@Table(
   name="customer",
   uniqueConstraints={@UniqueConstraint(columnNames="name")}
)
@SecondaryTable(name="customer_details")
public class Customer {
   ...
}

Persisting Basic Types with @Basic

By default, properties and instance variables in your POJO are persistent; Hibernate will store their values for you. The simplest mappings are therefore for the “basic” types. These include primitives, primitive wrappers, arrays of primitives or wrappers, enumerations, and any types that implement Serializable but are not themselves mapped entities. These are all mapped implicitly — no annotation is needed. By default, such fields are mapped to a single column, and eager fetching is used to retrieve them (i.e., when the entity is retrieved from the database, all the basic fields and properties are retrieved⁸). Also, when the field or property is not a primitive, it can be stored and retrieved as a null value.

This default behavior can be overridden by applying the @Basic annotation to the appropriate class member. The annotation takes two optional attributes, and is itself entirely optional. The first attribute is named optional and takes a Boolean. Defaulting to true, this can be set to false to provide a hint to schema generation that the associated column should be created NOT NULL. The second is named fetch and takes a member of the enumeration FetchType. This is EAGER by default, but can be set to LAZY to permit loading on access of the value.

Lazy loading means that the values of the references aren’t actually necessarily initialized when the object is loaded by the Session. This has the potential advantage of performance – you can see if an object is persisted or not, without having to set all of its attributes – but it also means that your object might not be initialized fully at any given moment. (It’s initialized when you actually start accessing the data.) This means that for lazily loaded data, the originating Session has to be active when you access the data, or else you will get a LazyInitializationException exception.

Lazy initialization is most valuable when you’re actually loading relationships from the database. If you had a PublishingHouse object, with thousands of Books being published, you wouldn’t necessarily want to load all of the books just because you are working with the PublishingHouse reference. Therefore, you’d want the books loaded lazily (because they probably have their own references to Authors, and those authors might have more than one book, and so forth and so on, ad infinitum).

The @Basic attribute is usually omitted, with the @Column attribute being used where the @Basic annotation’s optional attribute might otherwise be used to provide the NOT NULL behavior.

Omitting Persistence with @Transient

Some fields, such as calculated values, may be used at runtime only, and they should be discarded from objects as they are persisted into the database. The JPA specification provides the @Transient annotation for these transient fields. The @Transient annotation does not have any attributes — you just add it to the instance variable or the getter method as appropriate for the entity bean’s property access strategy.

The @Transient annotation highlights one of the more important differences between using annotations with Hibernate and using XML mapping documents. With annotations, Hibernate will default to persisting all of the fields on a mapped object. When using XML mapping documents, Hibernate requires you to tell it explicitly which fields will be persisted.⁹

For our example, if we wanted to add a Date field named publicationDate, not be stored in the database to our Book class, we could mark this field transient thus:

@Transient
Date publicationDate;

If we are using a property access strategy for our Book class, we would need to put the @Transient annotation on the accessor instead.

Mapping Properties and Fields with @Column

The @Column annotation is used to specify the details of the column to which a field or property will be mapped. Some of the details are schema related, and therefore apply only if the schema is generated from the annotated files. Others apply and are enforced at runtime by Hibernate (or the JPA 2 persistence engine). It is optional, with an appropriate set of default behaviors, but is often useful when overriding default behavior, or when you need to fit your object model into a preexisting schema. It is more commonly used than the similar @Basic annotation, with the following attributes commonly being overridden:

• name permits the name of the column to be explicitly specified — by default, this would be the name of the property. However, it is often necessary to override the default behavior when it would otherwise result in an SQL keyword being used as the column name (e.g., user).

• length permits the size of the column used to map a value (particularly a String value) to be explicitly defined. The column size defaults to 255, which might otherwise result in truncated String data, for example.

• nullable permits the column to be marked NOT NULL when the schema is generated. The default is that fields should be permitted to be null; however, it is common to override this when a field is, or ought to be, mandatory.

• unique permits the column to be marked as containing only unique values. This defaults to false, but commonly would be set for a value that might not be a primary key but would still cause problems if duplicated (such as username).

We have marked up the title field of our Book entity using the @Column entity to show how three of these attributes would be applied:

@Column(name="working_title",length=200,nullable=false)
String title;

The remaining attributes, less commonly used, are as follows:

• table is used when the owning entity has been mapped across one or more secondary tables. By default, the value is assumed to be drawn from the primary table, but the name of one of the secondary tables can be substituted here (see the @SecondaryTable annotation example earlier in this chapter).

• insertable defaults to true, but if set to false, the annotated field will be omitted from insert statements generated by Hibernate (i.e., it won’t be persisted).

• updatable defaults to true, but if set to false, the annotated field will be omitted from update statements generated by Hibernate (i.e., it won’t be altered once it has been persisted).

• columnDefinition can be set to an appropriate DDL fragment to be used when generating the column in the database. This can only be used during schema generation from the annotated entity, and should be avoided if possible, since it is likely to reduce the portability of your application between database dialects.

• precision permits the precision of decimal numeric columns to be specified for schema generation, and will be ignored when a nondecimal value is persisted. The value given represents the number of digits in the number (usually requiring a minimum length of n+1, where n is the scale).

• scale permits the scale of decimal numeric columns to be specified for schema generation and will be ignored where a nondecimal value is persisted. The value given represents the number of places after the decimal point.

Modeling Entity Relationships

Naturally, annotations also allow you to model associations between entities. JPA 2 supports one-to-one, one-to-many, many-to-one, and many-to-many associations. Each of these has its corresponding annotation.

We discussed the various ways in which these mappings can be established in the tables in Chapter 5. In this section, we will show how the various mappings are requested using the annotations.

@Embeddable
public class AuthorAddress {
...
}

@Embedded
AuthorAddress address;

@Embedded
@AttributeOverrides({
    @AttributeOverride(name="address",column=@Column(name="ADDR")),
    @AttributeOverride(name="country",column=@Column(name="NATION"))
})
AuthorAddress address;

@OneToOne
Address address;

   Human dave = new Human("dave");
   Pet cat = new PetCat("Tibbles");
   dave.setPet(cat);
   session.save(dave);

@OneToOne(cascade=CascadeType.ALL)
Address address;

   @OneToMany(cascade = ALL, mappedBy = "publisher"
   @OrderBy("name ASC")
   List<Book> books;

@OneToMany(cascade = ALL,mappedBy = "publisher")
Set<Book> books;

@ManyToOne
@JoinColumn(name = "publisher_id")
Publisher publisher;

@OneToMany(cascade = ALL)
@JoinTable
Set<Book> books;

@OneToMany(cascade = ALL)
@JoinTable(
        name="PublishedBooks",
        joinColumns = { @JoinColumn( name = "publisher_id") },
        inverseJoinColumns = @JoinColumn( name = "book_id")
)
Set<Book> books;

@ManyToMany(cascade = ALL)
Set321250_4_En authors;

@ManyToMany(mappedBy = "authors")
Set<Book> books;

@ManyToMany(cascade = ALL)
@JoinTable(
        name="Books_to_Author",
        joinColumns={@JoinColumn(name="book_ident")},
        inverseJoinColumns={@JoinColumn(name="author_ident")}
)
Set<Author> authors;

Inheritance

The JPA 2 standard and Hibernate both support three approaches to mapping inheritance hierarchies into the database. These are as follows:

1. Single table (SINGLE_TABLE): One table for each class hierarchy

2. Joined (JOINED): One table for each subclass (including interfaces and abstract classes)

3. Table-per-class (TABLE_PER_CLASS): One table for each concrete class implementation

Persistent entities that are related by inheritance must be marked up with the @Inheritance annotation. This takes a single strategy attribute, which is set to one of three javax.persistence. InheritanceType enumeration values corresponding to these approaches (shown in brackets in the preceding numbered list).

@Entity
@Inheritance(strategy = SINGLE_TABLE)
@DiscriminatorColumn(
    name="DISCRIMINATOR",
    discriminatorType=INTEGER
)
@DiscriminatorValue("1")
public class Book {
...
}

@Entity
@DiscriminatorValue("2")
public class ComputerBook extends Book {
...
}

@Entity
@Inheritance(strategy = JOINED)
@DiscriminatorColumn(
    name="DISCRIMINATOR"
)
public class Book {
...
}

@Entity
@Inheritance(strategy = TABLE_PER_CLASS)
public class Book {
...
}

Other JPA 2 Persistence Annotations

Although we have now covered most of the core JPA 2 persistence annotations, there are a few others that you will encounter fairly frequently. We cover some of these in passing in the following sections.

@Temporal(TemporalType.TIME)
java.util.Date startingTime;

@ElementCollection
List<String> passwordHints;

@Lob
String title; // a very, very long title indeed

@MappedSuperclass
public class BookSuperclass {
...
}

Ordering Collections with @OrderColumn

While @OrderBy allows data to be ordered once it has been retrieved from the database, JPA 2 also provides an annotation that allows the ordering of appropriate collection types (e.g., List) to be maintained in the database; it does so by maintaining an order column to represent that order. Here’s an example:

@OneToMany
@OrderColumn(
   name="employeeNumber"
)
List<Employee> employees;

Here, we are declaring that an employeeNumber column will maintain a value, starting at 0 and incrementing as each entry is added to the list. The default starting value can be overridden by the base attribute. By default, the column can contain null (unordered) values. The nullability can be overridden by setting the nullable attribute to false. By default, when the schema is generated from the annotations, the column is assumed to be an integer type; however, this can be overridden by supplying a columnDefinition attribute specifying a different column definition string.

@Entity
@NamedQuery(
        name="findAuthorsByName",
        query="from Author where name = :author"
)
public class Author {
...
}

@javax.annotations.NamedQuery(
   name="findBooksByAuthor",
   query="from Book b where b.author.name = :author"
)
package chapter06.annotations;

Query query = session.getNamedQuery("findBooksByAuthor", Book.class);
query.setParameter("author", "Dave");
List<Book> booksByDave = query.list();
System.out.println("There is/are " + booksByDave.size()
        + " books by Dave in the catalog");

@NamedNativeQuery(
  name="nativeFindAuthorNames",
  query="select name from author"
)

@Immutable

The @Immutable annotation marks an entity as being, well, immutable. This is useful for situations in which your entity represents reference data – things like lists of states, genders, or other rarely mutated data.

Since things like states tend to be rarely changed, someone usually updates the data manually, via SQL or an administration application. Hibernate can cache this data aggressively, which needs to be taken into consideration; if the reference data changes, you’d want to make sure that the applications using it are notified or restarted somehow.

What the annotation tells Hibernate is that any updates to an immutable entity should not be passed on to the database. It’s a “safe” object; one probably shouldn’t update it very often, if only to avoid confusion.

@Immutable can be placed on a collection; in this case, changes to the collection (additions, or removals) will cause a HibernateException to be thrown.

Natural IDs

The first part of this chapter spent a lot of pages discussing primary keys, including generated values. Generated values are referred to as “artificial primary keys,” and are very much recommended¹⁸ as a sort of shorthand reference for a given row.

However, there’s also the concept of a “natural ID ,” which provides another convenient way to refer to an entity, apart from an artificial or composite primary key.

An example might be a Social Security number or a Tax Identification Number in the United States. An entity (being a person or a corporation) might have an artificial primary key generated by Hibernate, but it also might have a unique tax identifier. This might be annotated with @Column(unique=true, nullable=false, updatable=false), which would create a unique, immutable index,¹⁹ but a natural ID also provides a loadable mechanism that we’ve not seen yet in any of our previous code, plus an actual optimization.

The Session provides the concept of a loader mechanism, known as a “load access.” There are three loaders contained in Hibernate: able to load by ID, natural ID, and simple natural ID.

Loading by ID refers to an internal reference for a given instance. For example, if an object with an ID of 1 is already referred to by Hibernate, Hibernate doesn’t need to go to the database to load that object – it can look the object up through its ID, and return that reference.

A natural ID is another form of that ID; in the case of a tax identifier, the system could look it up by the actual object ID (which would be an artificial key in most cases) or by the tax ID number itself – and if the tax ID is a “natural ID,” then the library is able to look that object up internally instead of building a query for the database.

Just as there are simple identifiers and composite identifiers comprising single fields and multiple fields, respectively – there are two forms of natural ID, similarly being made up of single fields or multiple fields.

In the case of the simple IDs, the load process provides a simple load() method, with the ID in question being the parameter. If no instance with the ID exists, load() returns null. The loader also provides an alternative, a getReference() method, which will throw an exception if no object with that natural ID is in the database.

For natural IDs, there are two forms of load mechanisms; one uses the simple natural ID (where the natural ID is one and only one field), and the other uses named attributes as part of a composite natural ID.

Now let’s look at some actual code. First, let’s create a class representing an employee in Listing 6-35; our employee will have a name (everyone has a name); an artificial ID (an employee number) assigned by the database; and a natural ID, representing a manually assigned badge number.

Listing 6-35. SimpleNaturalIdEmployee.java, without Accessors, Mutators, or Ancillary Methods

package chapter06.naturalid;

import org.hibernate.annotations.NaturalId;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class SimpleNaturalIdEmployee {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    Integer id;
    @NaturalId
    Integer badge;
    String name;

    public SimpleNaturalIdEmployee() {
    }  
}

The simple natural ID is declared by annotating a single field, badge, with @NaturalId.

To use the loader mechanism, you would get a reference through the use of Session.byId(), Session.byNaturalId(), or Session.bySimpleNaturalId(), with the type of the entity being passed in. The simple loaders (for the ID and for the simple natural ID) follow the same form: you acquire the loader, then either load or get the reference, using the key value as a parameter. Let’s see how that would look, shown in Listing 6-36.

Listing 6-36. A Simple Test Showing the Use of Both ID and Natural ID Loaders

@Test
public void testSimpleNaturalId() {
    Integer id = createSimpleEmployee("Sorhed", 5401).getId();

    try (Session session = SessionUtil.getSession()) {
        Transaction tx = session.beginTransaction();

        SimpleNaturalIdEmployee employee =
                session
                        .byId(SimpleNaturalIdEmployee.class)
                        .load(id);
        assertNotNull(employee);
        SimpleNaturalIdEmployee badgedEmployee =
                session
                        .bySimpleNaturalId(SimpleNaturalIdEmployee.class)
                        .load(5401);
        assertEquals(badgedEmployee, employee);

        tx.commit();
    }
}

private SimpleNaturalIdEmployee createSimpleEmployee(String name, int badge) {
    SimpleNaturalIdEmployee employee = new SimpleNaturalIdEmployee();
    employee.setName(name);
    employee.setBadge(badge);

    try (Session session = SessionUtil.getSession()) {
        Transaction tx = session.beginTransaction();
        session.save(employee);
        tx.commit();
    }
    return employee;
}

This code creates a new employee, with a specific badge number (5401). It then uses Session.byId(SimpleNaturalIdEmployee.class) to acquire a loader for the entity, and calls load(id), with the ID returned by the createSimpleEmployee() method.

There’s an interesting thing happening here, though, that the code demonstrates without it necessarily being obvious from the code level.

When we run this method, we actually load two references – or else the test for equivalency wouldn’t make any sense.²⁰ However, if we look at the actual SQL executed in the Session, we see only one call being issued.

This is because Hibernate will cache the natural IDs in objects that it loads in a session. When we use the natural ID in the load accessor, Hibernate looks in the session cache and finds that natural ID – and knows that this is the reference for which we’re asking. It doesn’t need to go to the database because it already has it in memory.

This helps make the class more self-documenting, as well as slightly more efficient; it means that if we have a data about a person from the real world, the API is more efficient. We can find a given employee by using a naturally indexed badge number instead of relying on other indexes, even if at the database level the other indexes do come into play.

An entity with a compound natural ID merely has more fields annotated with @NaturalId. Let’s create an employee for whom a section and department are a natural ID,²¹ as shown in Listing 6-37.

Listing 6-37. An Entity with a Compound Natural ID

package chapter06.naturalid;

import org.hibernate.annotations.NaturalId;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Employee {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    Integer id;
    @NaturalId
    Integer section;
    @NaturalId
    Integer department;
    String name;

    public Employee() {
    }

    // accessors and mutators removed for brevity
}

Next, let’s look at a test that demonstrates the use of the natural ID loader, shown in Listing 6-38.

Listing 6-38. The Natural ID Loader in Action

@Test
public void testLoadByNaturalId() {
    Employee initial = createEmployee("Arrowroot", 11, 291);
    try (Session session = SessionUtil.getSession()) {
        Transaction tx = session.beginTransaction();

        Employee arrowroot = session
                .byNaturalId(Employee.class)
                .using("section", 11)
                .using("department", 291)
                .load();
        assertNotNull(arrowroot);
        assertEquals(initial, arrowroot);

        tx.commit();
    }
}

private Employee createEmployee(String name, int section, int department) {
    Employee employee = new Employee();
    employee.setName(name);
    employee.setDepartment(department);
    employee.setSection(section);
    try (Session session = SessionUtil.getSession()) {
        Transaction tx = session.beginTransaction();
        session.save(employee);
        tx.commit();
    }
    return employee;
}

This is very similar to our previous test for natural ID usage: we create an employee, and then search for the ID. The object returned by Session.byNaturalId() has a using() method that takes a field name and the field value, as opposed to using a single reference for the identifier. If we don’t include every field making up the natural ID, we’ll get an exception.

Note that we’re using the load() method; if the natural ID is not present in the database, load() will return a signal value of null.

Now let’s look at another test in Listing 6-39. This one, which uses getReference(), will throw an exception if the ID isn’t present, so we don’t need the check for null.

Listing 6-39. A Test That Uses getReference()Instead of load()

@Test
public void testGetByNaturalId() {
    Employee initial = createEmployee("Eorwax", 11, 292);
    try (Session session = SessionUtil.getSession()) {
        Transaction tx = session.beginTransaction();

        Employee eorwax = session
                .byNaturalId(Employee.class)
                .using("section", 11)
                .using("department", 292)
                .getReference();
        System.out.println(initial.equals(eorwax));
        assertEquals(initial, eorwax);

        tx.commit();
    }
}