The simplicity of Hibernate's annotation support stems from using sensible defaults, as well as Hibernate's ability to infer associations and database field types by considering the Java type of each JavaBean property. When mappings are defined in XML, we must explicitly delineate the details of each property and association. With Hibernate, because annotations are embedded into code, we have the benefit of drawing hints from the code itself, which dramatically simplifies configuration efforts.

As you learned in Chapter 4, the key annotation for Hibernate persistence is @Entity. This annotation tells Hibernate that we intend to persist this class. If we were following the XML mapping approach, we would then need to define each field explicitly in the hbm.xml mapping file. With Hibernate annotations, it is necessary to define only the details that don't conform to Hibernate's default behavior.

Hibernate will look at each property's Java type and its name, and use this metadata to define a column's field type and field name, respectively. The default behavior is to assume that all POJO properties are persistable, but you can also specify this behavior explicitly by using the @Basic annotation. Using @Basic also provides you with a way to customize various persistence-related aspects, such as whether a particular property should be lazily loaded. If you don't want certain fields persisted, you need to specify that these properties are transient using the @Transient annotation.

In addition to the @Transient and @Basic annotations, you can also use the @Temporal annotation for controlling the way date or time-based properties are mapped to the database. In our Comment class, we specify the following to declare that a Date property be persisted in the database as a timestamp:

@Temporal(TemporalType.TIMESTAMP)
public Date getCreatedDate() {
    return this.createdDate;
}

This concept of sensible defaults, or convention over configuration, really reduces the amount of coding required to get a domain model up and running. And Hibernate's annotation support provides ample flexibility to override any of the default behavior, should you be so inclined. For instance, if we wanted to define a table name for our Comment class that is different from the Java class name, we could accomplish this feat by using the @Table annotation:

@Table(name = "HOGWASH")
class Comment {
    . . . (Methods Omitted)
}

Similarly, we can require that the comment property maps to the column commentText by using the @Column annotation:

@Column(name = "commentText")
public String getComment() {
    return this.commentText;
}

This level of customization is very useful, but most of the time is unnecessary and redundant (unless you are mapping your domain model to a legacy database).

Hibernate annotation support does require that you define a primary key and all of your JavaBean's associations. In our Comment class, we have added the @Id annotation above the getId() method. This annotation tells Hibernate that the id property of our Comment class is the identifier (or primary key) for our Comment entity.

Below the @Id annotation is the @GeneratedValue annotation, which specifies the way in which a given instance's identifier will be created. The default is AUTO, and in our example, this is the identifier-generation strategy Hibernate will use (since we haven't defined a strategy at all). AUTO will look at the underlying database to make the decision as to how identifiers should be created. The options are to use a sequence, an identity column, or to use a special table for generating new IDs. If you wanted to override the default behavior and use a sequence, your @GeneratedValue annotation might look like this:

@GeneratedValue(strategy=GenerationType.SEQUENCE, generator="COMMENT_ID_SEQ")

This would create a sequence named COMMENT_ID_SEQ to be used for generating new IDs for our Comment table. Hibernate offers many more options for a domain class's identifier, including UUID-based generation, or simply allowing your application to assign identifiers directly.

Associations within a domain model represent how different domain entities relate to one another. Often, these relationships can be expressed in layman's terms as parent-child relationships, meaning that one entity owns or encapsulates a collection of another entity. Within the database, associations are represented through table joins, but there is no clear analogue for representing the more hierarchical relationships we have within Java. This is where Hibernate comes in. Cascading options help to establish parent-child relationships, or more precisely, the rules for how operations such as save and delete that are applied to one entity should cascade to associated entities. This concept is often referred to as transitive persistence.

For example, within our gallery application, we would assert that ArtEntity owns a collection of Comment instances. This is logical since a Comment is attached to a particular ArtEntity instance. An end user can post a comment about a particular image, and this comment is typically relevant only to the image about which it was posted. Furthermore, if an ArtEntity instance is deleted, it doesn't make sense to keep its related Comment instances around anymore. In essence, comments are children of an ArtEntity.

Since comments can be considered children of an ArtEntity, we can assert that a save operation invoked on an ArtEntity should also cascade to any added or updated Comment instances associated to that ArtEntity instance. Additionally, should an ArtEntity be deleted, we would want the delete action to cascade to any associated Comment instances. We can represent these cascading rules using the following annotation:

@OneToMany(orphanRemoval = true, cascade = { javax.persistence.CascadeType.ALL })
public Set<Comment> getComments() {
    return comments;
}

In this case, we are setting orphanRemoval to true, which will also ensure that any dereferenced comments will also be deleted. We also specify a CascadeType of SAVE_UPDATE, which will ensure save and update operations invoked on an ArtEntity instance will be passed along to child Comment instances as well.

Hibernate allows entities, as well as association collections (a group of comments) to be implicitly cached. With caching enabled, Hibernate will first try to find an entity or collection in the cache before trying to query the database. Since loading data from the cache is far less expensive than performing a database operation, caching is another effective strategy for improving application performance.

