org.compass.core
Class CompassTemplate

java.lang.Object
  org.compass.core.CompassTemplate

All Implemented Interfaces:

CompassOperations

public class CompassTemplate
extends Object
implements CompassOperations

Helper class that simplifies the Compass access code using the template design pattern.

The central method is "execute", supporting Compass code implementing the CompassCallback interface. It provides Compass Session handling such that neither the CompassCallback implementation nor the calling code needs to explicitly care about retrieving/closing Compass Sessions, handling Session lifecycle exceptions, or managing transactions. The template code is similar to

 CompassSession session = compass.openSession();
 CompassTransaction tx = null;
 try {
        tx = session.beginTransaction();
        Object result = compassCallback.doInCompass(session);
        tx.commit();
        return result;
 } catch (RuntimeException e) {
        if (tx != null) {
                tx.rollback();
        }
        throw e;
 } finally {
        session.close();
 }
 

The template must have a Compass reference set, either using the tempalte constructor or using the set method.

CompassTemplate also provides the same operations available when working with CompassSession, just that they are executed using the "execute" template method, which means that they enjoy it's session lifecycle and transaction support.

Author:

kimchy

Constructor Summary

CompassTemplate()
Creates a new CompassTemplate instance (remember to set Compass using the setCompass method).

CompassTemplate(Compass compass)
Creates a new CompassTemplate instance, already initialized with a Compass instance.

Method Summary

void	create(Object obj) Creates a NEW object in Compass.
void	create(String alias, Object obj) Creates a NEW object in Compass that shares mapping alais with multiple objects.
void	delete(Class clazz, Object... ids) Deletes an object from Compass that match the mapping specified for the defined class based on its ids.
void	delete(Class clazz, Object obj) Deletes an object from Compass that match the mapping specified for the defined class.
void	delete(CompassQuery query) Deletes all entries in the index that match the given query.
void	delete(Object obj) Deletes an object from Compass.
void	delete(Resource resource) Deletes a resource with the specified alias.
void	delete(String alias, Object... ids) Deletes an object from Compass with multiple alias's based on its ids.
void	delete(String alias, Object obj) Deletes an object from Compass with multiple alias's.
void	evict(Object obj) Evicts the given object from the first level cache (transaction scoped cache).
void	evict(Resource resource) Evicts the given resource from the first level cache (transaction scoped cache).
void	evict(String alias, Object id) Evicts the given object from the first level cache (transaction scoped cache).
void	evictAll() Evicts all the objects and the resources from the first level cache.
<T> T	execute(CompassCallback<T> action) Executes the compass callback within a session and a transaction context.
<T> T	execute(CompassTransaction.TransactionIsolation transactionIsolation, CompassCallback<T> action) Executes the compass callback within a session and a transaction context.
CompassHitsOperations	executeFind(CompassCallback<CompassHitsOperations> action) A helper execute method for find operations.
<T> T	executeLocal(CompassCallback<T> action) Executes the compass callback within a session and a local transaction context.
CompassHits	find(String query) Finds a list of objects that match the specified query.
CompassDetachedHits	findWithDetach(String query)
CompassDetachedHits	findWithDetach(String query, int from, int size)
<T> T	get(Class<T> clazz, Object... ids) Returns an object that match the mapping specified for the defined class, and matches the specified ids.
<T> T	get(Class<T> clazz, Object id) Returns an object that match the mapping specified for the defined class, and matches the specified id.
Object	get(String alias, Object... ids) Returns an object that match the mapping specified for the defined alias, and matches the specified ids.
Object	get(String alias, Object id) Returns an object that match the mapping specified for the defined alias, and matches the specified id.
Compass	getCompass() Returns the compass instance used by the template.
Resource	getResource(Class clazz, Object... ids) Returns a Resource that match the mapping specified for the defined class type, and specified ids.
Resource	getResource(Class clazz, Object id) Returns a Resource that match the mapping specified for the defined class type, and specified id.
Resource	getResource(String alias, Object... ids) Returns a Resource that match the mapping specified for the defined alias (possibley different object types), and matches the specified ids.
Resource	getResource(String alias, Object id) Returns a Resource that match the mapping specified for the defined alias (possibley different object types), and matches the specified id.
CompassSettings	getSettings()
<T> T	load(Class<T> clazz, Object... ids) Loads and returns an object that match the mapping specified for the defined class, and matches the specified ids.
<T> T	load(Class<T> clazz, Object id) Loads and returns an object that match the mapping specified for the defined class, and matches the specified id.
Object	load(String alias, Object... ids) Loads and returns an object that match the mapping specified for the defined class, and matches the specified ids.
Object	load(String alias, Object id) Loads and returns an object that match the mapping specified for the defined class, and matches the specified id.
Resource	loadResource(Class clazz, Object... ids) Loads and returns a Resource that match the mapping specified for the defined class, and matches the specified ids.
Resource	loadResource(Class clazz, Object id) Loads and returns a Resource that match the mapping specified for the defined class, and matches the specified id.
Resource	loadResource(String alias, Object... ids) Loads and returns a Resource that match the mapping specified for the defined alias, and matches the specified ids.
Resource	loadResource(String alias, Object id) Loads and returns a Resource that match the mapping specified for the defined alias, and matches the specified id.
void	save(Object obj) Saves an object in Compass.
void	save(String alias, Object obj) Saves an object in Compass that shares mapping alais with multiple objects.
void	setCompass(Compass compass) Sets the compass instance that will be used by the template.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompassTemplate

public CompassTemplate()

Creates a new CompassTemplate instance (remember to set Compass using the setCompass method).

CompassTemplate

public CompassTemplate(Compass compass)

Creates a new CompassTemplate instance, already initialized with a Compass instance.

Method Detail

setCompass

public void setCompass(Compass compass)

Sets the compass instance that will be used by the template.

getCompass

public Compass getCompass()

Returns the compass instance used by the template.

Returns:

the compass instance

execute

public <T> T execute(CompassCallback<T> action)
          throws CompassException

Executes the compass callback within a session and a transaction context.

Parameters:

action - The action to execute witin a compass transaction

Returns:

An object as the result of the compass action

Throws:

CompassException

execute

public <T> T execute(CompassTransaction.TransactionIsolation transactionIsolation,
                     CompassCallback<T> action)
          throws CompassException

Executes the compass callback within a session and a transaction context. Applies the given transaction isolation level.

Parameters:

transactionIsolation - The transaction isolation

action - The action to execute witin a compass transaction

Returns:

An object as the result of the compass action

Throws:

CompassException

executeLocal

public <T> T executeLocal(CompassCallback<T> action)
               throws CompassException

Executes the compass callback within a session and a local transaction context. Applies the given transaction isolation level.

Parameters:

action - The action to execute witin a compass transaction

Returns:

An object as the result of the compass action

Throws:

CompassException

executeFind

public CompassHitsOperations executeFind(CompassCallback<CompassHitsOperations> action)
                                  throws CompassException

A helper execute method for find operations.

Parameters:

action - the callback to execute.

Returns:

The hits that match the query

Throws:

CompassException

getSettings

public CompassSettings getSettings()

create

public void create(Object obj)
            throws CompassException

Description copied from interface: CompassOperations

Creates a NEW object in Compass. All the meta data defined in the Compass mapping files will be indexed and saved for later searching. Note that if the same object (same alias and same id's already exists in the index, it won't be deleted).

Specified by:

create in interface CompassOperations

Parameters:

obj - The object to save.

Throws:

CompassException

create

public void create(String alias,
                   Object obj)
            throws CompassException

Description copied from interface: CompassOperations

Creates a NEW object in Compass that shares mapping alais with multiple objects. All the meta data defined in Compass mapping files will be indexed and saved for later searching.

Specified by:

create in interface CompassOperations

Parameters:

alias - The alias that match the object mappings

obj - The object to save

Throws:

CompassException

delete

public void delete(Object obj)
            throws CompassException

Description copied from interface: CompassOperations

Deletes an object from Compass. The object must have been either loaded by Compass or it's ids must be set if already known.

Specified by:

delete in interface CompassOperations

Parameters:

obj - The object to delete

Throws:

CompassException

delete

public void delete(Resource resource)
            throws CompassException

Description copied from interface: CompassOperations

Deletes a resource with the specified alias. Note that the resource must have the defined ids in the mapping files set and an alias set.

Specified by:

delete in interface CompassOperations

Parameters:

resource - The resource to be deleted.

Throws:

CompassException

delete

public void delete(Class clazz,
                   Object obj)
            throws CompassException

Description copied from interface: CompassOperations

Deletes an object from Compass that match the mapping specified for the defined class. The object can either be the id (or an array of ids), or the actual data object with it's property ids set.

Specified by:

delete in interface CompassOperations

Parameters:

clazz - The class that represtents the required mapping

obj - The object to delete

Throws:

CompassException

delete

public void delete(String alias,
                   Object obj)
            throws CompassException

Description copied from interface: CompassOperations

Deletes an object from Compass with multiple alias's. The object can either be the id (or an array of ids), or the actual data object with it's property ids set.

Specified by:

delete in interface CompassOperations

Parameters:

alias - The alias that the objects maps under

obj - The object to delete

Throws:

CompassException

