In Chapter 1, Your First Application, we used core Hibernate ORM to map an entity class to a database table, and then we used Hibernate Search to map two of its fields to a Lucene index. By itself, this provides a lot of search functionality that would be very cumbersome to code from scratch.
However, real-world applications usually involve numerous entities, many of which should be available for searching. Entities may be associated with each other, and our queries need to understand those associations so that we can search across multiple entities at once. We might want to declare that some mappings are more relevant to a search than others, or we might want to skip indexing data under certain conditions.
In this chapter, we will start to dive deeper into the options that Hibernate Search makes available for mapping entities. As a first step, we must take a look at the API options available in Hibernate ORM. How we map our entity classes to the database influences how Hibernate Search maps them to Lucene.
When the Hibernate Search documentation
mentions different APIs for Hibernate ORM, it can be confusing. In some cases, this might refer to whether database queries are performed using an org.hibernate.Session or a javax.persistence.EntityManager object (an important part of the next chapter). However, in the context of entity mapping, this refers to the three different approaches offered by Hibernate ORM:
- Annotation-based mapping with classic Hibernate-specific annotations
- Annotation-based mapping with the Java Persistence API (JPA 2.0)
- XML-based mapping with
hbm.xmlfiles
If you have only used Hibernate ORM with its classic annotations or XML-based mappings, or if you are new to Hibernate altogether, then this may be your first exposure to JPA. In a nutshell, JPA is a specification intended to serve as the official standard for object-relational mapping and similar features.
The idea is to provide for ORM what JDBC provides for low-level database connectivity. Once a developer has learned JDBC, they can quickly work with any database driver that implements the API (for example, Oracle, PostgreSQL, MySQL, and so on). Likewise, if you understand JPA, then you should be able to easily switch between ORM frameworks, such as Hibernate, EclipseLink, and Apache OpenJPA.
In practice, different implementations often have their own quirks and proprietary extensions, which can cause transition headaches. However, a common standard does reduce the pain and learning curve dramatically.
A comparison of using the Hibernate ORM native API versus using JPA for entity mapping is shown in the following diagram:
The good news for long-time Hibernate developers is that JPA entity mapping annotations are remarkably similar to Hibernate's own annotations. In fact, the founder of Hibernate worked on the committee that developed JPA, and these two APIs have strongly influenced each other.
The less-good news, depending on your perspective, is that Hibernate ORM 4.x deprecates its own mapping annotations in favor of their JPA counterparts. Those older annotations are targeted for removal in Hibernate ORM 5.x.
The third option, XML-based mapping, is still commonly found in legacy applications. It is falling out of favor, and the Hibernate Search documentation jokes about XML being unfit for the 21st century! Of course, that is somewhat tongue-in-cheek, considering that basic Hibernate configuration still lives in a hibernate.cfg.xml or persistence.xml file. Still, the clear trend with most Java frameworks is to use annotations for configuration that is tied to a particular class,
and to use some form of text file for global configuration.
Even if you are using hbm.xml files to map your entities to the database, you can still use the Hibernate Search annotations to map those entities to Lucene indexes. The two are perfectly compatible. This is convenient if you want to add Hibernate Search to a legacy application with minimal effort, or if you have a philosophical preference for hbm.xml files even when developing new applications.
The sample code for this book includes three versions of the VAPORware Marketplace application for this chapter:
- The
chapter2subdirectory continues where Chapter 1, Your First Application left off, using JPA annotations for mapping entities to both the database and Lucene. - The
chapter2-xmlsubdirectory is a variant of the same code, modified to mix XML-based database mapping with JPA-based Lucene mapping. - The
chapter2-mappingsubdirectory uses a special API to avoid annotations altogether. This is discussed further in the Programmatic Mapping API section near the end of this chapter.
You should explore all of this example code in detail to understand the available options. However, unless otherwise noted, the code examples in this book will focus on JPA annotations for both database and Lucene mapping.
Note
When JPA annotations are used for database mapping, Hibernate Search automatically creates a Lucene identifier for fields annotated with @Id.
For whatever reason, Hibernate Search cannot do the same with Hibernate ORM's own mapping API. So when you are not using JPA to map entities to the database, you must also add the @DocumentId annotation to fields that should be used as Lucene identifiers (entities are known as
documents in Lucene terminology).