To begin using Dozer, we first need to add the necessary dependencies to our Maven pom.xml file:

<!--Dozer -->
        <dependency>
            <groupId>net.sf.dozer</groupId>
            <artifactId>dozer</artifactId>
            <version>5.2.2</version>
        </dependency>

This will provide all the necessary JARs required for Dozer integration. Once this snippet is added to your pom.xml, you will likely need to run mvn install in order to download the necessary dependencies into your local Maven repository.

Before we can go any further, we need to define our DTO classes. Typically, DTOs are similar to their corresponding domain classes, but are simpler in nature. By removing bidirectional associations, circular references, and unnecessary properties, a DTO class can reduce the complexity in a marshaling strategy or a remoting implementation.

Let's define our ArtEntityDTO class:

package com.prospringhibernate.gallery.dto;

import java.net.URL;
import java.util.Date;
import java.util.HashSet;
import java.util.Set;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "artEntity")
public class ArtEntityDTO {

    private Long id;
    private String title;
    private String subTitle;
    private Date uploadedDate;
    private String displayDate;
    private Integer width;
    private Integer height;
    private String media;
    private String description;

private String caption;
    private String galleryURL;
    private String storageURL;
    private String thumbnailURL;
    private Boolean isGeneralViewable;
    private Boolean isPrivilegeViewable;
    private Set<CommentDTO> comments = new HashSet<CommentDTO>();

    public Long getId() {
        return id;
    }

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

    public String getTitle() {
        return title;
    }

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

    public String getSubTitle() {
        return subTitle;
    }

    public void setSubTitle(String subTitle) {
        this.subTitle = subTitle;
    }

    public Date getUploadedDate() {
        return uploadedDate;
    }

    public void setUploadedDate(Date uploadedDate) {
        this.uploadedDate = uploadedDate;
    }

    public String getDisplayDate() {
        return displayDate;
    }

    public void setDisplayDate(String displayDate) {
        this.displayDate = displayDate;
    }

    public Integer getWidth() {
        return width;
    }

public void setWidth(Integer width) {
        this.width = width;
    }

    public Integer getHeight() {
        return height;
    }

    public void setHeight(Integer height) {
        this.height = height;
    }

    public String getMedia() {
        return media;
    }

