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;
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