BackingStore


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: 169198 $
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 
241
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags