1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.server.xdbm;
21
22
23 import java.io.File;
24
25 import org.apache.directory.shared.ldap.schema.AttributeType;
26 import org.apache.directory.server.core.cursor.Cursor;
27
28
29 /**
30 * An index into the master table which returns one or more entry's positions
31 * in the master table for those entries which posses an attribute with the
32 * specified value. Cursors over indices can also be gotten to traverse the
33 * values of the index.
34 *
35 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
36 * @version $Rev: 656489 $
37 */
38 public interface Index<K, O>
39 {
40 int DEFAULT_INDEX_CACHE_SIZE = 100;
41
42 // -----------------------------------------------------------------------
43 // C O N F I G U R A T I O N M E T H O D S
44 // -----------------------------------------------------------------------
45
46
47 /**
48 * Gets the attribute identifier set at configuration time for this index which may not
49 * be the OID but an alias name for the attributeType associated with this Index
50 *
51 * @return configured attribute oid or alias name
52 */
53 String getAttributeId();
54
55
56 /**
57 * Sets the attribute identifier set at configuration time for this index which may not
58 * be the OID but an alias name for the attributeType associated with this Index
59 *
60 * @param attributeId configured attribute oid or alias name
61 */
62 void setAttributeId( String attributeId );
63
64
65 /**
66 * Gets the size of the index cache in terms of the number of index entries to be cached.
67 *
68 * @return the size of the index cache
69 */
70 int getCacheSize();
71
72
73 /**
74 * Sets the size of the index cache in terms of the number of index entries to be cached.
75 *
76 * @param cacheSize the size of the index cache
77 */
78 void setCacheSize( int cacheSize );
79
80
81 /**
82 * Sets the working directory path to something other than the default. Sometimes more
83 * performance is gained by locating indices on separate disk spindles.
84 *
85 * @param wkDirPath optional working directory path
86 */
87 void setWkDirPath( File wkDirPath );
88
89
90 /**
91 * Gets the working directory path to something other than the default. Sometimes more
92 * performance is gained by locating indices on separate disk spindles.
93 *
94 * @return optional working directory path
95 */
96 File getWkDirPath();
97
98
99 /**
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 void drop( Long id ) throws Exception;
172
173
174 void drop( K attrVal, Long id ) throws Exception;
175
176
177 IndexCursor<K, O> reverseCursor() throws Exception;
178
179
180 IndexCursor<K, O> forwardCursor() throws Exception;
181
182
183 IndexCursor<K, O> reverseCursor( Long id ) throws Exception;
184
185
186 IndexCursor<K, O> forwardCursor( K key ) throws Exception;
187
188
189 Cursor<K> reverseValueCursor( Long id ) throws Exception;
190
191
192 Cursor<Long> forwardValueCursor( K key ) throws Exception;
193
194
195 boolean forward( K attrVal ) throws Exception;
196
197
198 boolean forward( K attrVal, Long id ) throws Exception;
199
200
201 boolean reverse( Long id ) throws Exception;
202
203
204 boolean reverse( Long id, K attrVal ) throws Exception;
205
206
207 boolean forwardGreaterOrEq( K attrVal ) throws Exception;
208
209
210 boolean forwardGreaterOrEq( K attrVal, Long id ) throws Exception;
211
212
213 boolean reverseGreaterOrEq( Long id ) throws Exception;
214
215
216 boolean reverseGreaterOrEq( Long id, K attrVal ) throws Exception;
217
218
219 boolean forwardLessOrEq( K attrVal ) throws Exception;
220
221
222 boolean forwardLessOrEq( K attrVal, Long id ) throws Exception;
223
224
225 boolean reverseLessOrEq( Long id ) throws Exception;
226
227
228 boolean reverseLessOrEq( Long id, K attrVal ) throws Exception;
229
230
231 void close() throws Exception;
232
233
234 void sync() throws Exception;
235 }