IndexManager


1   /*
2    * Copyright (C) <2005>  <Steve Woodcock>
3    * 
4    * Created on Jul 31, 2005
5    *
6    */
7   package com.jofti.api;
8   
9   import java.io.InputStream  ;
10  
11  import com.jofti.config.IndexConfig;
12  import com.jofti.exception.JoftiException;
13  
14  
15  /**
16   *
17   * 
18   * 
19   * The manager is responsible for providing access to indexes. This class is not a singleton 
20   * and is not intended to be used in that manner.
21   * <p>
22   * The usage for the IndexCache manager is either to retrieve an indexed cache that has been configured via a configuration file:
23   *  e.g. <p>
24   * IndexManager manager = new IndexManagerImpl();<br>
25   * manager.setConfigFile("configFile");<br>
26   * manager.init();  <br>
27   * Index index = manager.getIndexCache("name");<br>
28   * <p>
29   * or:
30   * <p>
31   * IndexManager manager = new IndexManagerImpl();<br>
32   * manager.init(inputStream);   <br>
33   * IndexCache index = (IndexCache)manager.getIndexCache("name");<br>
34   * <p>
35   * or by using one the addIndex methods:
36   * <p>
37   * 
38   * IndexManager manager = new IndexManagerImpl();<br>
39   * manager.init();  <br>
40   * IndexCache index = (IndexCache)manager.addIndexCache(indexConfig, "fileName");<br>
41   * <p>
42   * or
43   * IndexManager manager = new IndexManagerImpl();<br>
44   * manager.init();  <br>
45   * Index index = manager.addIndex(indexConfig, cacheImpl);<br>
46   *<p>
47   * The recommended usage for pre-existing Caches is to use the addIndex method and use a 
48   * Listener adapter so all Index updates are managed using the listener callback methods. 
49   * <p>
50   * NameSpaced caches such as JBossCache are obtained using:<br>
51   * <p>
52   * IndexManager manager = new IndexManagerImpl();<br>
53   * manager.init(configFile);    <br>
54   * NameSpacedIndex index = manager.getNameSpacedIndex("name");<br>
55   * 
56    * @author  Steve Woodcock<br>
57   * @version 1.10<p>
58   */
59  public interface IndexManager
60  {
61      /**
62       * Sets a config file to use in the Manager. This file must be on the
63       * classpath.<p>
64       * @param configFile - the filename containing the config - relative to the classpath. 
65       */
66      public abstract void setConfigFile(String   configFile);
67  
68      /**
69       * 
70       * Initialisation method that takes a config file name. This over-rides the
71       * fileName (if any) set in the setConfigFile() method.This method (or one of the other init 
72       * methods) must be called <b>BEFORE</b>  any other method is called on the manager.
73       * <p>
74       * @param configFileName - the filename containing the config - relative to the classpath.
75       * @throws JoftiException - an exception detailing a failure to initialise the cache.
76       */
77      public abstract void init(String   configFileName) throws JoftiException;
78  
79      /**
80       * 
81       * Initialisation method that takes no parameters. This configures the cache with the
82       * fileName set in the setConfigFile() method. This method (or one of the other init 
83       * methods) must be called <b>BEFORE</b>  any other method is called on the manager.
84       * <p>
85       * @throws JoftiException - an exception detailing a failure to initialise the cache.
86       */
87      public abstract void init() throws JoftiException;
88  
89      /**
90       * 
91       * Initialise method that takes an inputstream. This over-rides the fileName
92       * (if any) set in the setConfigFile() method.This method (or one of the other init 
93       * methods must be called <b>BEFORE</b> any other method is called on the manager.
94       * <p>
95       * @param configStream a stream containing the loaded file. 
96       * @throws JoftiException - an exception detailing a failure to initialise the cache.
97       */
98      public abstract void init(InputStream   configStream) throws JoftiException;
99  
100     /**
101      * This method allows cache instances to be added to the manager
102      * programatically rather than at start-up. The usage is for example:
103      * <p>
104      * DefaultIndexConfig config = new DefaultIndexConfig();<br>
105      * config.setName("test"); <br>
106      * Index index =  manager.addIndex(config, cacheImpl,
107      * xml-filename-with-classes-in-it);<br>
108      * <p>
109      * any type of cache can be added in this manner, providing a CacheAdapter
110      * exists for it and the correct adapter has been configured in the 
111      * @link IndexConfig class.<p>
112      * 
113      * If you are using a nameSpaced cache like JBossCache then the usage would
114      * be:
115      * <p>
116      * DefaultIndexConfig config = new DefaultIndexConfig();<br>
117      * config.setName("test"); <br>
118      * NameSpacedIndex index = (NameSpacedIndex)
119      * manager.addIndex(config, cacheImpl, xml-filename-with-classes-in-it);<br>
120      * 
121      * Note: The cache implementations must be started correctly before they are
122      * passed into this method. Added caches are assumed to have been started
123      * and the manager will NOT attempt to initialise the actual cache
124      * implementation.
125      * 
126      * 
127      * @param config -
128      *            the config class containing definitions of the adapter, index
129      *            type and parser to use.<br>
130      * @param cache -
131      *            the cache implementation.<br>
132      * @param classesFileName -
133      *            the xml file containing the classes definitions for the cache.
134      *            This file must be available on the classpath.<br>
135      * @return The added cache.<br>
136      * @throws JoftiException an exception detailing a failure to initialise the cache.
137      */
138     public abstract Index addIndex(IndexConfig config,
139             Object   cache, String   classesFileName) throws JoftiException;
140 
141     /**
142      * This method allows cache instances to be added to the manager
143      * programatically rather than at start-up. <p>
144      * 
145      * 
146      * Any type of cache can be added in this manner, providing a CacheAdapter
147      * exists for it and the correct adapter has been configured in the
148      * @link IndexConfig class.<p>
149      * 
150      * Note: This method is the equivalent of an index entry in the
151      * configuration file. The manager will atttempt to construct and initialise
152      * a new indexed cache based on the attributes in the IndexConfig class and
153      * the class definition file. This method cannot be used with Listener type adapters and an 
154      * attempt to do so will thow an exception.<p>
155      * 
156      * @param config -
157      *            the config class containing definitions of the adapter, index
158      *            type and parser to use.<br>
159      * @param classesFileName -
160      *            the xml file containing the classes definitions for the
161      *            cache. This file must be available on the classpath.
162      * @return The added cache.<br>
163      * @throws JoftiException an exception detailing a failure to initialise the cache.
164      */
165     public abstract Index addIndexCache(IndexConfig config,
166             String   classesFileName) throws JoftiException;
167 
168     
169     /**
170      * This method allows cache instances to be added to the manager
171      * programatically rather than at start-up.<p>
172      * 
173 
174      * Any type of cache can be added in this manner, providing a CacheAdapter
175      * exists for it and the correct adapter has been configured in the
176      * @link IndexConfig class.<p>
177      * 
178      * 
179      * Note: The cache implementations must be started correctly before they are
180      * passed into this method. Added caches are assumed to have been started
181      * and the manager will NOT attempt to initialise the actual cache
182      * implementation.
183      * 
184      *      
185      * @param config -
186      *            the config class containing definitions of the adapter, index
187      *            type and parser to use.<br>
188      * @param cache -
189      *            the cache implementation.<br>
190      * @param stream -
191      *            the inputstream containing the classes definitions for the
192      *            cache loaded from the config xml file.<br>
193      * @return The added Index.<br>
194      * @throws JoftiException  an exception detailing a failure to initialise the cache.
195      * */
196     public Index addIndex(IndexConfig config, Object   cache,
197                 InputStream   stream)  throws JoftiException;
198     
199     /**
200      * This method allows cache instances to be added to the manager
201      * programatically rather than at start-up.<p>
202      * 
203      *  
204      * Any type of cache can be added in this manner, providing a CacheAdapter
205      * exists for it and the correct adapter has been configured in the
206      * @link IndexConfig class. This method will result in the
207      * adapter used creating a new instance of its cache type.<p>
208      * 
209      * Note: This method is the equivalent of an index entry in the
210      * configuration file. The manager will atttempt to construct and initialise
211      * a new indexed cache based solely on the attributes in the IndexConfig
212      * class.<P>
213      * This method cannot be used with Listener type adapters and an 
214      * attempt to do so will thow an exception.<p> 
215      * Class definitions can be added using attribute classMappings in the
216      * IndexConfig class. See this class for details on how to configure these.
217      * <p>
218      * @param config -
219      *            the config class containing definitions of the adapter, index
220      *            type and parser to use.<br>
221      * @return The added Index.
222      * @throws JoftiException   an exception detailing a failure to initialise the cache.
223      */
224     public abstract Index addIndexCache(IndexConfig config)
225             throws JoftiException;
226 
227     /**
228      * This method allows cache instances to be added to the manager
229      * programatically rather than at start-up. The usage is for example:
230      * <p>
231      * DefaultIndexConfig config = new DefaultIndexConfig();<br>
232      * config.setName("test"); <br>
233      * Index index =  manager.addIndex(config, cacheImpl,
234      * xml-filename-with-classes-in-it);<br>
235      * <p>
236      * any type of cache can be added in this manner, providing a CacheAdapter
237      * exists for it and the correct adapter has been configured in the
238      * @link IndexConfig class.<p>
239      * 
240      * If you are using a nameSpaced cache like JBossCache then the usage would
241      * be:
242      * <p>
243      * DefaultIndexConfig config = new DefaultIndexConfig();<br>
244      * config.setName("test"); <br>
245      * NameSpacedIndex index = (NameSpacedIndex)
246      * manager.addIndexedCache(config, cacheImpl);<p>
247      * 
248      * Note: The cache implementations must be started correctly before they are
249      * passed into this method. Added caches are assumed to have been started
250      * and the manager will NOT attempt to initialise the actual cache
251      * implementation.<p>
252      * 
253      * 
254      * @param config -
255      *            the config class containing definitions of the adapter, index
256      *            type and parser to use.<br>
257      * @param cache -
258      *            the cache implementation.<br>
259      * @return The added cache.<br>
260      * @throws JoftiException   an exception detailing a failure to initialise the cache.
261      */
262     public abstract Index addIndex(IndexConfig config,
263             Object   cache) throws JoftiException;
264 
265     /**
266      * Retrieves an indexed cache from the manager. If the cache does not exist in the manager the 
267      * method returns NULL, rather than throw an exception.<p>
268      * 
269      * Attempting to retrieve a name spaced indexed cache using this method will result in an 
270      * exception.<p>
271      * Use this method for Map, EHCache and OSCache types.<p>
272      * @param indexName - the key name to retrive the indexed cache. This set in the config as the Name.<br>
273      * @return - the cache or NULL if no cache can be found under that name.<br>
274      * 
275      * @throws JoftiException  an exception detailing a failure to retrieve the indexed cache.
276      */
277     public abstract Index getIndexCache(String   indexName) throws JoftiException;
278 
279     
280  
281     /**
282      * Retrieves a name spaced indexed cache from the manager. If the index does not exist in the manager the 
283      * method returns NULL, rather than throw an exception.<p>
284      * Use this method for JBossCache<br>
285      * Attempting to retrieve a non-name spaced indexed cache using this method will result in an 
286      * exception.<p>
287      * @param indexName - the key name to retrive the indexed cache. This set in the config as the Name.<br>
288      * @return - the cache or NULL if no cache can be found under that name.<br>
289      * 
290      * @throws JoftiException an exception detailing a failure to retrieve the indexed cache.
291      */
292     public abstract NameSpacedIndex getNameSpacedIndex(String   indexName)
293             throws JoftiException;
294 
295     
296     /**
297      * Used to only remove an indexed cache from the manager and return the cache instance. You should use this method
298      when you want to remive the index but keep the cache. This is the opposite of the addIndex method.<p>
299      Once this method has been called the index becomes unusable and behaviour if you retain a reference is indeterminate.<p>
300      * 
301      * @param cache - the cache to be removed.
302      */
303     
304     public abstract Object   removeIndex(Object   cache);
305     
306     /**
307      * Used to shutdown and remove an indexed cache from the manager. You should use this method
308      * to remove an indexed cache from the manager and shutdown the cache instance- as some cache implementations explicitly require a 
309      * shutdown phase to be run before they can be removed.<p>
310      * 
311      * @param cache - the cache to be destroyed.
312      */
313     public abstract void destroyIndex(Object   cache);
314     
315     /**
316      * Used to shutdown and remove all indexed caches from the manager. You should always use this method
317      * to stop the manager - as some cache implementations explicitly require a 
318      * shutdown phase to be run before they can be removed.<p>
319      * 
320      */
321     public abstract void destroy();
322     
323   
324     
325     
326 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags