org.compass.core
Interface CompassSession

All Superinterfaces:

CompassIndexSession, CompassOperations, CompassSearchSession

All Known Subinterfaces:

InternalCompassSession

All Known Implementing Classes:

DefaultCompassSession, ExistingCompassSession

public interface CompassSession
extends CompassOperations, CompassSearchSession, CompassIndexSession

The main interface between a Java application and Compass.

Provides the basic operations with semantic mapped objects (save, delete, and load/get). The session provides operations on both the objects levels and Resource levels (indexed object model). The CompassSession operations are delegated to the underlying SearchEngine, so no direct access to the SearchEngine is needed.

Implementations will not be thread safe, Instead each thread/transaction should obtain its own instance from a Compass.

If the CompassSession throws an exception, the transaction must be rolled back and the session discarded. The internal state of the CompassSession might not be consistent with the search engine if discarded.

Using the session depends on how transaction managemnet should be done (also see Compass.openSession(). The simplest form looks like this:

 CompassSession session = compass.openSession();
 try {
      // do operations with the session
      session.commit(); // same as session.close()
 } catch (Exception e) {
      session.rollback();
 }
 

A more complex form includes explicit control using CompassTransaction:

 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();
 }
 

Author:

kimchy

See Also:

Resource, Compass

Method Summary

CompassAnalyzerHelper	analyzerHelper() Returns an Analyzer helper.
CompassTransaction	beginLocalTransaction() Begins a unit of work using a Compass local transaction.
CompassTransaction	beginTransaction() Begin a unit of work and return the associated CompassTranscation object.
void	close() Closes the CompassSession.
void	commit() Same as close().
void	flush() Flush the current transaction.
void	flushCommit(String... aliases) Flush commit all the provided aliases (or all of them, if none is provided).
CompassSettings	getSettings() Runtimes settings that apply on the session level.
boolean	isClosed() Returns true if the session is closed.
boolean	isReadOnly() Returns true if the session is read only.
CompassQueryBuilder	queryBuilder() Creats a new query builder, used to build queries programmatically.
CompassQueryFilterBuilder	queryFilterBuilder() Creats a new query filter builder, used to build filters of queries programmatically.
ResourceFactory	resourceFactory() Returns a resource factory allowing to create resources and properties.
void	rollback() When not using explicit CompassTransaction in order to manage transactions, can be called to rollback the current running transaction.
void	setReadOnly() Indicates that the session will be used for read only operations.
CompassTermFreqsBuilder	termFreqsBuilder(String... names) Creates a new terms frequencies builder used to get terms names and freqs for a list of property names.
CompassSession	useLocalTransaction() When not using the CompassTransaction interface, will begin a local transaction instead of the configured transaction.

Methods inherited from interface org.compass.core.CompassOperations

create, create, delete, delete, delete, delete, delete, delete, delete, evict, evict, evict, evictAll, find, get, get, get, get, getResource, getResource, getResource, getResource, load, load, load, load, loadResource, loadResource, loadResource, loadResource, save, save

Methods inherited from interface org.compass.core.CompassSearchSession

find, get, get, get, get, getResource, getResource, getResource, getResource, load, load, load, load, loadResource, loadResource, loadResource, loadResource

Methods inherited from interface org.compass.core.CompassIndexSession

create, create, delete, delete, delete, delete, delete, delete, delete, save, save

Method Detail

setReadOnly

void setReadOnly()

Indicates that the session will be used for read only operations. Allowing to optimize search and read.

isReadOnly

boolean isReadOnly()

Returns true if the session is read only.

See Also:

setReadOnly()

useLocalTransaction

CompassSession useLocalTransaction()

When not using the CompassTransaction interface, will begin a local transaction instead of the configured transaction.

Specified by:

useLocalTransaction in interface CompassSearchSession

resourceFactory

ResourceFactory resourceFactory()

Returns a resource factory allowing to create resources and properties.

