1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.ldap.server;
18
19
20 import org.apache.ldap.common.filter.ExprNode;
21
22 import javax.naming.Name;
23 import javax.naming.NamingEnumeration;
24 import javax.naming.NamingException;
25 import javax.naming.directory.Attributes;
26 import javax.naming.directory.ModificationItem;
27 import javax.naming.directory.SearchControls;
28 import java.util.Map;
29
30
31 /***
32 * An interface to a store for JNDI Attributes within a hierarchical namespace.
33 * Currently we only have a BackingStore designed for managing LDAP/X.500
34 * namespaces although foreseeably other hierarchical namespaces (directories)
35 * can have BackingStore's implemented for them. A BackingStore contains the
36 * set of operations that can be performed on a JNDI Attributes.
37 *
38 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
39 * @version $Rev: 159259 $
40 */
41 public interface BackingStore
42 {
43 /***
44 * Deletes a leaf entry from this BackingStore: non-leaf entries cannot be
45 * deleted until this operation has been applied to their children.
46 *
47 * @param name the normalized distinguished/absolute name of the entry to
48 * delete from this BackingStore.
49 * @throws NamingException if there are any problems
50 */
51 void delete( Name name ) throws NamingException;
52
53 /***
54 * Adds an entry to this BackingStore.
55 *
56 * @param upName the user provided distinguished/absolute name of the entry
57 * @param normName the normalized distinguished/absolute name of the entry
58 * @param entry the entry to add to this BackingStore
59 * @throws NamingException if there are any problems
60 */
61 void add( String upName, Name normName, Attributes entry ) throws NamingException;
62
63 /***
64 * Modifies an entry by adding, removing or replacing a set of attributes.
65 *
66 * @param name the normalized distinguished/absolute name of the entry to
67 * modify
68 * @param modOp the modification operation to perform on the entry which
69 * is one of constants specified by the DirContext interface:
70 * <code>ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE</code>.
71 * @param mods the attributes and their values used to affect the
72 * modification with.
73 * @throws NamingException if there are any problems
74 * @see javax.naming.directory.DirContext
75 * @see javax.naming.directory.DirContext#ADD_ATTRIBUTE
76 * @see javax.naming.directory.DirContext#REMOVE_ATTRIBUTE
77 * @see javax.naming.directory.DirContext#REPLACE_ATTRIBUTE
78 */
79 void modify( Name name, int modOp, Attributes mods ) throws NamingException;
80
81 /***
82 * Modifies an entry by using a combination of adds, removes or replace
83 * operations using a set of ModificationItems.
84 *
85 * @param name the normalized distinguished/absolute name of the entry to modify
86 * @param mods the ModificationItems used to affect the modification with
87 * @throws NamingException if there are any problems
88 * @see ModificationItem
89 */
90 void modify( Name name, ModificationItem [] mods ) throws NamingException;
91
92 /***
93 * A specialized form of one level search used to return a minimal set of
94 * information regarding child entries under a base. Convenience method
95 * used to optimize operations rather than conducting a full search with
96 * retrieval.
97 *
98 * @param base the base distinguished/absolute name for the search/listing
99 * @return a NamingEnumeration containing objects of type
100 * {@link org.apache.ldap.server.db.DbSearchResult}
101 * @throws NamingException if there are any problems
102 */
103 NamingEnumeration list( Name base ) throws NamingException;
104
105 /***
106 * Conducts a search against this BackingStore. Namespace specific
107 * parameters for search are contained within the environment using
108 * namespace specific keys into the hash. For example in the LDAP namespace
109 * a BackingStore implementation may look for search Controls using a
110 * namespace specific or implementation specific key for the set of LDAP
111 * Controls.
112 *
113 * @param base the normalized distinguished/absolute name of the search base
114 * @param env the environment under which operation occurs
115 * @param filter the root node of the filter expression tree
116 * @param searchCtls the search controls
117 * @throws NamingException if there are any problems
118 * @return a NamingEnumeration containing objects of type
119 * <a href="http://java.sun.com/j2se/1.4.2/docs/api/
120 * javax/naming/directory/SearchResult.html">SearchResult</a>.
121 */
122 NamingEnumeration search( Name base, Map env, ExprNode filter,
123 SearchControls searchCtls ) throws NamingException;
124
125 /***
126 * Looks up an entry by distinguished/absolute name. This is a simplified
127 * version of the search operation used to point read an entry used for
128 * convenience.
129 *
130 * @param name the normalized distinguished name of the object to lookup
131 * @return an Attributes object representing the entry
132 * @throws NamingException if there are any problems
133 */
134 Attributes lookup( Name name ) throws NamingException;
135
136 /***
137 * Looks up an entry by distinguished name. This is a simplified version
138 * of the search operation used to point read an entry used for convenience
139 * with a set of attributes to return. If the attributes are null or emty
140 * this defaults to the lookup opertion without the attributes.
141 *
142 * @param dn the normalized distinguished name of the object to lookup
143 * @param attrIds the set of attributes to return
144 * @return an Attributes object representing the entry
145 * @throws NamingException if there are any problems
146 */
147 Attributes lookup( Name dn, String [] attrIds ) throws NamingException;
148
149 /***
150 * Fast operation to check and see if a particular entry exists.
151 *
152 * @param name the normalized distinguished/absolute name of the object to
153 * check for existance
154 * @return true if the entry exists, false if it does not
155 * @throws NamingException if there are any problems
156 */
157 boolean hasEntry( Name name ) throws NamingException;
158
159 /***
160 * Checks to see if name is a context suffix.
161 *
162 * @param name the normalized distinguished/absolute name of the context
163 * @return true if the name is a context suffix, false if it is not.
164 * @throws NamingException if there are any problems
165 */
166 boolean isSuffix( Name name ) throws NamingException;
167
168 /***
169 * Modifies an entry by changing its relative name. Optionally attributes
170 * associated with the old relative name can be removed from the entry.
171 * This makes sense only in certain namespaces like LDAP and will be ignored
172 * if it is irrelavent.
173 *
174 * @param name the normalized distinguished/absolute name of the entry to
175 * modify the RN of.
176 * @param newRn the new RN of the entry specified by name
177 * @param deleteOldRn boolean flag which removes the old RN attribute
178 * from the entry if set to true, and has no affect if set to false
179 * @throws NamingException if there are any problems
180 */
181 void modifyRn( Name name, String newRn, boolean deleteOldRn )
182 throws NamingException;
183
184 /***
185 * Transplants a child entry, to a position in the namespace under a new
186 * parent entry.
187 *
188 * @param newParentName the normalized distinguished/absolute name of the
189 * new parent to move the target entry to
190 * @param oriChildName the normalized distinguished/absolute name of the
191 * original child name representing the child entry to move
192 * @throws NamingException if there are any problems
193 */
194 void move( Name oriChildName, Name newParentName ) throws NamingException;
195
196 /***
197 * Transplants a child entry, to a position in the namespace under a new
198 * parent entry and changes the RN of the child entry which can optionally
199 * have its old RN attributes removed. The removal of old RN attributes
200 * may not make sense in all namespaces. If the concept is undefined in a
201 * namespace this parameters is ignored. An example of a namespace where
202 * this parameter is significant is the LDAP namespace.
203 *
204 * @param oriChildName the normalized distinguished/absolute name of the
205 * original child name representing the child entry to move
206 * @param newParentName the normalized distinguished/absolute name of the
207 * new parent to move the targeted entry to
208 * @param newRn the new RN of the entry
209 * @param deleteOldRn boolean flag which removes the old RN attribute
210 * from the entry if set to true, and has no affect if set to false
211 * @throws NamingException if there are any problems
212 */
213 void move( Name oriChildName, Name newParentName, String newRn,
214 boolean deleteOldRn ) throws NamingException;
215
216 /***
217 * Cue to BackingStores with caches to flush entry and index changes to disk.
218 *
219 * @throws NamingException if there are problems flushing caches
220 */
221 void sync() throws NamingException;
222
223 /***
224 * Closes or shuts down this BackingStore. Operations against closed
225 * BackingStores will fail.
226 *
227 * @throws NamingException if there are problems shutting down
228 */
229 void close() throws NamingException;
230
231 /***
232 * Checks to see if this BackingStore has been closed or shut down.
233 * Operations against closed BackingStores will fail.
234 *
235 * @return true if shut down, false otherwise
236 */
237 boolean isClosed();
238 }
239
240