View Javadoc

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 }