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 }