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.core.partition; 21 22 23 import org.apache.directory.server.core.DirectoryService; 24 import org.apache.directory.server.core.entry.ClonedServerEntry; 25 import org.apache.directory.server.core.entry.ServerSearchResult; 26 import org.apache.directory.server.core.filtering.EntryFilteringCursor; 27 import org.apache.directory.server.core.interceptor.context.AddOperationContext; 28 import org.apache.directory.server.core.interceptor.context.BindOperationContext; 29 import org.apache.directory.server.core.interceptor.context.DeleteOperationContext; 30 import org.apache.directory.server.core.interceptor.context.EntryOperationContext; 31 import org.apache.directory.server.core.interceptor.context.ListOperationContext; 32 import org.apache.directory.server.core.interceptor.context.LookupOperationContext; 33 import org.apache.directory.server.core.interceptor.context.ModifyOperationContext; 34 import org.apache.directory.server.core.interceptor.context.MoveAndRenameOperationContext; 35 import org.apache.directory.server.core.interceptor.context.MoveOperationContext; 36 import org.apache.directory.server.core.interceptor.context.RenameOperationContext; 37 import org.apache.directory.server.core.interceptor.context.SearchOperationContext; 38 import org.apache.directory.server.core.interceptor.context.UnbindOperationContext; 39 import org.apache.directory.shared.ldap.name.LdapDN; 40 41 import javax.naming.Context; 42 43 44 /** 45 * An interfaces that bridges between underlying JNDI entries and JNDI 46 * {@link Context} API. DIT (Directory Information Tree) consists one or 47 * above {@link Partition}s whose parent is {@link PartitionNexus}, 48 * and all of them are mapped to different 49 * base suffix. Each partition contains entries whose name ends with that 50 * base suffix. 51 * 52 * @org.apache.xbean.XBean 53 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 54 * @version $Rev: 689396 $ 55 */ 56 public interface Partition 57 { 58 /** The name of reserved system partition */ 59 String SYSTEM_PARTITION_NAME = "system"; 60 61 /** default partition implementation class */ 62 String DEFAULT_PARTITION_IMPLEMENTATION = "org.apache.directory.server.core.partition.impl.btree.jdbm.JdbmPartition"; 63 64 /** the default entry cache size to use for a partition */ 65 int DEFAULT_CACHE_SIZE = 10000; 66 67 68 // ----------------------------------------------------------------------- 69 // C O N F I G U R A T I O N M E T H O D S 70 // ----------------------------------------------------------------------- 71 72 73 /** 74 * Gets the unique identifier for this partition. 75 * 76 * @return the unique identifier for this partition 77 */ 78 String getId(); 79 80 81 /** 82 * Sets the unique identifier for this partition. 83 * 84 * @param id the unique identifier for this partition 85 */ 86 void setId( String id ); 87 88 89 /** 90 * Gets the non-normalized suffix for this Partition as a string. 91 * 92 * @return the suffix string for this Partition. 93 */ 94 String getSuffix(); 95 96 97 /** 98 * Sets the non-normalized suffix for this Partition as a string. 99 * 100 * @param suffix the suffix string for this Partition. 101 */ 102 void setSuffix( String suffix ); 103 104 105 /** 106 * Used to specify the entry cache size for a Partition. Various Partition 107 * implementations may interpret this value in different ways: i.e. total cache 108 * size limit verses the number of entries to cache. 109 * 110 * @param cacheSize the size of the cache 111 */ 112 void setCacheSize( int cacheSize ); 113 114 115 /** 116 * Gets the entry cache size for this partition. 117 * 118 * @return the size of the cache 119 */ 120 int getCacheSize(); 121 122 123 // ----------------------------------------------------------------------- 124 // E N D C O N F I G U R A T I O N M E T H O D S 125 // ----------------------------------------------------------------------- 126 127 128 /** 129 * Initializes this partition. 130 * 131 * @param core the directory core for the server. 132 * @throws Exception if initialization fails in any way 133 */ 134 void init( DirectoryService core ) throws Exception; 135 136 137 /** 138 * Deinitialized this partition. 139 */ 140 void destroy() throws Exception; 141 142 143 /** 144 * Checks to see if this partition is initialized or not. 145 * @return true if the partition is initialized, false otherwise 146 */ 147 boolean isInitialized(); 148 149 150 /** 151 * Flushes any changes made to this partition now. 152 * @throws Exception if buffers cannot be flushed to disk 153 */ 154 void sync() throws Exception; 155 156 157 /** 158 * Gets the distinguished/absolute name of the suffix for all entries 159 * stored within this ContextPartition. 160 * 161 * @return Name representing the distinguished/absolute name of this 162 * ContextPartitions root context. 163 * @throws Exception if access or suffix parsing fails 164 */ 165 LdapDN getSuffixDn() throws Exception; 166 167 168 /** 169 * Gets the distinguished/absolute name of the suffix for all entries 170 * stored within this ContextPartition. 171 * 172 * @return Name representing the distinguished/absolute name of this 173 * ContextPartitions root context. 174 * @throws Exception if access or suffix parsing fails 175 */ 176 LdapDN getUpSuffixDn() throws Exception; 177 178 179 /** 180 * Deletes a leaf entry from this ContextPartition: non-leaf entries cannot be 181 * deleted until this operation has been applied to their children. 182 * 183 * @param opContext the context of the entry to 184 * delete from this ContextPartition. 185 * @throws Exception if there are any problems 186 */ 187 void delete( DeleteOperationContext opContext ) throws Exception; 188 189 190 /** 191 * Adds an entry to this ContextPartition. 192 * 193 * @param opContext the context used to add and entry to this ContextPartition 194 * @throws Exception if there are any problems 195 */ 196 void add( AddOperationContext opContext ) throws Exception; 197 198 199 /** 200 * Modifies an entry by adding, removing or replacing a set of attributes. 201 * 202 * @param opContext The contetx containin the modification operation 203 * to perform on the entry which is one of constants specified by the 204 * DirContext interface: 205 * <code>ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE</code>. 206 * 207 * @throws Exception if there are any problems 208 * @see javax.naming.directory.DirContext 209 * @see javax.naming.directory.DirContext#ADD_ATTRIBUTE 210 * @see javax.naming.directory.DirContext#REMOVE_ATTRIBUTE 211 * @see javax.naming.directory.DirContext#REPLACE_ATTRIBUTE 212 */ 213 void modify( ModifyOperationContext opContext ) throws Exception; 214 215 216 /** 217 * A specialized form of one level search used to return a minimal set of 218 * information regarding child entries under a base. Convenience method 219 * used to optimize operations rather than conducting a full search with 220 * retrieval. 221 * 222 * @param opContext the context containing the distinguished/absolute name for the search/listing 223 * @return a NamingEnumeration containing objects of type {@link ServerSearchResult} 224 * @throws Exception if there are any problems 225 */ 226 EntryFilteringCursor list( ListOperationContext opContext ) throws Exception; 227 228 229 /** 230 * Conducts a search against this ContextPartition. Namespace specific 231 * parameters for search are contained within the environment using 232 * namespace specific keys into the hash. For example in the LDAP namespace 233 * a ContextPartition implementation may look for search Controls using a 234 * namespace specific or implementation specific key for the set of LDAP 235 * Controls. 236 * 237 * @param opContext The context containing the information used by the operation 238 * @throws Exception if there are any problems 239 * @return a NamingEnumeration containing objects of type 240 */ 241 EntryFilteringCursor search( SearchOperationContext opContext ) throws Exception; 242 243 244 /** 245 * Looks up an entry by distinguished/absolute name. This is a simplified 246 * version of the search operation used to point read an entry used for 247 * convenience. 248 * 249 * Depending on the context parameters, we my look for a simple entry, 250 * or for a restricted set of attributes for this entry 251 * 252 * @param lookupContext The context containing the parameters 253 * @return an Attributes object representing the entry 254 * @throws Exception if there are any problems 255 */ 256 ClonedServerEntry lookup( LookupOperationContext lookupContext ) throws Exception; 257 258 259 ClonedServerEntry lookup( Long id ) throws Exception; 260 261 262 /** 263 * Fast operation to check and see if a particular entry exists. 264 * 265 * @param opContext The context used to pass informations 266 * @return true if the entry exists, false if it does not 267 * @throws Exception if there are any problems 268 */ 269 boolean hasEntry( EntryOperationContext opContext ) throws Exception; 270 271 /** 272 * Modifies an entry by changing its relative name. Optionally attributes 273 * associated with the old relative name can be removed from the entry. 274 * This makes sense only in certain namespaces like LDAP and will be ignored 275 * if it is irrelavent. 276 * 277 * @param opContext the modify DN context 278 * @throws Exception if there are any problems 279 */ 280 void rename( RenameOperationContext opContext ) throws Exception; 281 282 283 /** 284 * Transplants a child entry, to a position in the namespace under a new 285 * parent entry. 286 * 287 * @param opContext The context containing the DNs to move 288 * @throws Exception if there are any problems 289 */ 290 void move( MoveOperationContext opContext ) throws Exception; 291 292 293 /** 294 * Transplants a child entry, to a position in the namespace under a new 295 * parent entry and changes the RN of the child entry which can optionally 296 * have its old RN attributes removed. The removal of old RN attributes 297 * may not make sense in all namespaces. If the concept is undefined in a 298 * namespace this parameters is ignored. An example of a namespace where 299 * this parameter is significant is the LDAP namespace. 300 * 301 * @param opContext The context contain all the information about 302 * the modifyDN operation 303 * @throws Exception if there are any problems 304 */ 305 void moveAndRename( MoveAndRenameOperationContext opContext ) throws Exception; 306 307 308 /** 309 * Represents a bind operation issued to authenticate a client. Partitions 310 * need not support this operation. This operation is here to enable those 311 * interested in implementing virtual directories with ApacheDS. 312 * 313 * @param opContext the bind context, containing all the needed informations to bind 314 * @throws Exception if something goes wrong 315 */ 316 void bind( BindOperationContext opContext ) throws Exception; 317 318 /** 319 * Represents an unbind operation issued by an authenticated client. Partitions 320 * need not support this operation. This operation is here to enable those 321 * interested in implementing virtual directories with ApacheDS. 322 * 323 * @param opContext the context used to unbind 324 * @throws Exception if something goes wrong 325 */ 326 void unbind( UnbindOperationContext opContext ) throws Exception; 327 }