Friday 4 July 2008

JBoss Cache Searchable

For those who don't know yet, I've been working on a GSoC (Google Summer of Code) project and is the integration package between JBoss Cache and Hibernate Search. Basically, this enables users to search through JBoss Cache using Hibernate Search. According to another Surtani at JBoss, it's a very cool project and as far as I'm concerned it's just a fun piece of code to be working on :). It's been an interesting, topsy-turvy ride over the past couple of months getting all this stuff to work - and is still not optimised, but that will be done over the next couple of weeks. Here is some basic information I copied out from the wiki.

About this package

The goal is to add search capabilities to JBoss Cache. We achieve this by using Hibernate Search to index user objects as they are added to the cache and modified. The cache is queried by passing in a valid Apache Lucene query which is then used to search through the indexes and retrieve matching objects from the cache.


Usage

How will I use jbosscache-searchable?

You can create an instance of a searchable-cache. People who use jbosscache-core frequently will find this quite easy as it is very similar to creating an instance of the cache.

The SearchableCache interface is a sub-interface of Cache. Hence, it has the usual put(), get() and remove() methods on it. However, it also has the createQuery() method. This will return a CacheQuery object with which the list() method can be called. This will return all the results from the search in a list. You can also call an iterator() method on it - which returns a QueryResultIterator which is a sub-interface of the jdk's ListIterator.

How to create a searchable cache, code example: -

Start by creating a core cache.

Cache cache = new DefaultCacheFactory().createCache();


Similar to that create a searchable cache. As parameters, you must pass in the cache instance that you have created and the classes that you wish to be searched.

SearchableCache searchable = new
SearchableCacheFactory().createSearchableCache(cache, Person.class);


Lets say that I have 100 objects in this class and I want to search for the people with name John.As with Hibernate Search, create a Lucene query and a QueryParser.

QueryParser queryParser = new QueryParser("name", new StandardAnalyzer());


"name" is the field within Person that I want to be searching through.

Query luceneQuery = queryParser.parse("John");


"John" is the word within the name field that I want to be searching for.

CacheQuery cacheQuery = searchableCache.createQuery(luceneQuery);


The cacheQuery object will now have all the instances of Person with name John. I can now put all of these into a List: -

List results = cacheQuery.list();


Annotations on your classes.

For the classes that you want to be searched, you will have to annotate them with Hibernate Search annotations.

  1. @ProvidedId - Firstly, you should not annotate a field with @DocumentId as normally with Hibernate Search. The @ProvidedId is so that Hibernate Search will not expect a @DocumentId and will know that you will provide one later. This is to say that a class with @ProvidedId doesn't need a @DocumentId. Although at this point it has not been tested, a @DocumentId in a field which is in a class that has a @ProvidedId should not break your system. This is a class annotation.
  2. @Indexed - This is so that Hibernate Search will index the class in Lucene and is annotated on the class.
  3. @Field - Hibernate Search will put all class-fields with this annotation into the index. With each @Field, you must also specify that the ''store'' property is set to ''yes''. Otherwise the field will not be stored. For example: - @Field (store = STORE.YES)

Also see http://www.hibernate.org/hib_docs/search/api/overview-summary.html for more information on annotations.


For more information, see the wiki page.

No comments: