01: /*
02: *Copyright (C) <2005> <Steve Woodcock>
03: *
04: * Created on 01 June 2005, 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 caches that are Name Spaced
13: * indexes.<p>
14: *
15: * The interface uses similar methods to the Map interface as most cache implementations
16: * can be easily adapted to these methods.<p>
17: *
18: * As with the Map classes the metaphors are to add an object use the put method, to retrieve an
19: * object use get(nameSpace,key) and to remove use remove(nameSpace,key).
20: * <p>
21: * The additional parameter on all these methods is a nameSpace object. The format of this object
22: * will depend on the cache implementation used. For JBossCache, for instance, the name Space is
23: * of type org.jboss.cache.Fqn.
24: * <p>
25: * The additional query method is for clients to query the cache by values other than the key. Please refer to
26: * the docs on IndexQuery.
27: * <p>
28: * It is important to realise that although the interface takes an Object as both key and value, some caches will only
29: * allow certain types of Objects to be inserted. Check with the actual cache provider used to determine
30: * these limitations.
31: * <p>
32: * The usage to obtain an indexed cache is to create a com.jofti.manager.IndexManager then use the
33: * getNameSpacedIndex method to obtain a reference to the indexed cache. You cannot retrieve a nameSpaced indexed cache using the
34: * getIndex method.
35: * <p>
36: *
37: *
38: * @author Steve Woodcock<br>
39: * @version 1.4 <br>
40: *
41: */
42: public interface NameSpacedIndex extends CacheAccessor, Index {
43:
44: /**
45: * Puts an object into the underlying cache instance and indexes the object according to
46: * the class definitions in the index config file. Some caches may only accept certain types of
47: * objects.<p>
48: *
49: * @param nameSpace value to use for nameSpace<br>
50: * @param key value to use as key in cache<p>
51: * @param value value to put into cache and to be indexed<p>
52: * @throws JoftiException thrown as a wrapper exception that contains any cache specific exceptions.<p>
53: */
54:
55: public void put(Object nameSpace, Object key, Object value)
56: throws JoftiException;
57:
58: /**
59: * Retrieves an object from the underlying cache instance. The behaviour of the caches have
60: * been normalised so that a not found object will always return null - rather than throw an exception (as some caches do) any cache error
61: * tranformed into a log message only. This method only provides this normalised behaviour as it the
62: * caches are usually read-mostly in operation and most caches already do this.
63: * <p>
64: * @param nameSpace value to use for nameSpace <p>
65: * @param key the key for the object in the name sapce cache<br>
66: * @return the object mapped in the cache - or null if no object found.<p>
67: */
68:
69: public Object get(Object nameSpace, Object key);
70:
71: /**
72: * Deletes an object from the underlying cache. Attempting to remove a non-existant object will
73: * not generate an exception. This will also remove the key/object from the index.
74: * <p>
75: * @param nameSpace value to use for nameSpace <br>
76: * @param key the key to remove from the cache<br>
77: * @throws JoftiException - A wrapper for any cache specific exceptions or exceptions generated by the index.<br>
78: */
79: public void remove(Object nameSpace, Object key)
80: throws JoftiException;
81:
82: /**
83: * Deletes all objects from the underlying cache within the namespace. Attempting to remove a non-existant object will
84: * not generate an exception. This will also remove the key/object entries for the namespace from the index.
85: * <p>
86: * @param nameSpace value to use for nameSpace<br>
87:
88: * @throws JoftiException - A wrapper for any cache specific exceptions or exceptions generated by the index.
89: */
90: public void removeNameSpace(Object nameSpace) throws JoftiException;
91:
92: /**
93: * This will remove all the values in the cache and dump the current index.<p>
94:
95: * @throws JoftiException A wrapper for any cache specific exceptions or exceptions generated by the index.
96: */
97: public void removeAll() throws JoftiException;
98:
99: }
|