01: /*
02: * Copyright (C) <2005> <Steve Woodcock>
03: *
04: * Created on 01 June 2003, 08:12
05: */
06:
07: package com.jofti.api;
08:
09: import com.jofti.exception.JoftiException;
10:
11: /**
12: * The main interface used by clients of index wrappers that are not Name Spaced.
13: * <p>
14: * The interface uses similar methods to the Map interface as most cache implementations
15: * can be easily adapted to these methods.<p>
16: *
17: * As with the Map classes the metaphors are to add an object use the put method, to retrieve an
18: * object use get(key) and to remove use remove(key).
19: * <p>
20: * The additional query method is for clients to query the cache by values other than the key. Please refer to
21: * the docs on IndexQuery.
22: * <p>
23: * It is important to realise that although the interface takes an Object as both key and value, some caches will only
24: * allow certain types of Objects to be inserted. Check with the actual cache provider used to determine
25: * these limitations.
26: * <p>
27: * The usage to obtain a cache is to create a com.jofti.manager.IndexManager then use the
28: * getIndexCache method to obtain a reference to the index. Where a listener implementation is available it is
29: * recommended to configure a listener adapter and perform the puts/gets directly on the cache implementation. This Inteface should be used
30: * where you want to be able to swap cache implmentations with no code change or you need to use a cache, such as Map, that has no callback capability.
31: * <p>
32: *
33: *
34: * @author Steve Woodcock (steve@jofti.com)<br>
35: * @version 1.3<br>
36: *
37: */
38: public interface IndexCache extends CacheAccessor, Index {
39:
40: /**
41: * Puts an object into the underlying cache instance and indexes the object according to
42: * the class definitions in the index config file. Some caches may only accept certain types of
43: * object.<p>
44: * @param key value to use as key in cache
45: * @param value value to put into cache and to be indexed
46: * @throws JoftiException thrown as a wrapper exception that contains any cache specific exceptions.
47: */
48: public void put(Object key, Object value) throws JoftiException;
49:
50: /**
51: * Retrieves an object from the underlying cache instance. The behaviour of the caches have
52: * been normalised so that a not found object will always return null - rather than throw an exception (as some caches do). A cache error
53: * (if any) will be tranformed into a log message only.
54: * <p>
55: * @param key -the key to retrieve the cached object
56: * @return the object mapped in the cache - or null if no object found.
57: */
58: public Object get(Object key);
59:
60: /**
61: * Deletes an object from the underlying cache. Attempting to remove a non-existent, or expired object will
62: * not generate an exception. Note: this behaviour has been normalised so that all caches appear conform to this idipom.
63: * This will also remove the key/object from the index.
64: * <p>
65: * @param key -the key to retrieve the cached object
66: * @throws JoftiException - A wrapper for any cache specific exceptions or exceptions generated by the index.
67: */
68: public void remove(Object key) throws JoftiException;
69:
70: /**
71: * This will remove all the values in the cache and dump the current index.<p>
72: * @throws JoftiException
73: */
74: public void removeAll() throws JoftiException;
75:
76: }
|