grailsPortal.description

h1. Grails Hibernate Search Plugin

This plugin aims to integrate Hibernate Search features to Grails in very few steps.

h2. Quick start


h3. Installation

{code}
  grails install-plugin hibernate-search
{code}

h3. Configuration

By default, the plugin stores your indexes in this directory:

{code}
 ~/.grails/${grails.version}/projects/${yourProjectName}/lucene-index/development/
{code}

You can override this configuration in your Datasource.groovy

{code}
 hibernate {
 
    // default Grails configuration:
    cache.use_second_level_cache = true
    cache.use_query_cache = true
    cache.provider_class = 'net.sf.ehcache.hibernate.EhCacheProvider'

    // hibernate search configuration:
    search.default.directory_provider = 'filesystem'
    search.default.indexBase = '/path/to/your/indexes'

}
{code}

You can also define the path to your indexes with JNDI configuration as following:

{code}
 hibernate {
 
    // default Grails configuration:
    cache.use_second_level_cache = true
    cache.use_query_cache = true
    cache.provider_class = 'net.sf.ehcache.hibernate.EhCacheProvider'

    // hibernate search configuration:
    search.default.directory_provider = 'filesystem'
    search.default.indexBaseJndiName = 'java:comp/env/luceneIndexBase'

}
{code}

h3. Mark your domain classes as indexable

Add a static search closure as following:

{code}
class MyDomainClass {

    String author
    String body
    Date publishedDate
    String summary
    String title
    Status status
    Double price
    Integer someInteger

    enum Status {
        DISABLED, PENDING, ENABLED
    }

    static hasMany = [categories: Category, items: Item]

    static search = {
        // fields
        author index: 'tokenized'
        body index: 'tokenized'
        publishedDate date: 'day'
        summary index: 'tokenized'
        title index: 'tokenized'
        status index: 'un_tokenized'
        categories indexEmbedded: true
        items indexEmbedded: [depth: 2] // configure the depth indexing
        price numeric: 2
        someInteger index: 'un_tokenized', bridge: ['class': PaddedIntegerBridge, params: ['padding': 10]]

        // support for classBridge
        classBridge = ['class': MyClassBridge, params: [myParam: "4"]]
    }

}
{code}

This static property indicates which fields should be indexed and describes how the field has to be indexed.

Also, the plugin lets you to mark your domain classes as indexable with the Hibernate Search annotations.

{code}
@Indexed
class MyDomainClass {

    // when using annotations, id is required to define DocumentId
    @DocumentId
    Long id

    @Field(index=Index.TOKENIZED)
    String author
    
    @Field(index=Index.TOKENIZED)
    String body
    
    @Field
    @DateBridge(resolution=Resolution.DAY)
    Date publishedDate
    
    @Field(index=Index.TOKENIZED)
    String summary
    
    @Field(index=Index.TOKENIZED)
    String title
    
    @Field(index=Index.UN_TOKENIZED)
    Status status
    
    @Field 
    @NumericField( precisionStep = 2)
    Double price

    enum Status {
        DISABLED, PENDING, ENABLED
    }

    @IndexedEmbedded
    Set categories

    @IndexedEmbedded(depth = 2)
    Set items

    static hasMany = [categories: Category]

}
{code}


h3. Search

The plugin provides you dynamic method to search for indexed entities. 

h4. Retrieving the results

All indexed domain classes provides .search() method which lets you to list the results.
The plugin provides a search DSL for simplifying the way you can search. Here is what it looks like with the search DSL:

{code}
class SomeController {

   def myAction = { MyCommand command ->

      def page = [max: Math.min(params.max ? params.int('max') : 10, 50), 
                           offset: params.offset ? params.int('offset') : 0]

      def myDomainClasses = MyDomainClass.search().list {

         if ( command.dateTo ) {
            below "publishedDate", command.dateTo
         }

         if ( command.dateFrom ) {
            above "publishedDate", command.dateFrom
         }

         mustNot {
            keyword "status", Status.DISABLED
         }

         if ( command.keyword ) {
            should {
               command.keyword.tokenize().each { keyword ->

                  def wild = keyword.toLowerCase() + '*'

                  wildcard "author", wild
                  wildcard "body", wild
                  wildcard "summary", wild
                  wildcard "title", wild
                  wildcard "categories.name", wild
               }
            }
         }

         sort "publishedDate", "asc"

         maxResults page.max

         offset page.offset
      }

      [myDomainClasses: myDomainClasses]
   }
}
{code}

h4. Counting the results

You can also retrieve the number of results by using 'count' method:

{code}
def myDomainClasses = MyDomainClass.search().count {
 ...
}
{code}

h2. Bug tracker

Please report any issue on GitHub: 

[https://github.com/mathpere/grails-hibernate-search-plugin/issues|https://github.com/mathpere/grails-hibernate-search-plugin/issues]


h2. Authors

**Mathieu Perez**
- [http://twitter.com/mathieuperez|http://twitter.com/mathieuperez]

**Julie Ingignoli**
- [http://twitter.com/ZeJulie|http://twitter.com/ZeJulie] 


h2. License

Licensed under the Apache License, Version 2.0:  [http://www.apache.org/licenses/LICENSE-2.0|http://www.apache.org/licenses/LICENSE-2.0]