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    }