KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > jofti > api > IndexCache


1 /*
2  * Copyright (C) <2005> <Steve Woodcock>
3  *
4  * Created on 01 June 2003, 08:12
5  */
6
7 package com.jofti.api;
8
9 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 JavaDoc key, Object JavaDoc 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 JavaDoc get(Object JavaDoc 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 JavaDoc 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    
77   
78     
79     
80 }
81
Popular Tags