001 package com.sptci.prevayler;
002
003 import org.apache.lucene.search.Filter;
004 import org.apache.lucene.search.Query;
005 import org.apache.lucene.search.Sort;
006
007 import java.io.Serializable;
008 import java.util.Collection;
009 import java.util.Map;
010
011 /**
012 * A base interface that defines the public interface exposed by the database
013 * system. This interface defines the common non-transactional features
014 * supported by the system.
015 *
016 * <p>© Copyright 2008 <a href='http://sptci.com/' target='_top'>Sans
017 * Pareil Technologies, Inc.</a></p>
018 *
019 * @author Rakesh 2008-11-23
020 * @version $Id: AbstractDatabase.java 22 2008-11-24 19:04:25Z sptrakesh $
021 */
022 public interface AbstractDatabase<P extends PrevalentObject> extends Serializable
023 {
024 /**
025 * Return the total number of instances of the specified type in the
026 * prevalent system.
027 *
028 * @param cls The type of the prevalent object whose count is desired.
029 * @return The total number of prevalent objects of the specified type.
030 * @throws PrevalentException If errors are encountered while interacting
031 * with the prevalent system.
032 */
033 int count( Class cls ) throws PrevalentException;
034
035 /**
036 * Retrieve the prevalent object of type with object id.
037 *
038 * @param cls The type of the prevalent object.
039 * @param oid The object id for the prevalent object to retrieve.
040 * @return The prevalent object instance. Returns <code>null</code> if no
041 * such object is stored in the prevalent system.
042 * @throws PrevalentException If errors are encountered while reconstituting
043 * the prevalent object.
044 */
045 P fetch( Class cls, Object oid ) throws PrevalentException;
046
047 /**
048 * Fetch the prevalent objects in the specified range of data. This
049 * method supports display of paginated view of the prevalent objects of
050 * the type specified. Note that the objects are returned in insertion
051 * order.
052 *
053 * @see com.sptci.prevayler.PrimaryStorage#get( long, long )
054 * @param cls The type of prevalent object to retrive.
055 * @param start The starting index (inclusive) from which to fetch the
056 * prevalent objects.
057 * @param end The ending index (exclusive) to which to fetch the
058 * prevalent objects.
059 * @return The collection of prevalent objects. Returns an empty
060 * collection if there are no objects in the specified range.
061 * @throws com.sptci.prevayler.PrevalentException If errors are encountered while fetching the
062 * objects.
063 */
064 Collection<P> fetch( Class cls, long start, long end )
065 throws PrevalentException;
066
067 /**
068 * Fetch the prevalent object(s) of the specified <code>cls</code> type
069 * which has the specified object as the value of the specified
070 * field.
071 *
072 * <p><b>Note:</b> Only indexed fields are searched. If the specified
073 * field is not indexed, this method returns an empty collection.</p>
074 *
075 * @param cls The type of prevalent object to query for.
076 * @param field The name of the field in the prevalent object using which
077 * the results are to be queried.
078 * @param object The value of the field.
079 * @return The collection of prevalent objects who have the specified
080 * object in the field specified. Returns an empty collection if
081 * no results are found.
082 * @throws com.sptci.prevayler.PrevalentException If errors are encountered while reconstituting
083 * the prevalent objects being returned.
084 */
085 Collection<P> fetch( Class cls, String field, Object object )
086 throws PrevalentException;
087
088 /**
089 * Fetch the prevalent object(s) of the specified <code>cls</code> type
090 * which has the specified indexed field values. The results
091 * contain a union of the matching objects.
092 *
093 * <p><b>Note:</b> Only indexed fields are searched. If the specified
094 * field(s) are not indexed, this method ignores those field(s).</p>
095 *
096 * @see #fetch( Class, String, Object )
097 * @param cls The type of prevalent object to query for.
098 * @param parameters The map of parameters to use to filter the
099 * prevalent instances.
100 * @return The collection of prevalent objects that matches the specified
101 * parameters.
102 * @throws com.sptci.prevayler.PrevalentException If errors are encountered while reconstituting
103 * the prevalent objects being returned.
104 */
105 Collection<P> fetchUnion( Class cls, Map<String,?> parameters )
106 throws PrevalentException;
107
108 /**
109 * Fetch the prevalent object(s) of the specified <code>cls</code> type
110 * which has the specified indexed field values. The results
111 * contain an intersection of the matching objects.
112 *
113 * <p><b>Note:</b> Only indexed fields are searched. If the specified
114 * field(s) are not indexed, this method ignores those field(s).</p>
115 *
116 * @see #fetch( Class, String, Object )
117 * @param cls The type of prevalent object to query for.
118 * @param parameters The map of parameters to use to filter the
119 * prevalent instances.
120 * @return The collection of prevalent objects that matches the specified
121 * parameters.
122 * @throws com.sptci.prevayler.PrevalentException If errors are encountered while reconstituting
123 * the prevalent objects being returned.
124 */
125 Collection<P> fetchIntersection( Class cls, Map<String,?> parameters )
126 throws PrevalentException;
127
128 /**
129 * Execute the specified lucene query and return the collection of matching
130 * prevalent objects.
131 *
132 * <p><b>Notes:</b></p>
133 * <ul>
134 * <li>We use built-in lucene analysers which apply a lower-case
135 * filter to the input content. Hence make sure that you specify only
136 * lower-case search clauses in your query.</li>
137 * <li>The results may be restricted to only instances of specific
138 * prevalent classes by adding
139 * <a href='http://docs.rakeshv.org/java/lucene/org/apache/lucene/index/Term.html'>Term</a>
140 * clauses for the class. The
141 * <a href='http://docs.rakeshv.org/java/lucene/org/apache/lucene/document/Document.html'>Document</a>
142 * instance for a prevalent object contains a {@code class}
143 * <a href='http://docs.rakeshv.org/java/lucene/org/apache/lucene/document/Field.html'>Field</a>
144 * which contains the fully qualified class name of the prevalent object.</li>
145 * </ul>
146 *
147 * @param query The lucene query that is to be executed to find matching
148 * prevalent object instances.
149 * @param filter The filter to apply to restrict the query results.
150 * @param count The maximum number to top hits for the search to return.
151 * @param sort The sort criteria to use for the results.
152 * @return The collection of matching instances or an empty collection.
153 * @throws com.sptci.prevayler.PrevalentException If errors are encountered while reconstituting
154 * the prevalent objects being returned.
155 */
156 Collection<P> search( Query query, Filter filter, int count, Sort sort )
157 throws PrevalentException;
158 }