delete

public void delete(CompassQuery query)
            throws CompassException

Description copied from interface: CompassOperations

Deletes all entries in the index that match the given query.

Specified by:

delete in interface CompassOperations

Parameters:

query - The query to delete by

Throws:

CompassException

find

public CompassHits find(String query)
                 throws CompassException

Description copied from interface: CompassOperations

Finds a list of objects that match the specified query. The query syntax is a search engine format query. For detailed description of the query syntax please visit the site.

Several examples are:

• A set of words - i.e. "Jack London". Compass will search the default property (usually ALL properties, specified in CompassEnvironment).
• A set of words prefixed by meta data name - i.e. author:"Jack London". Compass will search only meta data name author matching keywords Jack London.
• Multiple meta data names - i.e. author:"Jack London" AND book:Fang*. Compass will search both meta data name author matching keywords Jack London and meta data name book matching wildcard Fang*

Note that the list may contains several object types (classes) with no relation between them (except for the semantic relation).

Specified by:

find in interface CompassOperations

Parameters:

query - The query string to search by

Returns:

A hits of objects that matches the query string

Throws:

CompassException

findWithDetach

public CompassDetachedHits findWithDetach(String query)
                                   throws CompassException

Throws:

CompassException

findWithDetach

public CompassDetachedHits findWithDetach(String query,
                                          int from,
                                          int size)
                                   throws CompassException

Throws:

CompassException

get

public <T> T get(Class<T> clazz,
                 Object id)
      throws CompassException

Description copied from interface: CompassOperations

Returns an object that match the mapping specified for the defined class, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Returns null if the object is not found.

Specified by:

get in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

id - The id that identifies the resource

Returns:

The object, returns null if not found

Throws:

CompassException

get

public Object get(String alias,
                  Object id)
           throws CompassException

Description copied from interface: CompassOperations

Returns an object that match the mapping specified for the defined alias, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Returns null if the object is not found.

Specified by:

get in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

id - The id that identifies the resource

Returns:

The object, returns null if not found

Throws:

CompassException

getResource

public Resource getResource(Class clazz,
                            Object id)
                     throws CompassException

Description copied from interface: CompassOperations

Returns a Resource that match the mapping specified for the defined class type, and specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Returns null if the object is not found.

Specified by:

getResource in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

id - The id that identifies the resource

Returns:

The resource, returns null if not found

Throws:

CompassException

getResource

public Resource getResource(String alias,
                            Object id)
                     throws CompassException

Description copied from interface: CompassOperations

Returns a Resource that match the mapping specified for the defined alias (possibley different object types), and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Returns null if the object is not found.

Specified by:

getResource in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

id - The id that identifies the resource

Returns:

The resource

Throws:

CompassException

load

public <T> T load(Class<T> clazz,
                  Object... ids)
       throws CompassException

Description copied from interface: CompassOperations

Loads and returns an object that match the mapping specified for the defined class, and matches the specified ids.

Specified by:

load in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

ids - The ids that identifies the resource

Returns:

The object

Throws:

CompassException

load

public <T> T load(Class<T> clazz,
                  Object id)
       throws CompassException

Description copied from interface: CompassOperations

Loads and returns an object that match the mapping specified for the defined class, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Throws an exception if the resource is not found.

Specified by:

load in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

id - The id that identifies the resource

Returns:

The object

Throws:

CompassException

load

public Object load(String alias,
                   Object... ids)
            throws CompassException

Description copied from interface: CompassOperations

Loads and returns an object that match the mapping specified for the defined class, and matches the specified ids.

Specified by:

load in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

ids - The ids that identifies the resource

Returns:

The object

Throws:

CompassException

load

public Object load(String alias,
                   Object id)
            throws CompassException

Description copied from interface: CompassOperations

Loads and returns an object that match the mapping specified for the defined class, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Throws an exception if the resource is not found.

Specified by:

load in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

id - The id that identifies the resource

Returns:

The object

Throws:

CompassException

loadResource

public Resource loadResource(Class clazz,
                             Object id)
                      throws CompassException

Description copied from interface: CompassOperations

Loads and returns a Resource that match the mapping specified for the defined class, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Throws an exception if the resource is not found.

Specified by:

loadResource in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

id - The id that identifies the resource

Returns:

The resource

Throws:

CompassException

loadResource

public Resource loadResource(String alias,
                             Object id)
                      throws CompassException

Description copied from interface: CompassOperations

Loads and returns a Resource that match the mapping specified for the defined alias, and matches the specified id. The id can be an object of the class (with the id attributes set), an array of id objects, or the actual id object. Throws an exception if the resource is not found.

Specified by:

loadResource in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

