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: /**
020: *
021: * @author kimchy
022: */
023: public interface SearchEngineIndexManager {
024:
025: /**
026: * A callback interface that works with.
027: *
028: * @author kimchy
029: */
030: public static interface IndexOperationCallback {
031:
032: /**
033: * First step is called just after the index is locked for any dirty operations.
034: * <p>
035: * Return <code>true</code> if after the first step, the system should continue
036: * to the second step.
037: */
038: boolean firstStep() throws SearchEngineException;
039:
040: /**
041: * Second step is called just after the index is locked for read operations
042: * (on top of the dirty operations).
043: */
044: void secondStep() throws SearchEngineException;
045: }
046:
047: /**
048: * A callback to replace the current index.
049: *
050: * @author kimchy
051: */
052: public static interface ReplaceIndexCallback {
053:
054: /**
055: * Provides the ability to be notified when the index can be built
056: * during the replace operation. There is no need to actually build the
057: * index, if one already exists.
058: */
059: void buildIndexIfNeeded() throws SearchEngineException;
060: }
061:
062: /**
063: * Starts the index manager
064: */
065: void start();
066:
067: /**
068: * Stops / closes the index manager
069: */
070: void stop();
071:
072: /**
073: * Returns <code>true</code> if the index manage is running
074: */
075: boolean isRunning();
076:
077: /**
078: * Closes the index manager. Used by compass, probably not a good idea to call it.
079: */
080: void close();
081:
082: /**
083: * Creates an index data. If exists, deletes it and creates a new one.
084: *
085: * @throws SearchEngineException
086: */
087: void createIndex() throws SearchEngineException;
088:
089: /**
090: * Verify the index data. If exists, does nothing. If it doesn't exists,
091: * creates it. Returns <code>true</code> if the index was created. If the index
092: * exists, and it's {@link org.compass.core.lucene.LuceneEnvironment.SearchEngineIndex#USE_COMPOUND_FILE}
093: * changed it's settings, will compound / un-compound the index accordingly.
094: *
095: * @throws SearchEngineException
096: */
097: boolean verifyIndex() throws SearchEngineException;
098:
099: /**
100: * Deletes the index.
101: *
102: * @throws SearchEngineException
103: */
104: void deleteIndex() throws SearchEngineException;
105:
106: /**
107: * Cleans the index from data (by deleting and creating an empty one).
108: */
109: void cleanIndex() throws SearchEngineException;
110:
111: /**
112: * Cleans the index from data (by deleting and creating an empty one).
113: */
114: void cleanIndex(String subIndex) throws SearchEngineException;
115:
116: /**
117: * Returns <code>true</code> if the index exists.
118: */
119: boolean indexExists() throws SearchEngineException;
120:
121: /**
122: * A general api for index operations. Provides the ability to perform safe operations
123: * using the {@link IndexOperationCallback}.
124: */
125: void operate(IndexOperationCallback callback)
126: throws SearchEngineException;
127:
128: /**
129: * Replaces the index data that is used by the current instance, with the one that is pointed by
130: * the given <code>indexManager</code>. A callback interface can be registered if the index is
131: * dynamically created.
132: * <p>
133: * The replace process is safe, in terms that it will aquire dirty locks and read locks,
134: * so the index can be safely replaced while it is being used.
135: */
136: void replaceIndex(SearchEngineIndexManager indexManager,
137: ReplaceIndexCallback callback) throws SearchEngineException;
138:
139: /**
140: * Returns <code>true</code> if the sub index is cached.
141: */
142: boolean isCached(String subIndex) throws SearchEngineException;
143:
144: /**
145: * Returns <code>true</code> if one of the sub indexes is cached.
146: */
147: boolean isCached() throws SearchEngineException;
148:
149: /**
150: * Clears any internal caching done by the index for the specified sub-index.
151: *
152: * @throws SearchEngineException
153: */
154: void clearCache(String subIndex) throws SearchEngineException;
155:
156: /**
157: * Clears any internal caching done by the index.
158: *
159: * @throws SearchEngineException
160: */
161: void clearCache() throws SearchEngineException;
162:
163: /**
164: * Refresh any internal caching done by the index for the specified sub-index.
165: *
166: * @throws SearchEngineException
167: */
168: void refreshCache(String subIndex) throws SearchEngineException;
169:
170: /**
171: * Refresh any internal caching done by the index.
172: *
173: * @throws SearchEngineException
174: */
175: void refreshCache() throws SearchEngineException;
176:
177: /**
178: * Notifies all the compass instances that are working with the same index to
179: * clear cache.
180: *
181: * @throws SearchEngineException
182: */
183: void notifyAllToClearCache() throws SearchEngineException;
184:
185: /**
186: * Manual check if the notified to clear the cache globally. If it does, will clear the cache.
187: *
188: * @throws SearchEngineException
189: */
190: void checkAndClearIfNotifiedAllToClearCache()
191: throws SearchEngineException;
192:
193: /**
194: * Performs scheduled tasks that are usually derived basde on the actual index storage used.
195: *
196: * <p>This API will be called when disabling the automatic scheduler that comes built in with
197: * Compass.
198: */
199: void performScheduledTasks() throws SearchEngineException;
200:
201: /**
202: * Returns the sub indexes that Compass handles.
203: */
204: String[] getSubIndexes();
205:
206: /**
207: * Releases all the locks held over all the possbile sub indexes.
208: */
209: void releaseLocks() throws SearchEngineException;
210:
211: /**
212: * Releases a lock for the given sub index.
213: */
214: void releaseLock(String subIndex) throws SearchEngineException;
215:
216: /**
217: * Returns <code>true</code> if one of the sub indexes is locked.
218: */
219: boolean isLocked() throws SearchEngineException;
220:
221: /**
222: * Returns <code>true</code> if the given sub index is locked.
223: */
224: boolean isLocked(String subIndex) throws SearchEngineException;
225: }
|