Hibernate integrates with several caching frameworks, such as Ehcache, and provides a CacheManager interface if you want to add your own caching solution. Once integrated, caching happens implicitly, without requiring any additional coding, other than specifying caching rules for each entity and collection.

To get basic caching enabled on our domain model, we can add the following annotation to each domain entity, as well as its corresponding collections, to ensure they are appropriately cached:

@Entity
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class ArtEntity implements Serializable {

    . . . Methods Omitted . . .

    @OneToMany(orphanRemoval = true, cascade = { javax.persistence.CascadeType.ALL })
    @Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
    public Set<Comment> getComments() {
        return comments;
    }

    public void setComments(Set<Comment> comments) {
        this.comments = comments;
    }

    . . . Methods Omitted . . .

}

Specifying a read-write caching strategy ensures that Hibernate will invalidate the cache whenever a particular domain instance is updated. This prevents stale data from being stored in the cache.

There are three types of caching options for Hibernate: domain, collection, and query. Domain and collection caching are demonstrated in the preceding example, as we have specified the @Cache annotation for the top-level domain entity as well as for the comments association.

Caching details should be adjusted using the configuration file appropriate for the caching implementation you have selected. In the case of Ehcache, you can configure specifics, such as the time-to-live and cache size on a domain-by-domain basis within the ehcache.xml file.

We will cover caching strategies in more detail in Chapter 9.

For our gallery application, we require a few more classes to help provide the persistence details for all of the gallery's functionality. As a quick recap, here is an overview of our domain model, as it currently stands:

ORM solutions like Hibernate go far beyond mapping database fields to domain model instances. Object-oriented concepts, such as polymorphism, are also enabled by Hibernate and are an effective means for establishing a hierarchy of domain objects that share a set of core properties and functionality.

Rather than store an image path directly within our ArtEntity class, let's instead refactor this data into a separate base class called ArtData. We will then create three subclasses that each extend the ArtData class (and therefore share its properties) but are tailored to represent a particular type of image. We will define the following four new domain classes:

Hibernate provides four different options for implementing polymorphism:

Implicit polymorphism: This option uses the Java inheritance structure without requiring these structural details to affect the database schema. In other words, using implicit polymorphism, you will be able to query a parent class, and Hibernate will issue select queries for all tables within the specified Java class hierarchy. While this strategy allows you to leverage the polymorphic structure inherent in your Java classes without affecting the database, these types of queries can be a bit inefficient, as Hibernate must do a lot more heavy lifting to translate distinct tables into a coherent class hierarchy, without being able to effectively leverage the database. The other polymorphic strategies rely on the database to some degree to delineate the associations between classes in the Java hierarchy.

Table-per-hierarchy: This option combines all the properties of a class hierarchy into a single table, using a discriminator field to help determine which Java type is represented by each row in the database. A discriminator is simply a table column, the value of which is used to specify to which class that particular row should be associated. The advantage of this approach is that all the necessary fields for any class within the hierarchy are included in a single table, without requiring the overhead of a database join. The disadvantage is that the design is not very normalized, and for any given type, there will likely be fields that will not be utilized. This can impose limitations on your database schema, such as preventing you from being able to specify not-null constraints. Since field requirements will differ between classes in the hierarchy and they are all shared within a single table, you must simplify the schema down to the lowest common denominator.

Table-per-subclass: Using this option, each Java class in the hierarchy is represented by a different table. Properties related to the parent class are persisted to a single table. The specific properties unique to each subclass are stored within their own database tables. A particular subclass in the hierarchy is then represented through a join between the parent table and the subclass table. The advantage of this approach is that the design is clean and normalized, since shared properties are stored in a single parent table and only subclass-specific attributes are sequestered into their own subclass tables. However, although cleaner from a relational database modeling perspective, you should consider the performance hit incurred by the necessity of joining tables together.

Table-per-concrete-class: This option requires that every Java class that is not declared as abstract be represented by its own table. Subclasses are not implemented as joins between multiple tables. Instead, all the properties of each class—including those properties inherited from a parent class—are persisted to their own table. This obviously requires a bit of redundancy, as the same fields across a class hierarchy will be present in each mapped table. However, Hibernate can implement polymorphic queries more efficiently by leveraging SQL unions across all tables mapped to a particular class hierarchy. The downside is the increased verbosity and redundancy in your database schema. Furthermore, Hibernate imposes limitations on the ID-generation strategy used by tables mapped with this polymorphic approach.

Which option to use really depends on your domain model. If there isn't too much disparity across classes within your class hierarchy, then the table-per-hierarchy option probably makes the most sense. In our case, this is the strategy we will employ.

Let's take a look at the base ArtData entity:

@Entity
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(discriminatorType = DiscriminatorType.STRING)
@DiscriminatorValue("GENERIC")
public class ArtData implements DomainObject {

    private Long id;
    private byte[] picture;
    private Integer version;

    public ArtData() {
    }