    public void setMedia(String media) {
        this.media = media;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getCaption() {
        return caption;
    }

    public void setCaption(String caption) {
        this.caption = caption;
    }

    public String getGalleryURL() {
        return galleryURL;
    }

    public void setGalleryURL(String galleryURL) {
        this.galleryURL = galleryURL;
    }

    public String getStorageURL() {
        return storageURL;
    }

    public void setStorageURL(String storageURL) {
        this.storageURL = storageURL;
    }

public String getThumbnailURL() {
        return thumbnailURL;
    }

    public void setThumbnailURL(String thumbnailURL) {
        this.thumbnailURL = thumbnailURL;
    }

    public Boolean getGeneralViewable() {
        return isGeneralViewable;
    }

    public void setGeneralViewable(Boolean generalViewable) {
        isGeneralViewable = generalViewable;
    }

    public Boolean getPrivilegeViewable() {
        return isPrivilegeViewable;
    }

    public void setPrivilegeViewable(Boolean privilegeViewable) {
        isPrivilegeViewable = privilegeViewable;
    }

    public Set<CommentDTO> getComments() {
        return comments;
    }

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

At first glance, the ArtEntityDTO looks very similar to the ArtEntity domain class. On closer inspection, however, you will notice that we've removed a few references. We no longer have a dependency on any of the classes in the ArtData hierarchy. Instead, we have replaced references to a particular ArtData subclass with a String that will contain a URL to the relevant image (instead of a wrapper class that contains image metadata and the binary image data itself).

The ArtEntityDTO also omits the many-to-many association to the Category domain class. This means we won't be able to directly access the associated categories of a particular ArtEntity instance. In our application, this isn't a critical requirement. We will be able to access the ArtEntity instances associated with a particular Category by accessing a Category instance directly and navigating to its child ArtEntity instances.

Notice that our ArtEntityDTO still includes a comments property. This property is represented by a java.util.Set, but rather than containing Comment domain class instances, it holds CommentDTO instances. We haven't defined our CommentDTO class yet, but like the ArtEntityDTO, this class will serve as a simplified representation of a Comment entity.

One additional detail we added to the ArtEntityDTO is the @XmlRootElement(name = "artEntity") annotation. One use case for a DTO class is to simplify the marshaling process to XML or JSON. @XMLRootElement is a Java Architecture for XML Binding (JAXB) annotation—a standard for object-to-XML marshaling. Later in this chapter, we will leverage JAXB for rendering an XML representation of our domain classes, as part of a REST web service.

Although the differences between the ArtEntity domain class and the ArtEntityDTO are not significant, the discrepancies are intricate enough to require a fairly complex mapping strategy. For instance, consider what would be required to map a collection of Comment instances to a collection of CommentDTO instances. Luckily, Dozer is able to handle the task of mapping and converting between these classes without requiring much work.

Next, let's take a look at the CommentDTO class:

@XmlRootElement(name = "comment")
public class CommentDTO {

    private Long id;
    private String comment;
    private Date commentDate;
    private String firstName;
    private String lastName;
    private String emailAddress;
    private String telephone;

    public Long getId() {
        return id;
    }

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

    public String getComment() {
        return comment;
    }

    public void setComment(String comment) {
        this.comment = comment;
    }

    public Date getCommentDate() {
        return commentDate;
    }

    public void setCommentDate(Date commentDate) {
        this.commentDate = commentDate;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getEmailAddress() {
        return emailAddress;
    }

    public void setEmailAddress(String emailAddress) {
        this.emailAddress = emailAddress;
    }

    public String getTelephone() {
        return telephone;
    }

    public void setTelephone(String telephone) {
        this.telephone = telephone;
    }

}

The differences between the Comment domain class and the CommentDTO class are fairly trivial. We have removed the commentedArt property, which would create a circular reference between the ArtEntityDTO and the CommentDTO (provided that we changed the property type from ArtEntity to ArtEntityDTO).

Now that we have defined our DTO classes, let's create the mapping configuration that instructs Dozer how to map one class to another. Dozer provides a DozerBeanMapperFactoryBean abstraction for Spring, which is a factory bean that will help to create the Dozer mapper. The Dozer mapper relies on an XML configuration file to learn the rules that define how the properties of one class are mapped to the properties of another class.

First, let's add the appropriate configuration to our spring-master.xml file:

<bean class="org.dozer.spring.DozerBeanMapperFactoryBean">
    <property name="mappingFiles" value="classpath*:/dozer-mapping.xml"/>
</bean>

This bean is actually quite flexible, and supports additional properties for defining custom converters, event listeners, and other Dozer extension points. You can learn more about the capabilities of the DozerBeanMapperFactoryBean on the Dozer website.

In the preceding configuration, we have specified that the Dozer mapping files should be located on the classpath, under the name dozer-mapping.xml. This XML file defines the default behavior for Dozer as well as the rules for mapping between one class and another. Let's take a look at our Dozer mapping configuration:

<?xml version="1.0" encoding="UTF-8"?>
<mappings xmlns="http://dozer.sourceforge.net"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="http://dozer.sourceforge.net

http://dozer.sourceforge.net/schema/beanmapping.xsd">

    <configuration>
        <stop-on-errors>true</stop-on-errors>
        <date-format>MM/dd/yyyy HH:mm</date-format>
        <wildcard>true</wildcard>
    </configuration>

    <mapping>
        <class-a>com.prospringhibernate.gallery.domain.ArtEntity</class-a>
        <class-b>com.prospringhibernate.gallery.dto.ArtEntityDTO</class-b>
        <field>
            <a>galleryPicture.url</a>
            <b>galleryURL</b>
        </field>
        <field>
            <a>storagePicture.url</a>
            <b>storageURL</b>
        </field>
        <field>
            <a>thumbnailPicture.url</a>
            <b>thumbnailURL</b>
        </field>
    </mapping>

    <mapping>
        <class-a>com.prospringhibernate.gallery.domain.Category</class-a>
        <class-b>com.prospringhibernate.gallery.dto.CategoryDTO</class-b>
    </mapping>

    <mapping>
        <class-a>com.prospringhibernate.gallery.domain.Comment</class-a>
        <class-b>com.prospringhibernate.gallery.dto.CommentDTO</class-b>
    </mapping>

    <mapping>
        <class-a>com.prospringhibernate.gallery.domain.Exhibition</class-a>
        <class-b>com.prospringhibernate.gallery.dto.ExhibitionDTO</class-b>
    </mapping>

</mappings>

Let's step through the important components of this configuration. First is a configuration block toward the top of the file. This section specifies the default global mapping behavior for Dozer. We define a default date-format and also set the wildcard behavior to true. The wildcard behavior determines whether Dozer will attempt to automatically map all obvious properties by default. For instance, if wildcard is set to true and both mapped classes share properties with the same name, Dozer will attempt to map these properties automatically. This feature can be overridden within specific mapping rules. If wildcard is left active, you can still omit certain properties from being mapped by using the field-exclude element. For instance, if we wanted to prevent our subTitle property from being mapped, we could add the following snippet to the ArtEntity mapping configuration:

<field-exclude>
    <a>subTitle</a>
    <b>subTitle</b>
</field-exclude>

The mapping configuration for a pair of classes is straightforward. Each mapping definition is encapsulated in a mapping XML block. Within each block, we include a class-a element and a class-b element, specifying the respective classes to be mapped. Although the configuration is sequential in nature, keep in mind that Dozer is bidirectional by default. This means that rules defining how we map from an ArtEntity class to an ArtEntityDTO class can also be applied in reverse to map from a DTO class back to a domain class. You can require that mapping rules be applied in only a single direction by adding the attribute type="one-way" to a mapping element.

In the case of our ArtEntity to ArtEntityDTO mapping, most of the details will be implicit since the property names are fairly consistent between the two classes. Although the comments collection property on the ArtEntityDTO contains elements of a different type, Dozer will automatically convert each Comment element within the ArtEntity.comments collection to an instance of CommentDTO by applying the mapping rules specified.

The only exception we need to explicitly define in our ArtEntity mapping rules is the conversion between the three ArtData references into String properties. In this example, the names of the properties are not in sync between the two classes, so we need to define a field element for each ArtData reference. Notice that we are not only mapping properties with different names, but we are also extracting the value of a subproperty and using this value for the converted DTO property. For instance, in defining the mapping rule to convert the ArtEntity.galleryPicture property of type ArtData_Gallery to the ArtEntityDTO.galleryURL property, we attempt to extract the url property from the galleryPicture property to use as the value for the galleryURL. This is accomplished by specifying a nested expression in the Dozer configuration:

<field>
            <a>galleryPicture.url</a>
            <b>galleryURL</b>
        </field>

The value of element a specifies a nested property, and the value of element b simply defines the property directly. Dozer is very flexible in this regard and supports nested properties as well as indexed properties when using arrays or collections.

With the configuration details out of the way, let's try to do some mapping! The easiest way to verify that everything is working properly is to start with a test. As discussed in Chapter 8, let's create an integration test. It would actually be fairly trivial to define a unit test, as our dependencies are fairly minimal. However, since we have specified some of our Dozer setup using Spring configuration, it's a little easier to let Spring take care of the details.

Here is a simple test that will help ascertain whether our Dozer mapping process is working as it should:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {"classpath:/META-INF/spring/spring-master.xml"})
public class DozerMappingTest {

    private Mapper dozerMapper;
    private ArtEntity artEntity;

    public Mapper getDozerMapper() {
        return dozerMapper;
    }

    @Autowired
    public void setDozerMapper(Mapper dozerMapper) {
        this.dozerMapper = dozerMapper;
    }

    @Before
    public void preMethodSetup() {

        Comment comment = new Comment();
        comment.setComment("This is a test comment. What a cool picture!");
        comment.setCommentDate(new Date());
        comment.setEmailAddress("[email protected]");
        comment.setFirstName("John");
        comment.setLastName("Doe");
        comment.setTelephone("212-555-1212");

        ArtData_Thumbnail thumbnail = new ArtData_Thumbnail();
        thumbnail.setId(1L);

        artEntity = new ArtEntity();
        artEntity.setCaption("caption test");
        artEntity.addCommentToArt(comment);
        artEntity.setDescription("A very cool picture of trees.");
        artEntity.setDisplayDate("October 10th");
        artEntity.setHeight(500);
        artEntity.setWidth(300);
        artEntity.setSubTitle("This is a subtitle for a picture");
        artEntity.setTitle("This is a title of a picture");

artEntity.setThumbnailPicture(thumbnail);

    }

    @Test
    public void testMappingArtEntity() {
        ArtEntityDTO artEntityDTO = this.getDozerMapper().map(artEntity, ArtEntityDTO.class);
        Assert.assertEquals(artEntity.getTitle(), artEntityDTO.getTitle());
        Assert.assertTrue(artEntityDTO.getComments().size() > 0);
        Assert.assertTrue("artData_thumbnail should be a string value",
                                              artEntityDTO.getThumbnailURL().length() > 0);
    }

}

You should recognize much of the boilerplate detail from earlier testing examples. Notice that we specify our top-level Spring configuration file using the @ContextConfiguration annotation. Most of the code in this class is included in the preMethodSetup() method, which is annotated with the @Before annotation to ensure it is called before our test method (which is annotated with @Test). In preMethodSetup(), we instantiate an ArtEntity domain class, setting basic properties and associations. Once we have configured our ArtEntity instances, the testMappingArtEntity() method is called, which contains the code for our actual test. In this method, we call the map method on our Mapper instance, which was injected by Spring via autowiring into the dozerMapper private property. The Dozer mapper does all the real heavy lifting for us. We pass in our artEntity instance, which was set up in the previous step, along with the class type to which we want to map the instance, and Dozer converts our ArtEntity class into an ArtEntityDTO.

To ensure that all went according to plan, we assert a few properties on the mapped ArtEntityDTO instance, verifying that the correct values are present. Although the mapping process is deceptively simple, there is quite a bit going on behind the scenes. We now have an effective and reliable approach for converting Hibernate domain classes into simpler DTO classes.

For applications in which the likelihood that two simultaneous transactions should conflict is fairly remote, Hibernate and JPA offer support for Optimistic Locking. Optimistic Locking does not pose any constraints on accessing or writing data. Instead, the version field of the relevant domain entity is verified before the current transaction is committed. If the value of the version field does not match the value of the row (representing this particular domain entity) in the database, this implies that a concurrent transaction has modified the domain entity.

When a version field is added to a domain class (by annotating a field with @Version), Hibernate will automatically increment the value of this field on a particular domain entity whenever it is updated. We can then leverage this feature to help prevent entities that were modified in a concurrent transaction from having their state reverted. In other words, a typical update operation is enhanced with a SQL condition to check the version field, such that updating the name property of an ArtEntity domain entity would become:

UPDATE artentity SET name = 'foo', version = 8 where id = 4 and version = 7;

Optimistic Locking is beneficial in that it does not pose any significant constraints that could limit scalability, such as database locks. However, this strategy will throw an exception if a version mismatch is detected, which means that application developers must re-attempt the transaction, while trying to reconcile the conflicting data.

When the potential for simultaneous modifications are more likely, you may want to consider leveraging Pessimistic Locking instead. Pessimistic Locking uses database locks, and therefore poses greater risk for scalability and database deadlock. The chief advantage of Pessimistic Locking is that it limits concurrent access or modification of domain entities, which can help maintain data consistency without complicating application code. Keep in mind, however, that the longer a pessimistic lock is held, the greater the impact to scalability.

Locking an entity is relatively simple in JPA 2.0. You can acquire a pessimistic lock when loading a particular entity. You can also explicitly lock an entity after it has already been loaded, by calling lock or refresh on the entityManager instance.

For example, to acquire a pessimistic write lock (which is an exclusive lock) while loading a particular ArtEntity instance, we could do the following:

ArtEntity artEntity = entityManager.find(ArtEntity.class, 7, LockModeType.PESSIMISTIC_WRITE)

If we had previously loaded an ArtEntity instance, and now wanted to acquire a pessimistic read lock (which represents a shared lock), we could use the following approach:

entityManager.lock(artEntity, LockModeType.PESSIMISTIC_READ)

While it is possible to obtain multiple, concurrent read locks, there can only be a single pessimistic write lock.

At the center of Lucene's indexing API is the Document class. Similar to the concept of a database table, a Document is composed of Fields, each of which contains text data extracted from the original content intended to be indexed. Unlike a database, Lucene documents are denormalized. There is no concept of joining, as data relationships are not indicative of IR. Instead, you can think of documents as containers—a means for organizing content so that it can be effectively searched against later.

Each Field in a Lucene Document typically represents a particular component of the content you wish to search. For example, if you wanted to index your personal music library, you would likely define a document with fields for an audio track, the track's album, the track's artist, the file name for the track, your notes about the track, the album's release date, and so on. To assist with the indexing process, Lucene provides a set of Analyzers. An Analyzer helps to break down and filter the content for each particular field, extracting a stream of tokens. For instance, since it's reasonable that your notes on a particular album could contain several paragraphs of text, you would need to break down this content into words. You might then want to break down these words into their roots, allowing you to be able to find notes by using the word listen, even if a particular note actually contained the word listens or listening. This process is called stemming, and helps to break down words into their root forms. An analyzer might also filter out superfluous content, such as removing stop words, such as the and a.

The individual tokens that an analyzer extracts are known as terms. Terms are the foundational elements that comprise an Index, and therefore are also the primary component of a search query. Lucene uses an inverted index to optimize the manner in which content is found. An inverted index uses the tokens extracted in the analyzer step of the indexing process as the lookup keys for a particular piece of content. This sort of approach is more conducive to searching, as the emphasis for lookup is placed on the individual terms or words a user might want to search for, rather than the content itself. Additionally, Lucene is able to track the frequency of a particular token, its position in relation to other tokens, and its offset within the original content from which it was extracted. This metadata is extremely valuable for a host of search features.

Lucene provides a series of options to customize how a particular field is indexed. For instance, it might be more ideal for some fields to be tokenized, while others should have their content preserved in its original form. In the music library example, you would probably want to tokenize the notes field, since you would want to be able to search for a particular word or phrase contained in your notes. However, you would not want to tokenize the track's file name, as this data makes sense only as a complete, unmodified unit.

Lucene also allows you to specify whether the original content for a particular field is stored. For instance, while you might not want to tokenize a track's file name, you would definitely want to store this data. Then when a particular document is returned as part of a search result list, you could access the file name directly so that the application could work with this data (for instance, to play the track or locate it on your file system).

Lucene includes a powerful querying API, providing a flexible way to specify the fields and terms for which to search, along with the ability to define Boolean and grouping expressions.

The simplest Lucene query might look like the following:

cupcake

This would search for the term cupcake on the default field. The default field is typically specified in the QueryParser, a Lucene class used to parse a user-defined query expression into a Query instance.

More often, a Lucene query will target one or more fields, such as in the following example:

notes:cupcake AND album:Pepper

This will return all documents in which the word cupcake is contained in the notes field and the word Pepper is contained in the album field. It is also possible to define this query as follows:

+notes:cupcake +album:Pepper

As you can see, you can define Boolean AND expressions by using the + prefix or by using the AND keyword. In Lucene, a Boolean OR is the default, so you can simply specify multiple expressions together:

notes:cupcake album:Pepper

Or you can explicitly include the OR keyword:

notes:cupcake OR album:Pepper

If you want to insist that a search should not include a particular term, you can prefix it with a minus (-) character. For example, if you wanted to ensure that your search results did not contain any tracks played by the Beatles, you could use the following query:

notes:cupcake AND album:Pepper -artist:"The Beatles"

This query will look for a note containing the word cupcake and an album containing the word Pepper, but the track artist can't be The Beatles. Notice the quotes around "The Beatles" to indicate that the artist field must match the entire phrase. So, if the artist name was specified as just Beatles, you could still end up with a Beatles track in your search results. To prevent this scenario, you could just use Beatles, without the quotation marks.

But what if you wanted to ensure that a misspelled artist attribution on a track in your library wouldn't affect the intention of your searches? To address this problem, you can use a tilde (˜) character, which lets Lucene know that you want to allow a fuzzy match:

(track:"Fixing a Hole" OR track:"Hey Jude") AND artist:Beatles˜

This query expresses your intention for a fuzzy search on the artist field. Now, even if the artist attribution in your library is spelled as "Beetles," it will likely be included in your search results. Notice also the use of parentheses to group the first part of the query. This grouping specifies that the query should return tracks that match either title, provided they both are by the artist Beatles.

If you wanted to ensure that your results contain only tracks released within a particular date range, you could take advantage of Lucene's date-range querying capability:

artist:Rol* AND releaseDate:[5/18/1975 TO 5/18/2010]

This query will find any track with a release date between May 18, 1975, and May 18, 2010, as long as the artist name starts with Rol. The wildcard modifier (*) indicates that you want to match an artist given the specified prefix.

The preceding query examples should give you a sense of some of the things possible with Lucene query expressions. You will learn shortly how to parse these expressions into a Lucene Query. Of course, it's also possible to define queries programmatically, and doing so can often provide you with more flexibility. However, defining an expression using some of the conventions shown in these examples can give your design more clarity.

Let's consider the search requirements of our image gallery application. Users will likely want to be able to find images by caption, author, title, or description, and possibly filter results by category or tag. We also want to display results in terms of relevance, not just sorted alphabetically or by date. What constitutes relevance is an important concern for search features, as ultimately, the success of search is based on how expediently users are able to find what they are looking for.

To begin integrating Hibernate Search into our art gallery application, we must first update our Maven pom.xml to include the necessary dependencies. This is easily accomplished by adding the following snippet to our pom.xml:

<!--Hibernate Search-->
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-search</artifactId>
    <version>3.2.1.Final</version>
</dependency>

Hibernate Search expects a few key configuration properties in order to define some of the basic defaults, such as the location of the Lucene index. These properties can be specified within the persistence.xml file. The following represents the key properties to set in order to bootstrap our Hibernate Search integration. The important new attributes are in bold.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://java.sun.com/xml/ns/persistence

http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
                          version="2.0">

<persistence-unit name="persistenceUnit" transaction-type="RESOURCE_LOCAL">
        <provider>org.hibernate.ejb.HibernatePersistence</provider>
        <properties>
            <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
            <property name="hibernate.hbm2ddl.auto" value="create"/>
            <property name="hibernate.cache.use_second_level_cache" value="true"/>
            <property name="hibernate.cache.provider_class"
                                 value="net.sf.ehcache.hibernate.SingletonEhCacheProvider"/>
            <property name="hibernate.search.default.directory_provider"
                                 value="org.hibernate.search.store.FSDirectoryProvider"/>
            <property name="hibernate.search.default.indexBase" value="./lucene/indexes"/>
            <property name="hibernate.search.default.batch.merge_factor" value="10"/>
            <property name="hibernate.search.default.batch.max_buffered_docs" value="10"/>
        </properties>
    </persistence-unit>

</persistence>

This configuration provides Hibernate Search with some of the key details required to get things rolling, such as which directory provider to use (a Lucene configuration that delineates the strategy for managing and storing the index) and where the index is located.

With the configuration out of the way, we need to design our Lucene index, specifying the fields within the Lucene document and defining how these fields map to the properties within each of our domain classes. Hibernate Search is flexible in this regard, and allows you to fine-tune the requirements for every field. However, following convention over configuration, the framework includes sensible defaults, so you need to deal with only special requirements.

By default, each domain class that is indexed will be mapped to its own index. Each domain class property will map to a Lucene field of the same name, unless you choose to override this default. It is also possible to define more than one field for a particular domain class property, which is useful if you need to use multiple indexing strategies for the same domain class property. For example, you might want to have one field that is not tokenized but stores the content in its original form, while another field tokenizes the content.

To map your domain class properties to a Lucene index, Hibernate Search offers a set of specialized annotations that complement the JPA annotations we used to define our Hibernate mappings. Let's take a look at the ArtEntity domain class and add Hibernate Search annotations to establish our Lucene mappings:

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

    private Long id;
    private String title;
    private String subTitle;
    private String uploadedDate;
    private String displayDate;
    private Integer width;
    private Integer height;
    private String media;
    private String description;
    private String caption;
    private ArtData_Gallery galleryPicture;
    private ArtData_Storage storagePicture;
    private ArtData_Thumbnail thumbnailPicture;
    private Boolean isGeneralViewable;
    private Boolean isPrivilegeViewable; // can be seen by logged-in non-administrators (special visitors)
    private Set<Category> categories = new HashSet<Category>();
    private Set<Comment> comments = new HashSet<Comment>();

    private Integer version;

    public ArtEntity() {
    }

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

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

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

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

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

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

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

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

    @Field(index = Index.TOKENIZED, store=Store.YES)
    @Boost(2.0f)
    public String getTitle() {
        return title;
    }

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

@Field(index = Index.TOKENIZED, store=Store.YES)
    public String getSubTitle() {
        return subTitle;
    }

    public void setSubTitle(String subTitle) {
        this.subTitle = subTitle;
    }

    @Field(index = Index.TOKENIZED, store=Store.NO)
    public String getMedia() {
        return media;
    }

    public void setMedia(String media) {
        this.media = media;
    }

    @Field(index = Index.UN_TOKENIZED, store=Store.YES)
    @DateBridge(resolution = Resolution.MINUTE)
    public String getUploadedDate() {
        return uploadedDate;
    }

    public void setUploadedDate(String uploadedDate) {
        this.uploadedDate = uploadedDate;
    }

    public String getDisplayDate() {
        return displayDate;
    }

    public void setDisplayDate(String displayDate) {
        this.displayDate = displayDate;
    }

    @Field(index = Index.UN_TOKENIZED, store=Store.YES)
    public Integer getWidth() {
        return width;
    }

    public void setWidth(Integer width) {
        this.width = width;
    }

    @Field(index = Index.UN_TOKENIZED, store=Store.YES)
    public Integer getHeight() {
        return height;
    }

public void setHeight(Integer height) {
        this.height = height;
    }

    @Field(index = Index.TOKENIZED, store=Store.NO)
    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    @Field(index = Index.TOKENIZED, store=Store.NO)
    public String getCaption() {
        return caption;
    }

    public void setCaption(String caption) {
        this.caption = caption;
    }

    public Boolean getGeneralViewable() {
        return isGeneralViewable;
    }

    public void setGeneralViewable(Boolean generalViewable) {
        isGeneralViewable = generalViewable;
    }

    public Boolean getPrivilegeViewable() {
        return isPrivilegeViewable;
    }

    public void setPrivilegeViewable(Boolean privilegeViewable) {
        isPrivilegeViewable = privilegeViewable;
    }

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

    public void setCategories(Set<Category> categories) {
        this.categories = categories;
    }

    @ContainedIn
    @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;
    }

}

