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 }