001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.server.xdbm;
021
022
023 import java.io.File;
024
025 import org.apache.directory.shared.ldap.cursor.Cursor;
026 import org.apache.directory.shared.ldap.schema.AttributeType;
027
028
029 /**
030 * An index into the master table which returns one or more entry's positions
031 * in the master table for those entries which posses an attribute with the
032 * specified value. Cursors over indices can also be gotten to traverse the
033 * values of the index.
034 *
035 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
036 * @version $Rev: 787602 $
037 */
038 public interface Index<K, O>
039 {
040 int DEFAULT_INDEX_CACHE_SIZE = 100;
041
042 // -----------------------------------------------------------------------
043 // C O N F I G U R A T I O N M E T H O D S
044 // -----------------------------------------------------------------------
045
046
047 /**
048 * Gets the attribute identifier set at configuration time for this index which may not
049 * be the OID but an alias name for the attributeType associated with this Index
050 *
051 * @return configured attribute oid or alias name
052 */
053 String getAttributeId();
054
055
056 /**
057 * Sets the attribute identifier set at configuration time for this index which may not
058 * be the OID but an alias name for the attributeType associated with this Index
059 *
060 * @param attributeId configured attribute oid or alias name
061 */
062 void setAttributeId( String attributeId );
063
064
065 /**
066 * Gets the size of the index cache in terms of the number of index entries to be cached.
067 *
068 * @return the size of the index cache
069 */
070 int getCacheSize();
071
072
073 /**
074 * Sets the size of the index cache in terms of the number of index entries to be cached.
075 *
076 * @param cacheSize the size of the index cache
077 */
078 void setCacheSize( int cacheSize );
079
080
081 /**
082 * Sets the working directory path to something other than the default. Sometimes more
083 * performance is gained by locating indices on separate disk spindles.
084 *
085 * @param wkDirPath optional working directory path
086 */
087 void setWkDirPath( File wkDirPath );
088
089
090 /**
091 * Gets the working directory path to something other than the default. Sometimes more
092 * performance is gained by locating indices on separate disk spindles.
093 *
094 * @return optional working directory path
095 */
096 File getWkDirPath();
097
098
099 /**
100 * Checks whether or not calls to count the number of keys greater than or
101 * less than the key are exact.
102 *
103 * Checking to see the number of values greater than or less than some key
104 * may be excessively costly. Since this is not a critical function but
105 * one that assists in optimizing searches some implementations can just
106 * return a worst case (maximum) guess.
107 *
108 * @return true if the count is an exact value or a worst case guess
109 */
110 boolean isCountExact();
111
112
113 // -----------------------------------------------------------------------
114 // E N D C O N F I G U R A T I O N M E T H O D S
115 // -----------------------------------------------------------------------
116
117
118 /**
119 * Gets the attribute this Index is built upon.
120 *
121 * @return the id of the Index's attribute
122 */
123 AttributeType getAttribute();
124
125
126 /**
127 * Gets the normalized value for an attribute.
128 *
129 * @param attrVal the user provided value to normalize
130 * @return the normalized value.
131 * @throws Exception if something goes wrong.
132 */
133 K getNormalized( K attrVal ) throws Exception;
134
135
136 /**
137 * Gets the total scan count for this index.
138 *
139 * @return the number of key/value pairs in this index
140 * @throws Exception on failure to access index db files
141 */
142 int count() throws Exception;
143
144
145 /**
146 * Gets the scan count for the occurance of a specific attribute value
147 * within the index.
148 *
149 * @param attrVal the value of the attribute to get a scan count for
150 * @return the number of key/value pairs in this index with the value value
151 * @throws Exception on failure to access index db files
152 */
153 int count( K attrVal ) throws Exception;
154
155
156 int greaterThanCount( K attrVal ) throws Exception;
157
158
159 int lessThanCount( K attrVal ) throws Exception;
160
161
162 Long forwardLookup( K attrVal ) throws Exception;
163
164
165 K reverseLookup( Long id ) throws Exception;
166
167
168 void add( K attrVal, Long id ) throws Exception;
169
170
171 /**
172 * Remove all the reference to an entry from the index.
173 *
174 * As an entry might be referenced more than once in the forward index,
175 * depending on which index we are dealing with, we need to iterate
176 * over all the values contained into the reverse index for this entryId.
177 *
178 * For instance, considering the ObjectClass index for an entry having
179 * three ObjectClasses (top, person, inetOrgPerson), then the reverse
180 * index will contain :
181 *
182 * [entryId, [top, person, inetOrgPerson]]
183 *
184 * and the forward index will contain many entries like :
185 * [top, [..., entryId, ...]]
186 * [person, [..., entryId, ...]]
187 * [inetOrgPerson, [..., entryId, ...]]
188 *
189 * So dropping the entryId means that we must first get all the values from
190 * the reverse index (and we will get [top, person, inetOrgPerson]) then to
191 * iterate through all those values to remove entryId from the associated
192 * list of entryIds.
193 *
194 *
195 * @param entryId The master table entry ID to remove
196 * @throws Exception
197 */
198 void drop( Long entryId ) throws Exception;
199
200
201 void drop( K attrVal, Long id ) throws Exception;
202
203
204 IndexCursor<K, O> reverseCursor() throws Exception;
205
206
207 IndexCursor<K, O> forwardCursor() throws Exception;
208
209
210 IndexCursor<K, O> reverseCursor( Long id ) throws Exception;
211
212
213 IndexCursor<K, O> forwardCursor( K key ) throws Exception;
214
215
216 Cursor<K> reverseValueCursor( Long id ) throws Exception;
217
218
219 Cursor<Long> forwardValueCursor( K key ) throws Exception;
220
221
222 boolean forward( K attrVal ) throws Exception;
223
224
225 boolean forward( K attrVal, Long id ) throws Exception;
226
227
228 boolean reverse( Long id ) throws Exception;
229
230
231 boolean reverse( Long id, K attrVal ) throws Exception;
232
233
234 boolean forwardGreaterOrEq( K attrVal ) throws Exception;
235
236
237 boolean forwardGreaterOrEq( K attrVal, Long id ) throws Exception;
238
239
240 boolean reverseGreaterOrEq( Long id ) throws Exception;
241
242
243 boolean reverseGreaterOrEq( Long id, K attrVal ) throws Exception;
244
245
246 boolean forwardLessOrEq( K attrVal ) throws Exception;
247
248
249 boolean forwardLessOrEq( K attrVal, Long id ) throws Exception;
250
251
252 boolean reverseLessOrEq( Long id ) throws Exception;
253
254
255 boolean reverseLessOrEq( Long id, K attrVal ) throws Exception;
256
257
258 void close() throws Exception;
259
260
261 void sync() throws Exception;
262 }