id - The id that identifies the resource

Returns:

The resource

Throws:

CompassException

save

public void save(Object obj)
          throws CompassException

Description copied from interface: CompassOperations

Saves an object in Compass. All the meta data defined in the Compass mapping files will be indexed and saved for later searching.

Specified by:

save in interface CompassOperations

Parameters:

obj - The object to save.

Throws:

CompassException

save

public void save(String alias,
                 Object obj)
          throws CompassException

Description copied from interface: CompassOperations

Saves an object in Compass that shares mapping alais with multiple objects. All the meta data defined in Compass mapping files will be indexed and saved for later searching.

Specified by:

save in interface CompassOperations

Parameters:

alias - The alias that match the object mappings

obj - The object to save

Throws:

CompassException

evict

public void evict(Object obj)

Description copied from interface: CompassOperations

Evicts the given object from the first level cache (transaction scoped cache).

Specified by:

evict in interface CompassOperations

Parameters:

obj - The objects to evict.

evict

public void evict(String alias,
                  Object id)

Description copied from interface: CompassOperations

Evicts the given object from the first level cache (transaction scoped cache). The object can either be the id (or an array of ids), or the actual data object with it's property ids set.

Specified by:

evict in interface CompassOperations

Parameters:

alias - The alias of the object/entry to evict.

id - The id of the object/entry to evict.

evict

public void evict(Resource resource)

Description copied from interface: CompassOperations

Evicts the given resource from the first level cache (transaction scoped cache).

Specified by:

evict in interface CompassOperations

Parameters:

resource - The resource to evict.

evictAll

public void evictAll()

Description copied from interface: CompassOperations

Evicts all the objects and the resources from the first level cache.

Specified by:

evictAll in interface CompassOperations

getResource

public Resource getResource(Class clazz,
                            Object... ids)
                     throws CompassException

Description copied from interface: CompassOperations

Returns a Resource that match the mapping specified for the defined class type, and specified ids.

Specified by:

getResource in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

ids - The ids that identifies the resource

Returns:

The resource, returns null if not found

Throws:

CompassException

getResource

public Resource getResource(String alias,
                            Object... ids)
                     throws CompassException

Description copied from interface: CompassOperations

Returns a Resource that match the mapping specified for the defined alias (possibley different object types), and matches the specified ids. Returns null if the object is not found.

Specified by:

getResource in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

ids - The ids that identifies the resource

Returns:

The resource

Throws:

CompassException

loadResource

public Resource loadResource(Class clazz,
                             Object... ids)
                      throws CompassException

Description copied from interface: CompassOperations

Loads and returns a Resource that match the mapping specified for the defined class, and matches the specified ids. Throws an exception if the resource is not found.

Specified by:

loadResource in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

ids - The ids that identifies the resource

Returns:

The resource

Throws:

CompassException

loadResource

public Resource loadResource(String alias,
                             Object... ids)
                      throws CompassException

Description copied from interface: CompassOperations

Loads and returns a Resource that match the mapping specified for the defined alias, and matches the specified ids. Throws an exception if the resource is not found.

Specified by:

loadResource in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

ids - The ids that identifies the resource

Returns:

The resource

Throws:

CompassException

delete

public void delete(String alias,
                   Object... ids)
            throws CompassException

Description copied from interface: CompassOperations

Deletes an object from Compass with multiple alias's based on its ids.

Specified by:

delete in interface CompassOperations

Parameters:

alias - The alias that the objects maps under

ids - The ids of the object to delete

Throws:

CompassException

delete

public void delete(Class clazz,
                   Object... ids)
            throws CompassException

Description copied from interface: CompassOperations

Deletes an object from Compass that match the mapping specified for the defined class based on its ids.

Specified by:

delete in interface CompassOperations

Parameters:

clazz - The class that represtents the required mapping

ids - The object ids to delete

Throws:

CompassException

get

public <T> T get(Class<T> clazz,
                 Object... ids)
      throws CompassException

Description copied from interface: CompassOperations

Returns an object that match the mapping specified for the defined class, and matches the specified ids. Returns null if the object is not found.

Specified by:

get in interface CompassOperations

Parameters:

clazz - The class that represents the required mapping

ids - The ids that identifies the resource

Returns:

The object, returns null if not found

Throws:

CompassException

get

public Object get(String alias,
                  Object... ids)
           throws CompassException

Description copied from interface: CompassOperations

Returns an object that match the mapping specified for the defined alias, and matches the specified ids. Returns null if the object is not found.

Specified by:

get in interface CompassOperations

Parameters:

alias - The alias that represents the required mapping

ids - The ids that identifies the resource

Returns:

The object, returns null if not found

Throws:

CompassException