[jboss-user] [JBoss Cache] Document updated/added: "JBossCacheSearchable"

Manik Surtani do-not-reply at jboss.com
Mon Feb 22 10:43:20 EST 2010

User development,

The document "JBossCacheSearchable", was updated Feb 22, 2010
by Manik Surtani.

To view the document, visit:

h2.  JBoss Cache Searchable Edition
h3. Designs
See http://community.jboss.org/docs/DOC-13454
h3.  About this package
This is the integration package between JBoss Cache and Hibernate Search.
The goal is to add search capabilities to JBoss Cache.  We achieve this by using http://www.hibernate.org/410.html to index user objects as they are added to the cache and modified.  The cache is queried by passing in a valid http://lucene.apache.org/java/docs/index.html query which is then used to search through the indexes and retrieve matching objects from the cache.
h3.  Usage
h4.  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 http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/SearchableCache.html interface is a sub-interface of Cache. Hence, it has the usual put(), get() and remove() methods on it. However, it also has the http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/SearchableCache.html#createQuery(org.apache.lucene.search.Query,%20java.lang.Class...) method. This will return a http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/CacheQuery.html instance, which for example, the http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/CacheQuery.html#list() method can be called. This will return all the results from the search in a list. You can also call an http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/CacheQuery.html#iterator() method on it - which returns a http://www.jboss.org/file-access/default/members/jbosscache/freezone/docs/searchable/1.0.0.BETA1/apidocs/org/jboss/cache/search/QueryResultIterator.html which is a sub-interface of the jdk's http://java.sun.com/j2se/1.3/docs/api/java/util/ListIterator.html.
h4.  How to create a searchable cache and create a query, code examples: - 
public class MySearchableCache  {
  public void letsFindAListOfJohn()  {
    // 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, Address.class, City.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();

h3.  Annotations on your classes.
For the classes that you want to be searched, you will have to annotate them with Hibernate Search annotations.
* http://www.hibernate.org/hib_docs/search/3.1.0.Beta1/api/org/hibernate/search/annotations/ProvidedId.html - The @ProvidedId is to tell HibernateSearch that the document id is NOT in the class, but will be provided separately when the object needs to be indexed. This annotation is on the class.
* http://www.hibernate.org/hib_docs/search/3.1.0.Beta1/api/org/hibernate/search/annotations/Indexed.html - This is so that Hibernate Search will index the class in Lucene and is annotated on the class.
* http://www.hibernate.org/hib_docs/search/3.1.0.Beta1/api/org/hibernate/search/annotations/Field.html - Hibernate Search will put all class-fields with this annotation into the index. If you don't annotate any class-fields they will not be indexed - for example you may not want to annotate a field called +massiveString+ because that will make your indexes very large. 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)

For more code examples http://wiki.jboss.org/wiki/_Files/JBossCacheSearchable/jbcsPresentation.pdf for the attached pdf which has slides from a presentation done on the searchable cache and how it works.
+Also see+ /Hibernate Search API
h3.  Annotations on your class, code examples: - 
public class Person {
  @Field (store = STORE.YES)
  private String name;
  @Field (store = STORE.YES)
  private Date dateOfBirth;
  //You may not want to index this field because it will greatly increase the size of your indexes.
  private String massiveString;
  //Standard getters, setters etc follow.

h3.  FAQs
*Q: Can I add stuff directly onto the Cache?*
A: Yes.  SearchableCache registers a listener with the underlying cache, and is informed of any modification events.  So regardless of whether you use SearchableCache or the underlying cache directly to add/modify/remove data, search indexes will get updated.
It is, however, suggested that you use the SearchableCache directly since it offers a single entry point into the cache system and will help reduce confusion and complexity.
*Q: What about POJO Cache and cache.attach()?*
A: Currently, POJO Cache is not supported but will be for the next release (1.1.0)
*Q: Must Fqns only contain String elements?*
Currently, this is a restriction that Fqn elements as well as keys need to be Strings.  In future this may change to allow other objects.
*Q: Must keys only contain String elements?*
This is a restriction right now and the key part in the Fqn, key pairing has to be a String.
h3.  Project Dependencies
* Hibernate Search 3.1.0 GA
* JBoss Cache v3.0.0.GA
* Commons logging v1.1.1
* SLF4J v1.4.2
h4.  Using Maven or Ivy
* GroupId: org.jboss.cache
* ArtifactId: jbosscache-searchable
* Version: 1.0.0.GA
* Repository: http://repository.jboss.org/maven2
h3. Links
* Download: http://community.jboss.org/docs/DOC-12844
* API docs:  http://community.jboss.org/docs/DOC-12843
* SVN:       http://anonsvn.jboss.org/repos/jbosscache/searchable/
* JIRA:      http://jira.jboss.com/jira/browse/JBCACHE  (use the *SearchableCache* component)
* Forums:    http://www.jboss.com/index.html?module=bb&op=viewforum&f=286


More information about the jboss-user mailing list