The Hibernate Search annotations are fairly intuitive, given the Lucene concepts introduced earlier. Let's examine the additions to this class, one at a time.

First, we need to annotate a class with the @Indexed annotation in order for it to be considered for indexing. Next, Hibernate Search requires that the identifier of a domain class be annotated with @DocumentId. The document ID is used by Hibernate Search to bridge the Lucene and Hibernate worlds. In each index, Lucene stores a Hibernate entity's full class name as well as its identifier. Together, they form the basis for querying in Hibernate Search, and allow a list of documents returned by a Lucene query to be exchanged for a list of active Hibernate entities.

Unless a domain class property is annotated with the @Field annotation, it will not be indexed. The @Field annotation specifies that a particular domain class property be included in the Lucene index. The annotation takes a few parameters, including the ability to override the name of the field. Of most importance, however, are the index and store attributes. These parameters tell Lucene how to configure the field.

As noted earlier, a field can be tokenized, which will extract the contents of a particular property into a stream of tokens, leveraging a particular analyzer to filter out superfluous words, perform stemming, insert synonyms, and possibly perform a range of other options, depending on the analyzer used. A field can also be stored, which means that the original content will be inserted into the Lucene index. Storing a field can increase the size of the index, so it is rarely a good idea for large blocks of text. However, fields containing data that may need to be displayed by the application—such as a title, file name, or a business identifier—should be marked as stored. Let's look at a few examples:

