View Javadoc

1   /*
2    *   Copyright 2004 The Apache Software Foundation
3    *
4    *   Licensed under the Apache License, Version 2.0 (the "License");
5    *   you may not use this file except in compliance with the License.
6    *   You may obtain a copy of the License at
7    *
8    *       http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *   Unless required by applicable law or agreed to in writing, software
11   *   distributed under the License is distributed on an "AS IS" BASIS,
12   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *   See the License for the specific language governing permissions and
14   *   limitations under the License.
15   *
16   */
17  package org.apache.ldap.server.partition;
18  
19  
20  import java.util.Map;
21  
22  import javax.naming.Context;
23  import javax.naming.Name;
24  import javax.naming.NamingEnumeration;
25  import javax.naming.NamingException;
26  import javax.naming.directory.Attributes;
27  import javax.naming.directory.ModificationItem;
28  import javax.naming.directory.SearchControls;
29  import javax.naming.directory.SearchResult;
30  
31  import org.apache.ldap.common.filter.ExprNode;
32  import org.apache.ldap.server.configuration.ContextPartitionConfiguration;
33  import org.apache.ldap.server.jndi.ContextFactoryConfiguration;
34  
35  
36  /***
37   * An interfaces that bridges between underlying JNDI entries and JNDI
38   * {@link Context} API.  DIT (Directory Information Tree) consists one or
39   * above {@link ContextPartition}s whose parent is {@link ContextPartitionNexus},
40   * and all of them are mapped to different
41   * base suffix.  Each partition contains entries whose name ends with that
42   * base suffix.
43   *
44   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
45   * @version $Rev: 264732 $
46   */
47  public interface ContextPartition
48  {
49      /*** The objectClass name for aliases: 'alias' */
50      String ALIAS_OBJECT = "alias";
51  
52      /*** 
53       * The aliased Dn attribute name: aliasedObjectName for LDAP and
54       * aliasedEntryName or X.500.
55       */ 
56      String ALIAS_ATTRIBUTE = "aliasedObjectName";
57  
58      /***
59       * Initializes this partition.
60       */
61      void init( ContextFactoryConfiguration factoryCfg, ContextPartitionConfiguration cfg ) throws NamingException;
62      
63      
64      /***
65       * Deinitialized this partition.
66       */
67      void destroy();
68  
69      /***
70       * Checks to see if this partition is initialized or not.
71       */
72      boolean isInitialized();
73  
74      /***
75       * Flushes any changes made to this partition now.
76       */
77      void sync() throws NamingException;
78  
79      
80      /***
81       * Gets the distinguished/absolute name of the suffix for all entries
82       * stored within this ContextPartition.
83       *
84       * @param normalized boolean value used to control the normalization of the
85       * returned Name.  If true the normalized Name is returned, otherwise the 
86       * original user provided Name without normalization is returned.
87       * @return Name representing the distinguished/absolute name of this
88       * ContextPartitions root context.
89       */
90      Name getSuffix( boolean normalized ) throws NamingException;
91  
92      
93      /***
94       * Deletes a leaf entry from this ContextPartition: non-leaf entries cannot be 
95       * deleted until this operation has been applied to their children.
96       *
97       * @param name the normalized distinguished/absolute name of the entry to
98       * delete from this ContextPartition.
99       * @throws NamingException if there are any problems
100      */ 
101     void delete( Name name ) throws NamingException;
102 
103     /***
104      * Adds an entry to this ContextPartition.
105      *
106      * @param userProvidedName the user provided distinguished/absolute name of the entry
107      * @param normalizedName the normalized distinguished/absolute name of the entry
108      * @param entry the entry to add to this ContextPartition
109      * @throws NamingException if there are any problems
110      */
111     void add( String userProvidedName, Name normalizedName, Attributes entry ) throws NamingException;
112 
113     /***
114      * Modifies an entry by adding, removing or replacing a set of attributes.
115      *
116      * @param name the normalized distinguished/absolute name of the entry to
117      * modify
118      * @param modOp the modification operation to perform on the entry which
119      * is one of constants specified by the DirContext interface:
120      * <code>ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE</code>.
121      * @param attributes the attributes and their values used to affect the
122      * modification with.
123      * @throws NamingException if there are any problems
124      * @see javax.naming.directory.DirContext
125      * @see javax.naming.directory.DirContext#ADD_ATTRIBUTE
126      * @see javax.naming.directory.DirContext#REMOVE_ATTRIBUTE
127      * @see javax.naming.directory.DirContext#REPLACE_ATTRIBUTE
128      */
129     void modify( Name name, int modOp, Attributes attributes ) throws NamingException;
130 
131     /***
132      * Modifies an entry by using a combination of adds, removes or replace 
133      * operations using a set of ModificationItems.
134      *
135      * @param name the normalized distinguished/absolute name of the entry to modify
136      * @param items the ModificationItems used to affect the modification with
137      * @throws NamingException if there are any problems
138      * @see ModificationItem
139      */
140     void modify( Name name, ModificationItem [] items ) throws NamingException;
141 
142     /***
143      * A specialized form of one level search used to return a minimal set of 
144      * information regarding child entries under a base.  Convenience method
145      * used to optimize operations rather than conducting a full search with 
146      * retrieval.
147      *
148      * @param baseName the base distinguished/absolute name for the search/listing
149      * @return a NamingEnumeration containing objects of type {@link SearchResult}
150      * @throws NamingException if there are any problems
151      */
152     NamingEnumeration list( Name baseName ) throws NamingException;
153     
154     /***
155      * Conducts a search against this ContextPartition.  Namespace specific
156      * parameters for search are contained within the environment using
157      * namespace specific keys into the hash.  For example in the LDAP namespace
158      * a ContextPartition implementation may look for search Controls using a
159      * namespace specific or implementation specific key for the set of LDAP
160      * Controls.
161      *
162      * @param baseName the normalized distinguished/absolute name of the search base
163      * @param environment the environment under which operation occurs
164      * @param filter the root node of the filter expression tree
165      * @param searchControls the search controls
166      * @throws NamingException if there are any problems
167      * @return a NamingEnumeration containing objects of type 
168      * <a href="http://java.sun.com/j2se/1.4.2/docs/api/
169      * javax/naming/directory/SearchResult.html">SearchResult</a>.
170      */
171     NamingEnumeration search( Name baseName, Map environment, ExprNode filter,
172         SearchControls searchControls ) throws NamingException;
173 
174     /***
175      * Looks up an entry by distinguished/absolute name.  This is a simplified
176      * version of the search operation used to point read an entry used for
177      * convenience.
178      *
179      * @param name the normalized distinguished name of the object to lookup
180      * @return an Attributes object representing the entry
181      * @throws NamingException if there are any problems
182      */
183     Attributes lookup( Name name ) throws NamingException;
184 
185     /***
186      * Looks up an entry by distinguished/absolute name.  This is a simplified
187      * version of the search operation used to point read an entry used for
188      * convenience with a set of attributes to return.  If the attributes is
189      * null or empty, the returned entry will contain all attributes.
190      *
191      * @param name the normalized distinguished name of the object to lookup
192      * @param attrIds the set of attributes to return
193      * @return an Attributes object representing the entry
194      * @throws NamingException if there are any problems
195      */
196     Attributes lookup( Name name, String [] attrIds ) throws NamingException;
197 
198     /***
199      * Fast operation to check and see if a particular entry exists.
200      *
201      * @param name the normalized distinguished/absolute name of the object to
202      * check for existance
203      * @return true if the entry exists, false if it does not
204      * @throws NamingException if there are any problems
205      */
206     boolean hasEntry( Name name ) throws NamingException;
207 
208     /***
209      * Checks to see if name is a context suffix.
210      *
211      * @param name the normalized distinguished/absolute name of the context
212      * @return true if the name is a context suffix, false if it is not.
213      * @throws NamingException if there are any problems
214      */
215     boolean isSuffix( Name name ) throws NamingException;
216 
217     /***
218      * Modifies an entry by changing its relative name. Optionally attributes
219      * associated with the old relative name can be removed from the entry.
220      * This makes sense only in certain namespaces like LDAP and will be ignored
221      * if it is irrelavent.
222      *
223      * @param name the normalized distinguished/absolute name of the entry to
224      * modify the RN of.
225      * @param newRn the new RN of the entry specified by name
226      * @param deleteOldRn boolean flag which removes the old RN attribute
227      * from the entry if set to true, and has no affect if set to false
228      * @throws NamingException if there are any problems
229      */
230     void modifyRn( Name name, String newRn, boolean deleteOldRn )
231         throws NamingException;
232 
233     /***
234      * Transplants a child entry, to a position in the namespace under a new
235      * parent entry.
236      *
237      * @param newParentName the normalized distinguished/absolute name of the
238      * new parent to move the target entry to
239      * @param oldName the normalized distinguished/absolute name of the
240      * original child name representing the child entry to move
241      * @throws NamingException if there are any problems
242      */
243     void move( Name oldName, Name newParentName ) throws NamingException;
244 
245     /***
246      * Transplants a child entry, to a position in the namespace under a new
247      * parent entry and changes the RN of the child entry which can optionally
248      * have its old RN attributes removed.  The removal of old RN attributes
249      * may not make sense in all namespaces.  If the concept is undefined in a
250      * namespace this parameters is ignored.  An example of a namespace where
251      * this parameter is significant is the LDAP namespace.
252      *
253      * @param oldName the normalized distinguished/absolute name of the
254      * original child name representing the child entry to move
255      * @param newParentName the normalized distinguished/absolute name of the
256      * new parent to move the targeted entry to
257      * @param newRn the new RN of the entry
258      * @param deleteOldRn boolean flag which removes the old RN attribute
259      * from the entry if set to true, and has no affect if set to false
260      * @throws NamingException if there are any problems
261      */
262     void move( Name oldName, Name newParentName, String newRn,
263                boolean deleteOldRn ) throws NamingException;
264 }