1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 }