View Javadoc

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 }