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.engine;
018:
019: import org.compass.core.CompassTransaction.TransactionIsolation;
020: import org.compass.core.Resource;
021:
022: /**
023: * A search engine absraction above the actual search engine implementation.
024: * Works with resources and properties for data, and ResourceMapping,
025: * PropertyMapping, and ResourceIdMapping.
026: * <p/>
027: * All the search engine operations the are needed should be provided by the
028: * SearchEngine abstraction (save, delete, load, get, find).
029: * <p/>
030: * The search engine abstraction also acts as a Property and Resource factory,
031: * creating the actual implementations.
032: * <p/>
033: * The search engine must provide supprot for transactional operations, though
034: * in practice, it can be a non transactional search engine. If it is a non
035: * transactional search engine, it must be documented as such.
036: *
037: * @author kimchy
038: * @see org.compass.core.Resource
039: * @see org.compass.core.Property
040: * @see org.compass.core.mapping.ResourceMapping
041: * @see org.compass.core.mapping.ResourcePropertyMapping
042: * @see org.compass.core.mapping.ResourceIdMappingProvider
043: */
044: public interface SearchEngine {
045:
046: SearchEngineFactory getSearchEngineFactory();
047:
048: /**
049: * Begins the search engine transaction, using the configured transaction
050: * isolation.
051: */
052: void begin() throws SearchEngineException;
053:
054: /**
055: * Begins the search engine transaction using the given transaction
056: * isolation.
057: */
058: void begin(TransactionIsolation transactionIsolation)
059: throws SearchEngineException;
060:
061: /**
062: * Prepares the transaction for a commit. The first phase of a two phase
063: * commit operation.
064: */
065: void prepare() throws SearchEngineException;
066:
067: /**
068: * Commits the transaction. If onePhase is set to <code>true</code>,
069: * commits the transaction by executing the two phases in the two phase
070: * commit operation. If it is set to <code>false</code>, executes the
071: * second phase of the two phase commit operation (and must be called after
072: * <code>prepare</code>).
073: */
074: void commit(boolean onePhase) throws SearchEngineException;
075:
076: /**
077: * Returns <code>true</code> if Compass is within a running transaction.
078: */
079: boolean isWithinTransaction() throws SearchEngineException;
080:
081: /**
082: * Rolls back the current transaction. Can be called before any phase of the
083: * commit operation was executed, and after the first phase of the two phase
084: * commit operation (the <code>prepare</code> operation).
085: */
086: void rollback() throws SearchEngineException;
087:
088: /**
089: * Returns <code>true</code> if the search engine was used (up until now)
090: * for read only operations.
091: */
092: boolean isReadOnly();
093:
094: /**
095: * Flushed the current transaction. Currently only works with batch insert transaction.
096: */
097: void flush() throws SearchEngineException;
098:
099: /**
100: * Was this transaction rolled back
101: */
102: boolean wasRolledBack() throws SearchEngineException;
103:
104: /**
105: * Check if this transaction was successfully committed. This method could
106: * return <code>false</code> even after successful invocation of
107: * <code>commit()</code>.
108: */
109: boolean wasCommitted() throws SearchEngineException;
110:
111: /**
112: * Closes and disposes of the search engine.
113: */
114: void close() throws SearchEngineException;
115:
116: /**
117: * Creates a new query builder.
118: */
119: SearchEngineQueryBuilder queryBuilder()
120: throws SearchEngineException;
121:
122: /**
123: * Creates a new query filter builder.
124: */
125: SearchEngineQueryFilterBuilder queryFilterBuilder()
126: throws SearchEngineException;
127:
128: /**
129: * Returns an analyzer helper for the search engine.
130: */
131: SearchEngineAnalyzerHelper analyzerHelper();
132:
133: /**
134: * Creates the resource in the index file under the given alias.
135: */
136: void create(Resource resource) throws SearchEngineException;
137:
138: /**
139: * Saves the given resource under the given resource.
140: */
141: void save(Resource resource) throws SearchEngineException;
142:
143: /**
144: * Deletes the resource, which has the property ids. The ResourceMapping is fetched
145: * according to the alias.
146: */
147: void delete(Resource resource) throws SearchEngineException;
148:
149: /**
150: * Loads a resource for the given resource that holds the properties AND the
151: * alias, under the specified alias. Throws an exception if the resource if
152: * not found.
153: */
154: Resource load(Resource idResource) throws SearchEngineException;
155:
156: /**
157: * Returns a resource for the given resource that holds the properties AND
158: * the alias, under the specified alias. Retrurns null if the resource is
159: * not found.
160: */
161: Resource get(Resource idResource) throws SearchEngineException;
162:
163: /**
164: * Returns term frequencies.
165: */
166: SearchEngineTermFrequencies termFreq(String[] propertyNames,
167: int size, SearchEngineInternalSearch internalSearch);
168:
169: /**
170: * Returns a search engine internal implementation.
171: */
172: SearchEngineInternalSearch internalSearch(String[] subIndexes,
173: String[] aliases) throws SearchEngineException;
174: }
|