NameSpacedIndex


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