01: /*
02: * Copyright (C) <2005> <Steve Woodcock>
03: *
04: * Created on 01 June 2003, 08:12
05: */
06:
07: package com.jofti.api;
08:
09: import java.util.Map;
10:
11: import com.jofti.exception.JoftiException;
12:
13: /**
14: *
15: *
16: * This interface is used as the base interface for Indexes. The index is only
17: * searchable via the query method and is not available for direct manipulation.
18: * <p>
19: * The index does not require that all keys used are of the same type. It is reasonable to
20: * use many different key types. The only restriction is that the key must implement
21: * hashCode() and equals() if the searches are to work properly (as you would expect for HashMap).
22: * <p>
23: * Additionally, some caches have restrictions on key types:
24: * OSCache requires all keys to be String
25: * EHcache requires the key to be Serializable.
26: * <p>
27: * In general usage it is highly recommended (but not required) that you use keys that also implement
28: * Comparable.
29: * <p>
30: * @author Steve Woodcock<br>
31: * @version 1.7<br>
32: *
33: *
34: */
35: public interface Index {
36:
37: /**
38: * This queries the index and retrieves a map of matching elements (if any). The map contains
39: * key/value pairs of the key in the cache and the value stored against it. If ordering is specified in the
40: * query then the iterator provides ordered access to the return values.
41: * <p>
42: * If you are using a NameSpacedIndex the keys returned
43: * in this map are of type @see NameSpaceKey.
44: * <p>
45: * @param query - the type of query to perform against the index and cache.
46: * @return Map a map of the key/value results<br>
47: * @throws JoftiException a wrapper exception for errors in the query. <br>
48: */
49: public Map query(IndexQuery query) throws JoftiException;
50:
51: /**
52: * Adds a Query to the Index. Currently, This only supports EJB or SQL format queries
53: * not the convenience queries.
54: * @param name - the name that the query is stored under.
55: * @param query - the query to be stored in the index.
56: * @return - The parsed query.
57: * @throws JoftiException - Thrown if the query is not able to be parsed.
58: */
59: public IndexQuery addQuery(String name, IndexQuery query)
60: throws JoftiException;
61:
62: /**
63: * Obtains a previously stored query, whether stored programmatically or in a config file.
64: * Returns NULL if the query does not exist in the Index.
65: * @param name
66: * @return Query or NULL if no query is stored under the name.
67: */
68: public IndexQuery getQuery(String name);
69:
70: }
|