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    }