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: /**
020: * A interface describing all the available operations allowed by compass.
021: *
022: * @author kimchy
023: */
024: public interface CompassOperations {
025:
026: /**
027: * Deletes a resource with the specified alias. Note that the resource must
028: * have the defined ids in the mapping files set and an alias set.
029: *
030: * @param resource The resource to be deleted.
031: * @throws CompassException
032: */
033: void delete(Resource resource) throws CompassException;
034:
035: /**
036: * Returns a Resource that match the mapping specified for the defined class
037: * type, and specified id. The id can be an object of the class (with the id
038: * attributes set), an array of id objects, or the actual id object. Returns
039: * <code>null</code> if the object is not found.
040: *
041: * @param clazz The class that represents the required mapping
042: * @param id The id that identifies the resource
043: * @return The resource, returns <code>null</code> if not found
044: * @throws CompassException
045: */
046: Resource getResource(Class clazz, Object id)
047: throws CompassException;
048:
049: /**
050: * Returns a Resource that match the mapping specified for the defined class
051: * type, and specified ids.
052: *
053: * @param clazz The class that represents the required mapping
054: * @param ids The ids that identifies the resource
055: * @return The resource, returns <code>null</code> if not found
056: * @throws CompassException
057: */
058: Resource getResource(Class clazz, Object... ids)
059: throws CompassException;
060:
061: /**
062: * Returns a Resource that match the mapping specified for the defined alias
063: * (possibley different object types), and matches the specified id. The id
064: * can be an object of the class (with the id attributes set), an array of
065: * id objects, or the actual id object. Returns <code>null</code> if the
066: * object is not found.
067: *
068: * @param alias The alias that represents the required mapping
069: * @param id The id that identifies the resource
070: * @return The resource
071: * @throws CompassException
072: */
073: Resource getResource(String alias, Object id)
074: throws CompassException;
075:
076: /**
077: * Returns a Resource that match the mapping specified for the defined alias
078: * (possibley different object types), and matches the specified ids. Returns
079: * <code>null</code> if the object is not found.
080: *
081: * @param alias The alias that represents the required mapping
082: * @param ids The ids that identifies the resource
083: * @return The resource
084: * @throws CompassException
085: */
086: Resource getResource(String alias, Object... ids)
087: throws CompassException;
088:
089: /**
090: * Loads and returns a Resource that match the mapping specified for the
091: * defined class, and matches the specified id. The id can be an object of
092: * the class (with the id attributes set), an array of id objects, or the
093: * actual id object. Throws an exception if the resource is not found.
094: *
095: * @param clazz The class that represents the required mapping
096: * @param id The id that identifies the resource
097: * @return The resource
098: * @throws CompassException
099: */
100: Resource loadResource(Class clazz, Object id)
101: throws CompassException;
102:
103: /**
104: * Loads and returns a Resource that match the mapping specified for the
105: * defined class, and matches the specified ids. Throws an exception if
106: * the resource is not found.
107: *
108: * @param clazz The class that represents the required mapping
109: * @param ids The ids that identifies the resource
110: * @return The resource
111: * @throws CompassException
112: */
113: Resource loadResource(Class clazz, Object... ids)
114: throws CompassException;
115:
116: /**
117: * Loads and returns a Resource that match the mapping specified for the
118: * defined alias, and matches the specified id. The id can be an object of
119: * the class (with the id attributes set), an array of id objects, or the
120: * actual id object. Throws an exception if the resource is not found.
121: *
122: * @param alias The alias that represents the required mapping
123: * @param id The id that identifies the resource
124: * @return The resource
125: * @throws CompassException
126: */
127: Resource loadResource(String alias, Object id)
128: throws CompassException;
129:
130: /**
131: * Loads and returns a Resource that match the mapping specified for the
132: * defined alias, and matches the specified ids. Throws an exception if
133: * the resource is not found.
134: *
135: * @param alias The alias that represents the required mapping
136: * @param ids The ids that identifies the resource
137: * @return The resource
138: * @throws CompassException
139: */
140: Resource loadResource(String alias, Object... ids)
141: throws CompassException;
142:
143: /**
144: * Saves a resource within Search Engine.
145: *
146: * @param resource The resource to save
147: * @throws CompassException
148: */
149: void saveResource(Resource resource) throws CompassException;
150:
151: /**
152: * Deletes an object from Compass. The object must have been either loaded
153: * by Compass or it's ids must be set if already known.
154: *
155: * @param obj The object to delete
156: * @throws CompassException
157: */
158: void delete(Object obj) throws CompassException;
159:
160: /**
161: * Deletes an object from Compass with multiple alias's. The object can
162: * either be the id (or an array of ids), or the actual data object with
163: * it's property ids set.
164: *
165: * @param alias The alias that the objects maps under
166: * @param obj The object to delete
167: * @throws CompassException
168: */
169: void delete(String alias, Object obj) throws CompassException;
170:
171: /**
172: * Deletes an object from Compass with multiple alias's based on
173: * its ids.
174: *
175: * @param alias The alias that the objects maps under
176: * @param ids The ids of the object to delete
177: * @throws CompassException
178: */
179: void delete(String alias, Object... ids) throws CompassException;
180:
181: /**
182: * Deletes an object from Compass that match the mapping specified for the defined class.
183: * The object can either be the id (or an array of ids), or the actual data object with
184: * it's property ids set.
185: *
186: * @param clazz The class that represtents the required mapping
187: * @param obj The object to delete
188: * @throws CompassException
189: */
190: void delete(Class clazz, Object obj) throws CompassException;
191:
192: /**
193: * Deletes an object from Compass that match the mapping specified for the defined class
194: * based on its ids.
195: *
196: * @param clazz The class that represtents the required mapping
197: * @param ids The object ids to delete
198: * @throws CompassException
199: */
200: void delete(Class clazz, Object... ids) throws CompassException;
201:
202: /**
203: * Returns an object that match the mapping specified for the defined class,
204: * and matches the specified id. The id can be an object of the class (with
205: * the id attributes set), an array of id objects, or the actual id object.
206: * Returns <code>null</code> if the object is not found.
207: *
208: * @param clazz The class that represents the required mapping
209: * @param id The id that identifies the resource
210: * @return The object, returns <code>null</code> if not found
211: * @throws CompassException
212: */
213: <T> T get(Class<T> clazz, Object id) throws CompassException;
214:
215: /**
216: * Returns an object that match the mapping specified for the defined class,
217: * and matches the specified ids. Returns <code>null</code> if the object
218: * is not found.
219: *
220: * @param clazz The class that represents the required mapping
221: * @param ids The ids that identifies the resource
222: * @return The object, returns <code>null</code> if not found
223: * @throws CompassException
224: */
225: <T> T get(Class<T> clazz, Object... ids) throws CompassException;
226:
227: /**
228: * Returns an object that match the mapping specified for the defined alias,
229: * and matches the specified id. The id can be an object of the class (with
230: * the id attributes set), an array of id objects, or the actual id object.
231: * Returns <code>null</code> if the object is not found.
232: *
233: * @param alias The alias that represents the required mapping
234: * @param id The id that identifies the resource
235: * @return The object, returns <code>null</code> if not found
236: * @throws CompassException
237: */
238: Object get(String alias, Object id) throws CompassException;
239:
240: /**
241: * Returns an object that match the mapping specified for the defined alias,
242: * and matches the specified ids. Returns <code>null</code> if the object is
243: * not found.
244: *
245: * @param alias The alias that represents the required mapping
246: * @param ids The ids that identifies the resource
247: * @return The object, returns <code>null</code> if not found
248: * @throws CompassException
249: */
250: Object get(String alias, Object... ids) throws CompassException;
251:
252: /**
253: * Loads and returns an object that match the mapping specified for the
254: * defined class, and matches the specified id. The id can be an object of
255: * the class (with the id attributes set), an array of id objects, or the
256: * actual id object. Throws an exception if the resource is not found.
257: *
258: * @param clazz The class that represents the required mapping
259: * @param id The id that identifies the resource
260: * @return The object
261: * @throws CompassException
262: */
263: <T> T load(Class<T> clazz, Object id) throws CompassException;
264:
265: /**
266: * Loads and returns an object that match the mapping specified for the
267: * defined class, and matches the specified ids.
268: *
269: * @param clazz The class that represents the required mapping
270: * @param ids The ids that identifies the resource
271: * @return The object
272: * @throws CompassException
273: */
274: <T> T load(Class<T> clazz, Object... ids) throws CompassException;
275:
276: /**
277: * Loads and returns an object that match the mapping specified for the
278: * defined class, and matches the specified id. The id can be an object of
279: * the class (with the id attributes set), an array of id objects, or the
280: * actual id object. Throws an exception if the resource is not found.
281: *
282: * @param alias The alias that represents the required mapping
283: * @param id The id that identifies the resource
284: * @return The object
285: * @throws CompassException
286: */
287: Object load(String alias, Object id) throws CompassException;
288:
289: /**
290: * Loads and returns an object that match the mapping specified for the
291: * defined class, and matches the specified ids.
292: *
293: * @param alias The alias that represents the required mapping
294: * @param ids The ids that identifies the resource
295: * @return The object
296: * @throws CompassException
297: */
298: Object load(String alias, Object... ids) throws CompassException;
299:
300: /**
301: * Deletes all entries in the index that match the given query.
302: *
303: * @param query The query to delete by
304: * @throws CompassException
305: */
306: void delete(CompassQuery query) throws CompassException;
307:
308: /**
309: * Finds a list of objects that match the specified query. The query syntax
310: * is a search engine format query. For detailed description of the query
311: * syntax please visit the site.
312: * <p>
313: * Several examples are:
314: * <ul>
315: * <li>A set of words - i.e. "Jack London". Compass will search the default
316: * property (usually ALL properties, specified in CompassEnvironment).</li>
317: * <li>A set of words prefixed by meta data name - i.e. author:"Jack
318: * London". Compass will search only meta data name author matching keywords
319: * Jack London.
320: * <li>Multiple meta data names - i.e. author:"Jack London" AND book:Fang*.
321: * Compass will search both meta data name author matching keywords Jack
322: * London and meta data name book matching wildcard Fang*</li>
323: * </ul>
324: * </p>
325: * <p>
326: * Note that the list may contains several object types (classes) with no
327: * relation between them (except for the semantic relation).
328: * </p>
329: *
330: * @param query The query string to search by
331: * @return A hits of objects that matches the query string
332: * @throws CompassException
333: */
334: CompassHits find(String query) throws CompassException;
335:
336: /**
337: * Creates a NEW object in Compass. All the meta data defined in the Compass
338: * mapping files will be indexed and saved for later searching. Note that if
339: * the same object (same alias and same id's already exists in the index, it
340: * won't be deleted).
341: *
342: * @param obj The object to save.
343: * @throws CompassException
344: */
345: void create(Object obj) throws CompassException;
346:
347: /**
348: * Creates a NEW object in Compass that shares mapping alais with multiple
349: * objects. All the meta data defined in Compass mapping files will be
350: * indexed and saved for later searching.
351: *
352: * @param alias The alias that match the object mappings
353: * @param obj The object to save
354: * @throws CompassException
355: */
356: void create(String alias, Object obj) throws CompassException;
357:
358: /**
359: * Saves an object in Compass. All the meta data defined in the Compass
360: * mapping files will be indexed and saved for later searching.
361: *
362: * @param obj The object to save.
363: * @throws CompassException
364: */
365: void save(Object obj) throws CompassException;
366:
367: /**
368: * Saves an object in Compass that shares mapping alais with multiple
369: * objects. All the meta data defined in Compass mapping files will be
370: * indexed and saved for later searching.
371: *
372: * @param alias The alias that match the object mappings
373: * @param obj The object to save
374: * @throws CompassException
375: */
376: void save(String alias, Object obj) throws CompassException;
377:
378: /**
379: * Evicts the given object from the first level cache (transaction scoped
380: * cache).
381: *
382: * @param obj The objects to evict.
383: */
384: void evict(Object obj);
385:
386: /**
387: * Evicts the given object from the first level cache (transaction scoped
388: * cache). The object can either be the id (or an array of ids), or the
389: * actual data object with it's property ids set.
390: *
391: * @param alias The alias of the object/entry to evict.
392: * @param id The id of the object/entry to evict.
393: */
394: void evict(String alias, Object id);
395:
396: /**
397: * Evicts the given resource from the first level cache (transaction scoped
398: * cache).
399: *
400: * @param resource The resource to evict.
401: */
402: void evict(Resource resource);
403:
404: /**
405: * Evicts all the objects and the resources from the first level cache.
406: */
407: void evictAll();
408: }
|