001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core;
018:
019: import org.compass.core.CompassTransaction.TransactionIsolation;
020: import org.compass.core.config.CompassSettings;
021:
022: /**
023: * The main interface between a Java application and Compass.
024: * <p>
025: * Provides the basic operations with semantic mapped objects (save, delete, and
026: * load/get). The session provides operations on both the objects levels and
027: * Resource levels (indexed object model). The CompassSession operations are
028: * delegated to the underlying SearchEngine, so no direct access to the
029: * SearchEngine is needed.
030: * </p>
031: *
032: * <p>
033: * Implementations will not be thread safe, Instead each thread/transaction
034: * should obtain its own instance from a Compass.
035: * </p>
036: *
037: * <p>
038: * If the CompassSession throws an exception, the transaction must be rolled
039: * back and the session discarded. The internal state of the CompassSession
040: * might not be consistent with the search engine if discarded.
041: * </p>
042: *
043: * <p>
044: * Please see the CompassTemplate class for easier programmatic control using
045: * the template design pattern.
046: *
047: * @author kimchy
048: * @see org.compass.core.Resource
049: * @see org.compass.core.Compass
050: */
051:
052: public interface CompassSession extends CompassOperations {
053:
054: /**
055: * Runtimes settings that apply on the session level.
056: *
057: * @return Runtime settings applies on the session level
058: * @see org.compass.core.config.RuntimeCompassEnvironment
059: * @see org.compass.core.lucene.RuntimeLuceneEnvironment
060: */
061: CompassSettings getSettings();
062:
063: /**
064: * Begin a unit of work and return the associated CompassTranscation object.
065: * If a new underlying transaction is required, begin the transaction.
066: * Otherwise continue the new work in the context of the existing underlying
067: * transaction. The class of the returned CompassTransaction object is
068: * determined by the property <code>compass.transaction.factory</code>.
069: *
070: * @return a CompassTransaction instance
071: * @throws CompassException
072: * @see CompassTransaction
073: */
074: CompassTransaction beginTransaction() throws CompassException;
075:
076: /**
077: * Begin a unit of work and return the associated CompassTranscation object.
078: * If a new underlying transaction is required, begin the transaction.
079: * Otherwise continue the new work in the context of the existing underlying
080: * transaction. The class of the returned CompassTransaction object is
081: * determined by the property <code>compass.transaction.factory</code>.
082: * <p>
083: * Also accepts the transcation isolation of the transaction.
084: *
085: * @param transactionIsolation
086: * @return a CompassTransaction instance
087: * @throws CompassException
088: * @see CompassTransaction
089: */
090: CompassTransaction beginTransaction(
091: TransactionIsolation transactionIsolation)
092: throws CompassException;
093:
094: /**
095: * Begins a unit of work using a Compass local transaction. Very handy when using
096: * transaction strategy other than local transaction factory but still wish to use
097: * a local one for example to perform serach (which will be faster as it won't start
098: * and externa transaction).
099: */
100: CompassTransaction beginLocalTransaction() throws CompassException;
101:
102: /**
103: * Creats a new query builder, used to build queries programmatically.
104: *
105: * @return The query builder.
106: */
107: CompassQueryBuilder queryBuilder() throws CompassException;
108:
109: /**
110: * Creats a new query filter builder, used to build filters of queries
111: * programmatically.
112: *
113: * @return The query filter builder.
114: */
115: CompassQueryFilterBuilder queryFilterBuilder()
116: throws CompassException;
117:
118: /**
119: * Creates a new terms frequencies builder used to get terms names and
120: * freqs for a list of property names.
121: *
122: * @param names The property names
123: * @return A term freqs builder
124: * @throws CompassException
125: */
126: CompassTermFreqsBuilder termFreqsBuilder(String... names)
127: throws CompassException;
128:
129: /**
130: * Returns an Analyzer helper. Can be used to help analyze given texts.
131: *
132: * @return the analyzer helper
133: * @throws CompassException
134: */
135: CompassAnalyzerHelper analyzerHelper() throws CompassException;
136:
137: /**
138: * Closes the CompassSession. Note, if this session another session, it won't
139: * actually be closed, and defer closing the session to the other session.
140: *
141: * @throws CompassException
142: */
143: void close() throws CompassException;
144:
145: /**
146: * Returns <code>true</code> if the session is closed. Note, if this session
147: * "joined" another session, it won't actually be closed, and defer closing
148: * the session to the outer session.
149: */
150: boolean isClosed();
151: }
|