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


Copyright (c) 2004-2009 The Compass Project.