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 }