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.core.partition;
021
022
023 import org.apache.directory.server.core.entry.ClonedServerEntry;
024 import org.apache.directory.server.core.entry.ServerSearchResult;
025 import org.apache.directory.server.core.filtering.EntryFilteringCursor;
026 import org.apache.directory.server.core.interceptor.context.AddOperationContext;
027 import org.apache.directory.server.core.interceptor.context.BindOperationContext;
028 import org.apache.directory.server.core.interceptor.context.DeleteOperationContext;
029 import org.apache.directory.server.core.interceptor.context.EntryOperationContext;
030 import org.apache.directory.server.core.interceptor.context.ListOperationContext;
031 import org.apache.directory.server.core.interceptor.context.LookupOperationContext;
032 import org.apache.directory.server.core.interceptor.context.ModifyOperationContext;
033 import org.apache.directory.server.core.interceptor.context.MoveAndRenameOperationContext;
034 import org.apache.directory.server.core.interceptor.context.MoveOperationContext;
035 import org.apache.directory.server.core.interceptor.context.RenameOperationContext;
036 import org.apache.directory.server.core.interceptor.context.SearchOperationContext;
037 import org.apache.directory.server.core.interceptor.context.UnbindOperationContext;
038 import org.apache.directory.shared.ldap.exception.LdapInvalidDnException;
039 import org.apache.directory.shared.ldap.name.DN;
040 import org.apache.directory.shared.ldap.schema.SchemaManager;
041
042
043 /**
044 * Interface for entry stores containing a part of the DIB (Directory
045 * Information Base). Partitions are associated with a specific suffix, and
046 * all entries contained in the them have the same DN suffix in common.
047 *
048 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
049 * @version $Rev: 923721 $
050 */
051 public interface Partition
052 {
053 // -----------------------------------------------------------------------
054 // C O N F I G U R A T I O N M E T H O D S
055 // -----------------------------------------------------------------------
056
057 /**
058 * Gets the unique identifier for this partition.
059 *
060 * @return the unique identifier for this partition
061 */
062 String getId();
063
064
065 /**
066 * Sets the unique identifier for this partition.
067 *
068 * @param id the unique identifier for this partition
069 */
070 void setId( String id );
071
072
073 /**
074 * Gets the user provided suffix for this Partition as a String.
075 */
076 String getSuffix();
077
078
079 /**
080 * Sets the user provided suffix for this Partition as a String.
081 *
082 * @param suffix the suffix String for this Partition.
083 * @throws LdapInvalidDnException if the suffix does not conform to LDAP DN syntax
084 */
085 void setSuffix( String suffix ) throws LdapInvalidDnException;
086
087
088 /**
089 * Gets the schema manager assigned to this Partition.
090 *
091 * @return the schema manager
092 */
093 SchemaManager getSchemaManager();
094
095
096 /**
097 * Sets the schema manager assigned to this Partition.
098 *
099 * @param registries the manager to assign to this Partition.
100 */
101 void setSchemaManager( SchemaManager schemaManager );
102
103
104 // -----------------------------------------------------------------------
105 // E N D C O N F I G U R A T I O N M E T H O D S
106 // -----------------------------------------------------------------------
107
108 /**
109 * Initializes this partition.
110 *
111 * @throws Exception if initialization fails in any way
112 */
113 void initialize() throws Exception;
114
115
116 /**
117 * Gets the normalized suffix as an DN for this Partition after it has
118 * been initialized. Attempts to get this DN before initialization
119 * throw an IllegalStateException.
120 *
121 * @return the suffix for this Partition.
122 * @throws IllegalStateException if the Partition has not been initialized
123 */
124 DN getSuffixDn();
125
126
127 /**
128 * Instructs this Partition to synchronize with it's persistent store, and
129 * destroy all held resources, in preparation for a shutdown event.
130 */
131 void destroy() throws Exception;
132
133
134 /**
135 * Checks to see if this partition is initialized or not.
136 * @return true if the partition is initialized, false otherwise
137 */
138 boolean isInitialized();
139
140
141 /**
142 * Flushes any changes made to this partition now.
143 * @throws Exception if buffers cannot be flushed to disk
144 */
145 void sync() throws Exception;
146
147
148 /**
149 * Deletes a leaf entry from this ContextPartition: non-leaf entries cannot be
150 * deleted until this operation has been applied to their children.
151 *
152 * @param opContext the context of the entry to
153 * delete from this ContextPartition.
154 * @throws Exception if there are any problems
155 */
156 void delete( DeleteOperationContext opContext ) throws Exception;
157
158
159 /**
160 * Adds an entry to this ContextPartition.
161 *
162 * @param opContext the context used to add and entry to this ContextPartition
163 * @throws Exception if there are any problems
164 */
165 void add( AddOperationContext opContext ) throws Exception;
166
167
168 /**
169 * Modifies an entry by adding, removing or replacing a set of attributes.
170 *
171 * @param opContext The context containing the modification operation
172 * to perform on the entry which is one of constants specified by the
173 * DirContext interface:
174 * <code>ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE</code>.
175 *
176 * @throws Exception if there are any problems
177 * @see javax.naming.directory.DirContext
178 * @see javax.naming.directory.DirContext#ADD_ATTRIBUTE
179 * @see javax.naming.directory.DirContext#REMOVE_ATTRIBUTE
180 * @see javax.naming.directory.DirContext#REPLACE_ATTRIBUTE
181 */
182 void modify( ModifyOperationContext opContext ) throws Exception;
183
184
185 /**
186 * A specialized form of one level search used to return a minimal set of
187 * information regarding child entries under a base. Convenience method
188 * used to optimize operations rather than conducting a full search with
189 * retrieval.
190 *
191 * @param opContext the context containing the distinguished/absolute name for the search/listing
192 * @return a NamingEnumeration containing objects of type {@link ServerSearchResult}
193 * @throws Exception if there are any problems
194 */
195 EntryFilteringCursor list( ListOperationContext opContext ) throws Exception;
196
197
198 /**
199 * Conducts a search against this ContextPartition. Namespace specific
200 * parameters for search are contained within the environment using
201 * namespace specific keys into the hash. For example in the LDAP namespace
202 * a ContextPartition implementation may look for search Controls using a
203 * namespace specific or implementation specific key for the set of LDAP
204 * Controls.
205 *
206 * @param opContext The context containing the information used by the operation
207 * @throws Exception if there are any problems
208 * @return a NamingEnumeration containing objects of type
209 */
210 EntryFilteringCursor search( SearchOperationContext opContext ) throws Exception;
211
212
213 /**
214 * Looks up an entry by distinguished/absolute name. This is a simplified
215 * version of the search operation used to point read an entry used for
216 * convenience.
217 *
218 * Depending on the context parameters, we my look for a simple entry,
219 * or for a restricted set of attributes for this entry
220 *
221 * @param lookupContext The context containing the parameters
222 * @return an Attributes object representing the entry
223 * @throws Exception if there are any problems
224 */
225 ClonedServerEntry lookup( LookupOperationContext lookupContext ) throws Exception;
226
227
228 /**
229 * Fast operation to check and see if a particular entry exists.
230 *
231 * @param opContext The context used to pass informations
232 * @return true if the entry exists, false if it does not
233 * @throws Exception if there are any problems
234 */
235 boolean hasEntry( EntryOperationContext opContext ) throws Exception;
236
237
238 /**
239 * Modifies an entry by changing its relative name. Optionally attributes
240 * associated with the old relative name can be removed from the entry.
241 * This makes sense only in certain namespaces like LDAP and will be ignored
242 * if it is irrelevant.
243 *
244 * @param opContext the modify DN context
245 * @throws Exception if there are any problems
246 */
247 void rename( RenameOperationContext opContext ) throws Exception;
248
249
250 /**
251 * Transplants a child entry, to a position in the namespace under a new
252 * parent entry.
253 *
254 * @param opContext The context containing the DNs to move
255 * @throws Exception if there are any problems
256 */
257 void move( MoveOperationContext opContext ) throws Exception;
258
259
260 /**
261 * Transplants a child entry, to a position in the namespace under a new
262 * parent entry and changes the RN of the child entry which can optionally
263 * have its old RN attributes removed. The removal of old RN attributes
264 * may not make sense in all namespaces. If the concept is undefined in a
265 * namespace this parameters is ignored. An example of a namespace where
266 * this parameter is significant is the LDAP namespace.
267 *
268 * @param opContext The context contain all the information about
269 * the modifyDN operation
270 * @throws Exception if there are any problems
271 */
272 void moveAndRename( MoveAndRenameOperationContext opContext ) throws Exception;
273
274
275 /**
276 * Represents a bind operation issued to authenticate a client. Partitions
277 * need not support this operation. This operation is here to enable those
278 * interested in implementing virtual directories with ApacheDS.
279 *
280 * @param opContext the bind context, containing all the needed informations to bind
281 * @throws Exception if something goes wrong
282 */
283 void bind( BindOperationContext opContext ) throws Exception;
284
285
286 /**
287 * Represents an unbind operation issued by an authenticated client. Partitions
288 * need not support this operation. This operation is here to enable those
289 * interested in implementing virtual directories with ApacheDS.
290 *
291 * @param opContext the context used to unbind
292 * @throws Exception if something goes wrong
293 */
294 void unbind( UnbindOperationContext opContext ) throws Exception;
295 }