001: /*
002: * Copyright (C) <2005> <Steve Woodcock>
003: *
004: * Created on Jul 31, 2005
005: *
006: */
007: package com.jofti.api;
008:
009: import java.io.InputStream;
010:
011: import com.jofti.config.IndexConfig;
012: import com.jofti.exception.JoftiException;
013:
014: /**
015: *
016: *
017: *
018: * The manager is responsible for providing access to indexes. This class is not a singleton
019: * and is not intended to be used in that manner.
020: * <p>
021: * The usage for the IndexCache manager is either to retrieve an indexed cache that has been configured via a configuration file:
022: * e.g. <p>
023: * IndexManager manager = new IndexManagerImpl();<br>
024: * manager.setConfigFile("configFile");<br>
025: * manager.init(); <br>
026: * Index index = manager.getIndexCache("name");<br>
027: * <p>
028: * or:
029: * <p>
030: * IndexManager manager = new IndexManagerImpl();<br>
031: * manager.init(inputStream); <br>
032: * IndexCache index = (IndexCache)manager.getIndexCache("name");<br>
033: * <p>
034: * or by using one the addIndex methods:
035: * <p>
036: *
037: * IndexManager manager = new IndexManagerImpl();<br>
038: * manager.init(); <br>
039: * IndexCache index = (IndexCache)manager.addIndexCache(indexConfig, "fileName");<br>
040: * <p>
041: * or
042: * IndexManager manager = new IndexManagerImpl();<br>
043: * manager.init(); <br>
044: * Index index = manager.addIndex(indexConfig, cacheImpl);<br>
045: *<p>
046: * The recommended usage for pre-existing Caches is to use the addIndex method and use a
047: * Listener adapter so all Index updates are managed using the listener callback methods.
048: * <p>
049: * NameSpaced caches such as JBossCache are obtained using:<br>
050: * <p>
051: * IndexManager manager = new IndexManagerImpl();<br>
052: * manager.init(configFile); <br>
053: * NameSpacedIndex index = manager.getNameSpacedIndex("name");<br>
054: *
055: * @author Steve Woodcock<br>
056: * @version 1.10<p>
057: */
058: public interface IndexManager {
059: /**
060: * Sets a config file to use in the Manager. This file must be on the
061: * classpath.<p>
062: * @param configFile - the filename containing the config - relative to the classpath.
063: */
064: public abstract void setConfigFile(String configFile);
065:
066: /**
067: *
068: * Initialisation method that takes a config file name. This over-rides the
069: * fileName (if any) set in the setConfigFile() method.This method (or one of the other init
070: * methods) must be called <b>BEFORE</b> any other method is called on the manager.
071: * <p>
072: * @param configFileName - the filename containing the config - relative to the classpath.
073: * @throws JoftiException - an exception detailing a failure to initialise the cache.
074: */
075: public abstract void init(String configFileName)
076: throws JoftiException;
077:
078: /**
079: *
080: * Initialisation method that takes no parameters. This configures the cache with the
081: * fileName set in the setConfigFile() method. This method (or one of the other init
082: * methods) must be called <b>BEFORE</b> any other method is called on the manager.
083: * <p>
084: * @throws JoftiException - an exception detailing a failure to initialise the cache.
085: */
086: public abstract void init() throws JoftiException;
087:
088: /**
089: *
090: * Initialise method that takes an inputstream. This over-rides the fileName
091: * (if any) set in the setConfigFile() method.This method (or one of the other init
092: * methods must be called <b>BEFORE</b> any other method is called on the manager.
093: * <p>
094: * @param configStream a stream containing the loaded file.
095: * @throws JoftiException - an exception detailing a failure to initialise the cache.
096: */
097: public abstract void init(InputStream configStream)
098: throws JoftiException;
099:
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, Object cache,
139: 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: * This method allows cache instances to be added to the manager
170: * programatically rather than at start-up.<p>
171: *
172:
173: * Any type of cache can be added in this manner, providing a CacheAdapter
174: * exists for it and the correct adapter has been configured in the
175: * @link IndexConfig class.<p>
176: *
177: *
178: * Note: The cache implementations must be started correctly before they are
179: * passed into this method. Added caches are assumed to have been started
180: * and the manager will NOT attempt to initialise the actual cache
181: * implementation.
182: *
183: *
184: * @param config -
185: * the config class containing definitions of the adapter, index
186: * type and parser to use.<br>
187: * @param cache -
188: * the cache implementation.<br>
189: * @param stream -
190: * the inputstream containing the classes definitions for the
191: * cache loaded from the config xml file.<br>
192: * @return The added Index.<br>
193: * @throws JoftiException an exception detailing a failure to initialise the cache.
194: * */
195: public Index addIndex(IndexConfig config, Object cache,
196: InputStream stream) throws JoftiException;
197:
198: /**
199: * This method allows cache instances to be added to the manager
200: * programatically rather than at start-up.<p>
201: *
202: *
203: * Any type of cache can be added in this manner, providing a CacheAdapter
204: * exists for it and the correct adapter has been configured in the
205: * @link IndexConfig class. This method will result in the
206: * adapter used creating a new instance of its cache type.<p>
207: *
208: * Note: This method is the equivalent of an index entry in the
209: * configuration file. The manager will atttempt to construct and initialise
210: * a new indexed cache based solely on the attributes in the IndexConfig
211: * class.<P>
212: * This method cannot be used with Listener type adapters and an
213: * attempt to do so will thow an exception.<p>
214: * Class definitions can be added using attribute classMappings in the
215: * IndexConfig class. See this class for details on how to configure these.
216: * <p>
217: * @param config -
218: * the config class containing definitions of the adapter, index
219: * type and parser to use.<br>
220: * @return The added Index.
221: * @throws JoftiException an exception detailing a failure to initialise the cache.
222: */
223: public abstract Index addIndexCache(IndexConfig config)
224: throws JoftiException;
225:
226: /**
227: * This method allows cache instances to be added to the manager
228: * programatically rather than at start-up. The usage is for example:
229: * <p>
230: * DefaultIndexConfig config = new DefaultIndexConfig();<br>
231: * config.setName("test"); <br>
232: * Index index = manager.addIndex(config, cacheImpl,
233: * xml-filename-with-classes-in-it);<br>
234: * <p>
235: * any type of cache can be added in this manner, providing a CacheAdapter
236: * exists for it and the correct adapter has been configured in the
237: * @link IndexConfig class.<p>
238: *
239: * If you are using a nameSpaced cache like JBossCache then the usage would
240: * be:
241: * <p>
242: * DefaultIndexConfig config = new DefaultIndexConfig();<br>
243: * config.setName("test"); <br>
244: * NameSpacedIndex index = (NameSpacedIndex)
245: * manager.addIndexedCache(config, cacheImpl);<p>
246: *
247: * Note: The cache implementations must be started correctly before they are
248: * passed into this method. Added caches are assumed to have been started
249: * and the manager will NOT attempt to initialise the actual cache
250: * implementation.<p>
251: *
252: *
253: * @param config -
254: * the config class containing definitions of the adapter, index
255: * type and parser to use.<br>
256: * @param cache -
257: * the cache implementation.<br>
258: * @return The added cache.<br>
259: * @throws JoftiException an exception detailing a failure to initialise the cache.
260: */
261: public abstract Index addIndex(IndexConfig config, Object cache)
262: throws JoftiException;
263:
264: /**
265: * Retrieves an indexed cache from the manager. If the cache does not exist in the manager the
266: * method returns NULL, rather than throw an exception.<p>
267: *
268: * Attempting to retrieve a name spaced indexed cache using this method will result in an
269: * exception.<p>
270: * Use this method for Map, EHCache and OSCache types.<p>
271: * @param indexName - the key name to retrive the indexed cache. This set in the config as the Name.<br>
272: * @return - the cache or NULL if no cache can be found under that name.<br>
273: *
274: * @throws JoftiException an exception detailing a failure to retrieve the indexed cache.
275: */
276: public abstract Index getIndexCache(String indexName)
277: throws JoftiException;
278:
279: /**
280: * Retrieves a name spaced indexed cache from the manager. If the index does not exist in the manager the
281: * method returns NULL, rather than throw an exception.<p>
282: * Use this method for JBossCache<br>
283: * Attempting to retrieve a non-name spaced indexed cache using this method will result in an
284: * exception.<p>
285: * @param indexName - the key name to retrive the indexed cache. This set in the config as the Name.<br>
286: * @return - the cache or NULL if no cache can be found under that name.<br>
287: *
288: * @throws JoftiException an exception detailing a failure to retrieve the indexed cache.
289: */
290: public abstract NameSpacedIndex getNameSpacedIndex(String indexName)
291: throws JoftiException;
292:
293: /**
294: * Used to only remove an indexed cache from the manager and return the cache instance. You should use this method
295: when you want to remive the index but keep the cache. This is the opposite of the addIndex method.<p>
296: Once this method has been called the index becomes unusable and behaviour if you retain a reference is indeterminate.<p>
297: *
298: * @param cache - the cache to be removed.
299: */
300:
301: public abstract Object removeIndex(Object cache);
302:
303: /**
304: * Used to shutdown and remove an indexed cache from the manager. You should use this method
305: * to remove an indexed cache from the manager and shutdown the cache instance- as some cache implementations explicitly require a
306: * shutdown phase to be run before they can be removed.<p>
307: *
308: * @param cache - the cache to be destroyed.
309: */
310: public abstract void destroyIndex(Object cache);
311:
312: /**
313: * Used to shutdown and remove all indexed caches from the manager. You should always use this method
314: * to stop the manager - as some cache implementations explicitly require a
315: * shutdown phase to be run before they can be removed.<p>
316: *
317: */
318: public abstract void destroy();
319:
320: }
|