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: 917312 $
037 */
038 public interface Index<K, O, ID>
039 {
040 int DEFAULT_INDEX_CACHE_SIZE = 100;
041
042
043 // -----------------------------------------------------------------------
044 // C O N F I G U R A T I O N M E T H O D S
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 * Gets the attribute this Index is built upon.
119 *
120 * @return the id of the Index's attribute
121 */
122 AttributeType getAttribute();
123
124
125 /**
126 * Gets the normalized value for an attribute.
127 *
128 * @param attrVal the user provided value to normalize
129 * @return the normalized value.
130 * @throws Exception if something goes wrong.
131 */
132 K getNormalized( K attrVal ) throws Exception;
133
134
135 /**
136 * Gets the total scan count for this index.
137 *
138 * @return the number of key/value pairs in this index
139 * @throws Exception on failure to access index db files
140 */
141 int count() throws Exception;
142
143
144 /**
145 * Gets the scan count for the occurance of a specific attribute value
146 * within the index.
147 *
148 * @param attrVal the value of the attribute to get a scan count for
149 * @return the number of key/value pairs in this index with the value value
150 * @throws Exception on failure to access index db files
151 */
152 int count( K attrVal ) throws Exception;
153
154
155 int greaterThanCount( K attrVal ) throws Exception;
156
157
158 int lessThanCount( K attrVal ) throws Exception;
159
160
161 ID forwardLookup( K attrVal ) throws Exception;
162
163
164 K reverseLookup( ID id ) throws Exception;
165
166
167 void add( K attrVal, ID id ) throws Exception;
168
169
170 /**
171 * Remove all the reference to an entry from the index.
172 *
173 * As an entry might be referenced more than once in the forward index,
174 * depending on which index we are dealing with, we need to iterate
175 * over all the values contained into the reverse index for this entryId.
176 *
177 * For instance, considering the ObjectClass index for an entry having
178 * three ObjectClasses (top, person, inetOrgPerson), then the reverse
179 * index will contain :
180 *
181 * [entryId, [top, person, inetOrgPerson]]
182 *
183 * and the forward index will contain many entries like :
184 * [top, [..., entryId, ...]]
185 * [person, [..., entryId, ...]]
186 * [inetOrgPerson, [..., entryId, ...]]
187 *
188 * So dropping the entryId means that we must first get all the values from
189 * the reverse index (and we will get [top, person, inetOrgPerson]) then to
190 * iterate through all those values to remove entryId from the associated
191 * list of entryIds.
192 *
193 *
194 * @param entryId The master table entry ID to remove
195 * @throws Exception
196 */
197 void drop( ID entryId ) throws Exception;
198
199
200 void drop( K attrVal, ID id ) throws Exception;
201
202
203 IndexCursor<K, O, ID> reverseCursor() throws Exception;
204
205
206 IndexCursor<K, O, ID> forwardCursor() throws Exception;
207
208
209 IndexCursor<K, O, ID> reverseCursor( ID id ) throws Exception;
210
211
212 IndexCursor<K, O, ID> forwardCursor( K key ) throws Exception;
213
214
215 Cursor<K> reverseValueCursor( ID id ) throws Exception;
216
217
218 Cursor<ID> forwardValueCursor( K key ) throws Exception;
219
220
221 boolean forward( K attrVal ) throws Exception;
222
223
224 boolean forward( K attrVal, ID id ) throws Exception;
225
226
227 boolean reverse( ID id ) throws Exception;
228
229
230 boolean reverse( ID id, K attrVal ) throws Exception;
231
232
233 boolean forwardGreaterOrEq( K attrVal ) throws Exception;
234
235
236 boolean forwardGreaterOrEq( K attrVal, ID id ) throws Exception;
237
238
239 boolean reverseGreaterOrEq( ID id ) throws Exception;
240
241
242 boolean reverseGreaterOrEq( ID id, K attrVal ) throws Exception;
243
244
245 boolean forwardLessOrEq( K attrVal ) throws Exception;
246
247
248 boolean forwardLessOrEq( K attrVal, ID id ) throws Exception;
249
250
251 boolean reverseLessOrEq( ID id ) throws Exception;
252
253
254 boolean reverseLessOrEq( ID id, K attrVal ) throws Exception;
255
256
257 void close() throws Exception;
258
259
260 void sync() throws Exception;
261 }