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 java.io.Serializable;
020: import javax.naming.Referenceable;
021:
022: import org.compass.core.config.CompassSettings;
023: import org.compass.core.engine.SearchEngineIndexManager;
024: import org.compass.core.engine.SearchEngineOptimizer;
025: import org.compass.core.engine.spellcheck.SearchEngineSpellCheckManager;
026:
027: /**
028: * Creates a CompassSession. Usually an application has a single Compass object.
029: * Threads servicing client requests obtain sessions from Compass.
030: *
031: * <p>Implementors must be threadsafe.
032: *
033: * <p>CompassSessions are immutable. The behaviour of a Compass is controlled by
034: * settings supplied at configuration time through CompassConfiguration. These
035: * settings are defined on the web site.
036: *
037: * <p>Compass also provides operations that are on a higher level than a session,
038: * like create/delete operations on index data files and manages the index
039: * optimiser lifecycle.
040: *
041: * @author kimchy
042: * @see CompassSession
043: * @see org.compass.core.config.CompassConfiguration
044: */
045: public interface Compass extends Referenceable, Serializable {
046:
047: /**
048: * If there is a transaction bound session, will return it. Otherwise
049: * returns a new session.
050: *
051: * <p>A transactional bound session is bounded to the transaction when calling
052: * the CompassSession.beginTransaction() or if Compass tries to automatically join
053: * an already running transaction (see next paragraph).
054: *
055: * <p>If creating a new session, will try to automatically join an existing
056: * outer transaction. An outer transaction might be an already running Compass
057: * local transaction, or an external transaciton (JTA or Spring for example). In
058: * such cases, there is no need to perform any transaction managment code (begin
059: * or commit/rollback transaction) or closing the opened session. Compass will also
060: * bind the session to the same transaction if an outer transaction exists. Note, when
061: * doing so, the mentioned code will have to always be excuted within an already running
062: * transaction.
063: *
064: * @return CompassSession The compass session
065: * @throws CompassException
066: */
067: CompassSession openSession() throws CompassException;
068:
069: /**
070: * Closes Compass and releases any resources that are assoicated with it. It is
071: * very importnat to close an unused Compass instance since it might hold resources
072: * (such as file descriptor when storing the index within the file system) that
073: * will not be released otherwise.
074: *
075: * @throws CompassException
076: */
077: void close() throws CompassException;
078:
079: /**
080: * Clones the current <code>Compass</code> instance. The added settings will merged with the current
081: * compass settings, and control the creation of the new Compass.
082: *
083: * <p>Note, that the new instance will not be registered with JNDI, as well as not start the optimizer.
084: *
085: * @param addedSettings The settings to be added.
086: * @return the cloned compass instance.
087: */
088: Compass clone(CompassSettings addedSettings);
089:
090: /**
091: * Returns a resource factory allowing to create resources and properties.
092: */
093: ResourceFactory getResourceFactory();
094:
095: /**
096: * Retruns the search engine optimizer. You can controll the state of the
097: * optimizer (by calling <code>stop</code> or <code>start</code>), you
098: * can check if the index need optimization, and you can optimize the index.
099: *
100: * @return the search engine optimizer
101: */
102: SearchEngineOptimizer getSearchEngineOptimizer();
103:
104: /**
105: * Return the search engine index manager. You can control the index using
106: * it.
107: *
108: * @return the search engine index manager
109: */
110: SearchEngineIndexManager getSearchEngineIndexManager();
111:
112: /**
113: * Returns the spell check manager. Returns <code>null</code> if the spell check is not
114: * enabled.
115: */
116: SearchEngineSpellCheckManager getSpellCheckManager();
117:
118: /**
119: * Returns the settings Compass was started with.
120: */
121: CompassSettings getSettings();
122:
123: /**
124: * Returns <code>true</code> if the Compass instance is already closed
125: */
126: boolean isClosed();
127: }
|