You probably also noticed the use of the @DateBridge annotation. Since Lucene typically only manages text within its index, Hibernate Search includes a bridge strategy as way to convert nontext data into a String (and possibly back again). Hibernate Search will use the appropriate built-in bridges for mapping fields such as integers and longs, but for more complex data types, you can leverage a custom bridge or use one of the bridges provided by the framework. For example, we can map our uploadedDate property in the following way:

@Field(index = Index.UN_TOKENIZED, store=Store.YES)
    @DateBridge(resolution = Resolution.MINUTE)
    public Date getUploadedDate() {
        return uploadedDate;
    }

This mapping parameterizes the @DateBridge so that the date value is converted to text that can be lexicographically sorted. The date is stored within the Lucene index has a resolution of a minute. For performance reasons, you generally want to use the largest resolution setting your application can support (for instance, prefer a resolution of Minute over Second, or better yet, Day rather than Minute or Hour).

The @Boost annotation can be used to boost the weighting of a particular field within the Lucene index. For instance, to have the title field be twice as relevant as the description field, we can specify a boost factor of 2.0:

@Field(index = Index.TOKENIZED, store=Store.YES)
    @Boost(2.0f)
    public String getTitle() {
        return title;
    }

It is also possible to specify boost factors within a query, but in cases where you want a consistent boost weighting, the @Boost annotation can come in handy.

As we mentioned earlier, a Lucene index is denormalized, offering no concept of implicit relationships as found in typical relational databases. To translate some of the Hibernate association mappings into the world of Lucene, Hibernate Search offers the @IndexEmbedded annotation. @IndexEmbedded tells Hibernate Search to embed a particular association into the owning class. However, because Lucene is inherently denormalized, Hibernate Search must be made aware any time the embedded entity changes. To help track these changes, Hibernate Search provides the @ContainedIn annotation, to mark the other side of an embedded association.

Now that you have a clearer understanding of how to annotate a domain class for indexing, let's examine the indexing and search processes.