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.api.partition;
21
22
23 import java.io.IOException;
24 import java.io.OutputStream;
25 import java.util.UUID;
26
27 import org.apache.directory.api.ldap.model.entry.Entry;
28 import org.apache.directory.api.ldap.model.exception.LdapException;
29 import org.apache.directory.api.ldap.model.exception.LdapInvalidDnException;
30 import org.apache.directory.api.ldap.model.name.Dn;
31 import org.apache.directory.api.ldap.model.schema.SchemaManager;
32 import org.apache.directory.server.core.api.filtering.EntryFilteringCursor;
33 import org.apache.directory.server.core.api.interceptor.context.AddOperationContext;
34 import org.apache.directory.server.core.api.interceptor.context.DeleteOperationContext;
35 import org.apache.directory.server.core.api.interceptor.context.HasEntryOperationContext;
36 import org.apache.directory.server.core.api.interceptor.context.LookupOperationContext;
37 import org.apache.directory.server.core.api.interceptor.context.ModifyOperationContext;
38 import org.apache.directory.server.core.api.interceptor.context.MoveAndRenameOperationContext;
39 import org.apache.directory.server.core.api.interceptor.context.MoveOperationContext;
40 import org.apache.directory.server.core.api.interceptor.context.RenameOperationContext;
41 import org.apache.directory.server.core.api.interceptor.context.SearchOperationContext;
42 import org.apache.directory.server.core.api.interceptor.context.UnbindOperationContext;
43
44
45 /**
46 * Interface for entry stores containing a part of the DIB (Directory
47 * Information Base). Partitions are associated with a specific suffix, and
48 * all entries contained in the them have the same Dn suffix in common.
49 *
50 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
51 */
52 public interface Partition
53 {
54 /** root ID common to all partitions */
55 String ROOT_ID = new UUID( 0L, 0L ).toString();
56
57 /** Default id used for context entry if context entry doesn't exists */
58 String DEFAULT_ID = new UUID( 0L, 1L ).toString();
59
60 /**
61 * Start a read transaction
62 *
63 * @return a read transaction instance
64 */
65 PartitionReadTxn beginReadTransaction();
66
67
68 /**
69 * Start a write transaction
70 *
71 * @return A write transaction instance
72 */
73 PartitionWriteTxn beginWriteTransaction();
74
75
76 // -----------------------------------------------------------------------
77 // C O N F I G U R A T I O N M E T H O D S
78 // -----------------------------------------------------------------------
79
80 /**
81 * Gets the unique identifier for this partition.
82 *
83 * @return the unique identifier for this partition
84 */
85 String getId();
86
87
88 /**
89 * Sets the unique identifier for this partition.
90 *
91 * @param id the unique identifier for this partition
92 */
93 void setId( String id );
94
95
96 /**
97 * Gets the schema manager assigned to this Partition.
98 *
99 * @return the schema manager
100 */
101 SchemaManager getSchemaManager();
102
103
104 /**
105 * Sets the schema manager assigned to this Partition.
106 *
107 * @param schemaManager The SchemaManager instance
108 */
109 void setSchemaManager( SchemaManager schemaManager );
110
111
112 // -----------------------------------------------------------------------
113 // E N D C O N F I G U R A T I O N M E T H O D S
114 // -----------------------------------------------------------------------
115
116 /**
117 * Initializes this partition. <code>isInitialized()</code> will return <tt>true</tt> if
118 * <code>doInit()</code> returns without any errors. <code>destroy()</code> is called automatically
119 * as a clean-up process if <code>doInit()</code> throws an exception.
120 *
121 * @throws LdapException if initialization fails in any way
122 */
123 void initialize() throws LdapException;
124
125 /**
126 * Repair this partition.
127 *
128 * @throws Exception if repair fails in any way
129 */
130 void repair() throws Exception;
131
132
133 /**
134 * Gets the normalized suffix as an Dn for this Partition after it has
135 * been initialized. Attempts to get this Dn before initialization
136 * throw an IllegalStateException.
137 *
138 * @return the suffix for this Partition.
139 * @throws IllegalStateException if the Partition has not been initialized
140 */
141 Dn getSuffixDn();
142
143
144 /**
145 * Sets the suffix Dn, must be normalized.
146 *
147 * @param suffixDn the new suffix Dn
148 * @throws LdapInvalidDnException If the Dn is invalid
149 */
150 void setSuffixDn( Dn suffixDn ) throws LdapInvalidDnException;
151
152
153 /**
154 * Instructs this Partition to synchronize with it's persistent store, and
155 * destroy all held resources, in preparation for a shutdown event.
156 *
157 * @param partitionTxn The transaction to use
158 * @throws LdapException If we can't destroy the partition
159 */
160 void destroy( PartitionTxn partitionTxn ) throws LdapException;
161
162
163 /**
164 * Checks to see if this partition is initialized or not.
165 *
166 * @return <tt>true</tt> if the partition is initialized, false otherwise
167 */
168 boolean isInitialized();
169
170
171 /**
172 * Flushes any changes made to this partition now.
173 *
174 * @throws LdapException if buffers cannot be flushed to disk
175 */
176 void sync() throws LdapException;
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 deleteContext the context of the entry to
184 * delete from this ContextPartition.
185 * @return The delete Entry, if found
186 * @throws LdapException if there are any problems
187 */
188 Entry delete( DeleteOperationContext deleteContext ) throws LdapException;
189
190
191 /**
192 * Adds an entry to this ContextPartition.
193 *
194 * @param addContext the context used to add and entry to this ContextPartition
195 * @throws LdapException if there are any problems
196 */
197 void add( AddOperationContext addContext ) throws LdapException;
198
199
200 /**
201 * Modifies an entry by adding, removing or replacing a set of attributes.
202 *
203 * @param modifyContext The context containing the modification operation
204 * to perform on the entry which is one of constants specified by the
205 * DirContext interface:
206 * <code>ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE</code>.
207 * @throws LdapException if there are any problems
208 */
209 void modify( ModifyOperationContext modifyContext ) throws LdapException;
210
211
212 /**
213 * Conducts a search against this ContextPartition. Namespace specific
214 * parameters for search are contained within the environment using
215 * namespace specific keys into the hash. For example in the LDAP namespace
216 * a ContextPartition implementation may look for search Controls using a
217 * namespace specific or implementation specific key for the set of LDAP
218 * Controls.
219 *
220 * @param searchContext The context containing the information used by the operation
221 * @return a NamingEnumeration containing objects of type
222 * @throws LdapException if there are any problems
223 */
224 EntryFilteringCursor search( SearchOperationContext searchContext ) throws LdapException;
225
226
227 /**
228 * Looks up an entry by distinguished/absolute name. This is a simplified
229 * version of the search operation used to point read an entry used for
230 * convenience.
231 *
232 * Depending on the context parameters, we my look for a simple entry,
233 * or for a restricted set of attributes for this entry
234 *
235 * @param lookupContext The context containing the parameters
236 * @return an Attributes object representing the entry
237 * @throws LdapException if there are any problems
238 */
239 Entry lookup( LookupOperationContext lookupContext ) throws LdapException;
240
241
242 /**
243 * Fast operation to check and see if a particular entry exists.
244 *
245 * @param hasEntryContext The context used to pass informations
246 * @return true if the entry exists, false if it does not
247 * @throws LdapException if there are any problems
248 */
249 boolean hasEntry( HasEntryOperationContext hasEntryContext ) throws LdapException;
250
251
252 /**
253 * Modifies an entry by changing its relative name. Optionally attributes
254 * associated with the old relative name can be removed from the entry.
255 * This makes sense only in certain namespaces like LDAP and will be ignored
256 * if it is irrelevant.
257 *
258 * @param renameContext the modify Dn context
259 * @throws LdapException if there are any problems
260 */
261 void rename( RenameOperationContext renameContext ) throws LdapException;
262
263
264 /**
265 * Transplants a child entry, to a position in the namespace under a new
266 * parent entry.
267 *
268 * @param moveContext The context containing the DNs to move
269 * @throws LdapException if there are any problems
270 */
271 void move( MoveOperationContext moveContext ) throws LdapException;
272
273
274 /**
275 * Transplants a child entry, to a position in the namespace under a new
276 * parent entry and changes the RN of the child entry which can optionally
277 * have its old RN attributes removed. The removal of old RN attributes
278 * may not make sense in all namespaces. If the concept is undefined in a
279 * namespace this parameters is ignored. An example of a namespace where
280 * this parameter is significant is the LDAP namespace.
281 *
282 * @param moveAndRenameContext The context contain all the information about
283 * the modifyDN operation
284 * @throws LdapException if there are any problems
285 */
286 void moveAndRename( MoveAndRenameOperationContext moveAndRenameContext ) throws LdapException;
287
288
289 /**
290 * Represents an unbind operation issued by an authenticated client. Partitions
291 * need not support this operation. This operation is here to enable those
292 * interested in implementing virtual directories with ApacheDS.
293 *
294 * @param unbindContext the context used to unbind
295 * @throws LdapException if something goes wrong
296 */
297 void unbind( UnbindOperationContext unbindContext ) throws LdapException;
298
299
300 /**
301 * Dump the requested index to a given stream
302 *
303 * @param partitionTxn The transaction to use
304 * @param stream The Stream used to dump the index
305 * @param name The index to dump to stdout
306 * @throws IOException if we can't write the data
307 */
308 void dumpIndex( PartitionTxn partitionTxn, OutputStream stream, String name ) throws IOException;
309
310
311
312 /**
313 * Get the contextCSN
314 *
315 * @param partitionTxn The transaction to use
316 * @return the current highest committed CSN value
317 */
318 String getContextCsn( PartitionTxn partitionTxn );
319
320
321 /**
322 * Saves the context CSN value in the context entry of the partition
323 *
324 * @param partitionTxn The transaction to use
325 * @throws LdapException If the context can't be saved
326 */
327 void saveContextCsn( PartitionTxn partitionTxn ) throws LdapException;
328
329
330 /**
331 * Return the number of children and subordinates for a given entry
332 *
333 * @param partitionTxn The transaction to use
334 * @param entry The entry
335 * @return The Subordinate instance that contains the values.
336 * @throws LdapException If we had an issue while processing the request
337 */
338 Subordinates getSubordinates( PartitionTxn partitionTxn, Entry entry ) throws LdapException;
339 }