net.java.ao
Class SearchableEntityManager

java.lang.Object
  net.java.ao.EntityManager
      net.java.ao.SearchableEntityManager

public class SearchableEntityManager
extends EntityManager

Required to manage entities with enabled full-text searching. This is where all the "meat" of the Lucene indexing support is actually implemented. It is required to use this EntityManager implementation to use full-text searching. Example:

public interface Post extends Entity {
     // ...

     @Searchable
     @SQLType(Types.BLOB)
     public String getBody();

     @Searchable
     @SQLType(Types.BLOB)
     public void setBody(String body);
 }

 // ...
 SearchableEntityManager manager = new SearchableEntityManager(
         uri, username, password, FSDirectory.getDirectory("~/lucene_index"));
 manager.search(Post.class, "my search string");       // returns results as Post[]

This class does not support any Java full-text search libraries other than Lucene. Also, the support for Lucene itself is comparatively limited. If your requirements dictate more advanced functionality, you should consider writing a custom implementation of this class to provide the enhancements you need. More features are planned for this class in future...

Author:

Daniel Spiewak

See Also:

Searchable

Constructor Summary

SearchableEntityManager(DatabaseProvider databaseProvider, EntityManagerConfiguration configuration, LuceneConfiguration luceneConfiguration)

Method Summary

void	addToIndex(RawEntity<?> entity) Adds the entity instance to the index.
void	delete(RawEntity<?>... entities) Deletes the specified entities from the database.
org.apache.lucene.analysis.Analyzer	getAnalyzer()
protected <T extends RawEntity<K>,K> T	getAndInstantiate(Class<T> type, K key) Creates a new instance of the entity of the specified type corresponding to the given primary key.
org.apache.lucene.store.Directory	getIndexDir()
void	optimize() Optimizes the Lucene index for searching.
void	removeFromIndex(RawEntity<?> entity) Removes the specified entity from the Lucene index.
<T extends RawEntity<K>,K> T[]	search(Class<T> type, String strQuery) Runs a Lucene full-text search on the specified entity type with the given query.

Methods inherited from class net.java.ao.EntityManager

count, count, count, create, create, find, find, find, find, findWithSQL, flush, flushAll, get, get, getCache, getFieldNameConverter, getNameConverters, getPolymorphicTypeMapper, getProvider, getTableNameConverter, migrate, peer, peer, setCache, setPolymorphicTypeMapper, stream, stream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SearchableEntityManager

public SearchableEntityManager(DatabaseProvider databaseProvider,
                               EntityManagerConfiguration configuration,
                               LuceneConfiguration luceneConfiguration)
                        throws IOException

Throws:

IOException

Method Detail

getAndInstantiate

protected <T extends RawEntity<K>,K> T getAndInstantiate(Class<T> type,
                                                         K key)

Description copied from class: EntityManager

Creates a new instance of the entity of the specified type corresponding to the given primary key. This is used by EntityManager.get(Class, Object[])} to create the entity if the instance is not found already in the cache. This method should not be repurposed to perform any caching, since ActiveObjects already assumes that the caching has been performed.

Overrides:

getAndInstantiate in class EntityManager

Parameters:

type - The type of the entity to create.

key - The primary key corresponding to the entity instance required.

Returns:

An entity instance of the specified type and primary key.

search

public <T extends RawEntity<K>,K> T[] search(Class<T> type,
                                             String strQuery)
                                throws IOException,
                                       org.apache.lucene.queryParser.ParseException,
                                       SQLException

Runs a Lucene full-text search on the specified entity type with the given query. The search will be run on every Searchable field within the entity. No caching is performed in this method. Rather, AO relies upon the underlying Lucene code to be performant.

Parameters:

type - The type of the entities to search for.

strQuery - The query to pass to Lucene for the search.

Returns:

The entity instances which correspond with the search results.

Throws:

IOException - If Lucene was unable to open the index.

org.apache.lucene.queryParser.ParseException - If Lucene was unable to parse the search string into a valid query.

SQLException

delete

public void delete(RawEntity<?>... entities)
            throws SQLException

Description copied from class: EntityManager

Deletes the specified entities from the database. DELETE statements are called on the rows in the corresponding tables and the entities are removed from the instance cache. The entity instances themselves are not invalidated, but it doesn't even make sense to continue using the instance without a row with which it is paired.

This method does attempt to group the DELETE statements on a per-type basis. Thus, if you pass 5 instances of EntityA and two instances of EntityB, the following SQL prepared statements will be invoked:

DELETE FROM entityA WHERE id IN (?,?,?,?,?);
 DELETE FROM entityB WHERE id IN (?,?);

Thus, this method scales very well for large numbers of entities grouped into types. However, the execution time increases linearly for each entity of unique type.

Overrides:

delete in class EntityManager

Parameters:

entities - A varargs array of entities to delete. Method returns immediately if length == 0.

Throws:

SQLException

addToIndex

public void addToIndex(RawEntity<?> entity)
                throws IOException

Adds the entity instance to the index. No checking is performed to ensure that the entity is not already part of the index. All of the Searchable fields within the entity will be added to the index as part of the document corresponding to the instance.

Parameters:

entity - The entity to add to the index.

Throws:

IOException - If Lucene was unable to open the index.

removeFromIndex

public void removeFromIndex(RawEntity<?> entity)
                     throws IOException

Removes the specified entity from the Lucene index. This performs a lookup in the index based on the value of the entity primary key and removes the appropriate Document.

Parameters:

entity - The entity to remove from the index.

Throws:

IOException - If Lucene was unable to open the index.

optimize

public void optimize()
              throws IOException

Optimizes the Lucene index for searching. This call peers down to IndexWriter#optimize(). For sizable indexes, this call will take some time, so it is best not to perform the operation in scenarios where it may block interface responsiveness (such as in the middle of a page request, or within the EDT).

This method is the only optimization call made against the Lucene index. Meaning, SearchableEntityManager never optimizes the index automatically, as this could potentially cause major performance issues. Developers should be aware of this and the negative impact lack-of optimization can have upon search performance.

Throws:

IOException - If Lucene was unable to open the index.

getIndexDir

public org.apache.lucene.store.Directory getIndexDir()

getAnalyzer

public org.apache.lucene.analysis.Analyzer getAnalyzer()