KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > ldap > server > 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 JavaDoc;
23 import javax.naming.NamingEnumeration JavaDoc;
24 import javax.naming.NamingException JavaDoc;
25 import javax.naming.directory.Attributes JavaDoc;
26 import javax.naming.directory.ModificationItem JavaDoc;
27 import javax.naming.directory.SearchControls JavaDoc;
28 import java.util.Map JavaDoc;
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 JavaDoc name ) throws NamingException JavaDoc;
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 JavaDoc upName, Name JavaDoc normName, Attributes JavaDoc entry ) throws NamingException JavaDoc;
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 JavaDoc name, int modOp, Attributes JavaDoc mods ) throws NamingException JavaDoc;
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 JavaDoc name, ModificationItem JavaDoc [] mods ) throws NamingException JavaDoc;
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 JavaDoc list( Name JavaDoc base ) throws NamingException JavaDoc;
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 JavaDoc search( Name JavaDoc base, Map JavaDoc env, ExprNode filter,
123         SearchControls JavaDoc searchCtls ) throws NamingException JavaDoc;
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 JavaDoc lookup( Name JavaDoc name ) throws NamingException JavaDoc;
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 JavaDoc lookup( Name JavaDoc dn, String JavaDoc [] attrIds ) throws NamingException JavaDoc;
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 JavaDoc name ) throws NamingException JavaDoc;
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 JavaDoc name ) throws NamingException JavaDoc;
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 JavaDoc name, String JavaDoc newRn, boolean deleteOldRn )
182         throws NamingException JavaDoc;
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 JavaDoc oriChildName, Name JavaDoc newParentName ) throws NamingException JavaDoc;
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 JavaDoc oriChildName, Name JavaDoc newParentName, String JavaDoc newRn,
214                boolean deleteOldRn ) throws NamingException JavaDoc;
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 JavaDoc;
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 JavaDoc;
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
Popular Tags