Specified by:

resourceFactory in interface CompassIndexSession

getSettings

CompassSettings getSettings()

Runtimes settings that apply on the session level.

Specified by:

getSettings in interface CompassIndexSession

Specified by:

getSettings in interface CompassSearchSession

Returns:

Runtime settings applies on the session level

flush

void flush()
           throws CompassException

Flush the current transaction.

Specified by:

flush in interface CompassIndexSession

Throws:

CompassException

flushCommit

void flushCommit(String... aliases)
                 throws CompassException

Flush commit all the provided aliases (or all of them, if none is provided). Flush commit means that all operations up to this point will be made available in the index, and other sessions will be able to see it. It also means that the operations up to this point will not be rolledback.

Specified by:

flushCommit in interface CompassIndexSession

Throws:

CompassException

beginTransaction

CompassTransaction beginTransaction()
                                    throws CompassException

Begin a unit of work and return the associated CompassTranscation object. If a new underlying transaction is required, begin the transaction. Otherwise continue the new work in the context of the existing underlying transaction. The class of the returned CompassTransaction object is determined by the property compass.transaction.factory.

Returns:

a CompassTransaction instance

Throws:

CompassException

See Also:

CompassTransaction

beginLocalTransaction

CompassTransaction beginLocalTransaction()
                                         throws CompassException

Begins a unit of work using a Compass local transaction. Very handy when using transaction strategy other than local transaction factory but still wish to use a local one for example to perform serach (which will be faster as it won't start and externa transaction).

Throws:

CompassException

queryBuilder

CompassQueryBuilder queryBuilder()
                                 throws CompassException

Creats a new query builder, used to build queries programmatically.

Specified by:

queryBuilder in interface CompassSearchSession

Returns:

The query builder.

Throws:

CompassException

queryFilterBuilder

CompassQueryFilterBuilder queryFilterBuilder()
                                             throws CompassException

Creats a new query filter builder, used to build filters of queries programmatically.

Specified by:

queryFilterBuilder in interface CompassSearchSession

Returns:

The query filter builder.

Throws:

CompassException

termFreqsBuilder

CompassTermFreqsBuilder termFreqsBuilder(String... names)
                                         throws CompassException

Creates a new terms frequencies builder used to get terms names and freqs for a list of property names.

Note, term frequencies are updated to reflect latest changes to the index only after an optimization has taken place (note, calling optimize might not cause optimization).

Specified by:

termFreqsBuilder in interface CompassSearchSession

Parameters:

names - The property names

Returns:

A term freqs builder

Throws:

CompassException

analyzerHelper

CompassAnalyzerHelper analyzerHelper()
                                     throws CompassException

Returns an Analyzer helper. Can be used to help analyze given texts.

Specified by:

analyzerHelper in interface CompassSearchSession

Returns:

the analyzer helper

Throws:

CompassException

rollback

void rollback()
              throws CompassException

When not using explicit CompassTransaction in order to manage transactions, can be called to rollback the current running transaction. Effectively also closes the session.

Specified by:

rollback in interface CompassIndexSession

Throws:

CompassException

commit

void commit()
            throws CompassException

Same as close().

Specified by:

commit in interface CompassIndexSession

Throws:

CompassException

close

void close()
           throws CompassException

Closes the CompassSession. Note, if this session is "contained" within another session, it won't actually be closed, and defer closing the session to the other session.

If there is an on going transaction associated with the session that has not been committed / rolledback yet, will commit the transaction (and in case of failure, will roll it back). Failed commits will throw an exception from the close method.

Specified by:

close in interface CompassIndexSession

Specified by:

close in interface CompassSearchSession

Throws:

CompassException

See Also:

Compass.openSession()

isClosed

boolean isClosed()

Returns true if the session is closed. Note, if this session "joined" another session, it won't actually be closed, and defer closing the session to the outer session.

Specified by:

isClosed in interface CompassIndexSession