    public ArtData(byte[] picture) {
        this.picture = picture;
    }

    @Id
    @GeneratedValue
    public Long getId() {
        return id;
    }

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

    public byte[] getPicture() {
        return picture;
    }

    public void setPicture(byte[] picture) {
        this.picture = picture;
    }

    @Version
    public Integer getVersion() {
        return version;
    }

    public void setVersion(Integer version) {
        this.version = version;
    }

}

Much of this class should look familiar. You will notice the standard JavaBean conventions, as well as the core Hibernate annotations. Let's focus on the annotations that enable the inheritance in our model.

The @Inheritance annotation tells Hibernate that we want to use inheritance and that we are defining our base class.

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)

We are also specifying that we intend to use the table-per-hierarchy strategy (meaning that we want to persist all the fields in the entire hierarchy within a single table).

The @DiscriminatorColumn annotation provides Hibernate with the details about our discriminator. As mentioned earlier, the discriminator provides Hibernate with the clues it needs to infer to which Java type a particular database row corresponds. In our example, we are defining our discriminator column to be a String type. We could also use a char or an Integer.

Last, we define the discriminator value that each type will use through the @DiscriminatorValue annotation. In the case of the ArtData base class, we specify a value of GENERIC. So, for each ArtData instance that is persisted to the database, Hibernate will set the discriminator column to a value of GENERIC.

Next, we must define the classes that extend from our ArtData base class. Each class is fairly similar to one another in our scenario, but inheritance provides a clean way to classify the different types of images within our gallery application. Furthermore, this approach also provides future extension points, should we need to define additional metadata that only relates to a particular image type, such as a thumbnail aspect ratio or archival details for our ArtData_Storage class.

Here's our ArtData_Thumbnail class:

@Entity
@DiscriminatorValue("THUMBNAIL")
public class ArtData_Thumbnail extends ArtData {

    public ArtData_Thumbnail(byte[] picture) {
        this.setPicture(picture);
    }

    public ArtData_Thumbnail() {
    }

}

This is a fairly straightforward class. Notice, however, that we've set a discriminator value of THUMBNAIL.

Let's look at our ArtEntity class again, now with all of our refactorings applied:

@Entity
public class ArtEntity implements DomainObject {

    private Long id;
    private Integer version;
    private ArtData_Gallery galleryPicture;
    private ArtData_Storage storagePicture;
    private ArtData_Thumbnail thumbnailPicture;
    private Set<Category> categories = new HashSet();
    private Set<Comment> comments = new HashSet();

    public ArtEntity() {
    }

@Id
    @GeneratedValue
    public Long getId() {
        return id;
    }

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


    @Version
    public Integer getVersion() {
        return version;
    }

    public void setVersion(Integer version) {
        this.version = version;
    }

    @OneToOne(cascade = CascadeType.ALL)
    @JoinColumn()
    public ArtData_Gallery getGalleryPicture() {
        return galleryPicture;
    }

    public void setGalleryPicture(ArtData_Gallery pic) {
        this.galleryPicture = pic;
    }

    @OneToOne(cascade = CascadeType.ALL)
    @JoinColumn()
    public ArtData_Storage getStoragePicture() {
        return storagePicture;
    }

    public void setStoragePicture(ArtData_Storage pic) {
        this.storagePicture = pic;
    }

    @OneToOne(cascade = CascadeType.ALL)
    @JoinColumn()
    public ArtData_Thumbnail getThumbnailPicture() {
        return thumbnailPicture;
    }

    public void setThumbnailPicture(ArtData_Thumbnail pic) {
        this.thumbnailPicture = pic;
    }

@ManyToMany(mappedBy = "artEntities")
    public Set<Category> getCategories() {
        return categories;
    }

    @OneToMany(orphanRemoval = true, cascade = { javax.persistence.CascadeType.ALL })
    @Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
    public Set<Comment> getComments() {
        return comments;
    }

    public void setComments(Set<Comment> comments) {
        this.comments = comments;
    }

}

Notice that we have now defined a few one-to-one relationships for our thumbnailPicture, galleryPicture, and storagePicture properties. To simplify our code, we defined three separate one-to-one associations. However, we could have also chosen to put all the ArtData entities into a single collection, with a generic type of the ArtData base class. Since each image type is represented by a different subclass, it would be easy to differentiate between the different image types.

Also, notice that we have defined a many-to-many association to the Category class for the categories property. We have added the mappedBy hint here to indicate that the inverse side of this relationship is referenced by the artEntities property in the Comment class. For bidirectional many-to-many associations, we need to tell Hibernate which side of the collection is the owner. By adding the mappedBy attribute to the Comment class, we are asserting that the Category class owns the relationship.

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

      Category category = (Category) o;
     if (categoryName != null ?
             !categoryName.equals(category.categoryName) : category.categoryName != null) {
         return false;
     } else {
         return true;
     }
 }

 @Override
 public int hashCode() {
     return categoryName != null ? categoryName.hashCode() : 0;
 }