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.db;
18  
19  
20  import org.apache.ldap.common.schema.AttributeType;
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 java.math.BigInteger;
28  import java.util.Iterator;
29  
30  
31  /***
32   * A database for storing attributes.
33   *
34   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
35   * @version $Rev: 164289 $
36   */
37  public interface Database
38  {
39      // @todo do these alias constants need to go elsewhere?
40      /*** The objectClass name for aliases: 'alias' */
41      String ALIAS_OBJECT = "alias";
42      /*** 
43       * The aliased Dn attribute name: aliasedObjectName for LDAP and
44       * aliasedEntryName or X.500.
45       */ 
46      String ALIAS_ATTRIBUTE = "aliasedObjectName";
47  
48  
49      // ------------------------------------------------------------------------
50      // Index Operations 
51      // ------------------------------------------------------------------------
52  
53  
54      /***
55       * TODO Document me!
56       *
57       * @param attribute TODO
58       * @throws NamingException TODO
59       */    
60      void addIndexOn( AttributeType attribute ) throws NamingException;
61  
62      /***
63       * TODO Document me!
64       *
65       * @param attribute TODO
66       * @return TODO
67       */
68      boolean hasUserIndexOn( String attribute );
69  
70      /***
71       * TODO Document me!
72       *
73       * @param attribute TODO
74       * @return TODO
75       */
76      boolean hasSystemIndexOn( String attribute );
77  
78      /***
79       * Gets the Index mapping the names of attributes as Strings to the 
80       * BigInteger primary keys of entries containing one or more values of those
81       * attributes.
82       *
83       * @return the existance Index
84       */
85      Index getExistanceIndex();
86  
87      /***
88       * Gets the Index mapping the BigInteger primary keys of parents to the 
89       * BigInteger primary keys of their children.
90       *
91       * @return the hierarchy Index
92       */
93      Index getHierarchyIndex();
94      
95      /***
96       * Gets the Index mapping user provided distinguished names of entries as 
97       * Strings to the BigInteger primary keys of entries.
98       *
99       * @return the user provided distinguished name Index
100      */
101     Index getUpdnIndex();
102 
103     /***
104      * Gets the Index mapping the normalized distinguished names of entries as
105      * Strings to the BigInteger primary keys of entries.  
106      *
107      * @return the normalized distinguished name Index
108      */
109     Index getNdnIndex();
110 
111     /***
112      * Gets the alias index mapping parent entries with scope expanding aliases 
113      * children one level below them; this system index is used to dereference
114      * aliases on one/single level scoped searches.
115      * 
116      * @return the one alias index
117      */
118     Index getOneAliasIndex();
119 
120     /***
121      * Gets the alias index mapping relative entries with scope expanding 
122      * alias descendents; this system index is used to dereference aliases on 
123      * subtree scoped searches.
124      * 
125      * @return the sub alias index
126      */
127     Index getSubAliasIndex();
128 
129     /***
130      * Gets the system index defined on the ALIAS_ATTRIBUTE which for LDAP would
131      * be the aliasedObjectName and for X.500 would be aliasedEntryName.
132      * 
133      * @return the index on the ALIAS_ATTRIBUTE
134      */
135     Index getAliasIndex();
136 
137     /***
138      * Sets the system index defined on the ALIAS_ATTRIBUTE which for LDAP would
139      * be the aliasedObjectName and for X.500 would be aliasedEntryName.
140      * 
141      * @param attrType the index on the ALIAS_ATTRIBUTE
142      */
143     void setAliasIndexOn( AttributeType attrType ) throws NamingException;
144 
145     /***
146      * Sets the attribute existance Index.
147      *
148      * @param attrType the attribute existance Index
149      */    
150     void setExistanceIndexOn( AttributeType attrType ) throws NamingException;
151 
152     /***
153      * Sets the hierarchy Index.
154      *
155      * @param attrType the hierarchy Index
156      */    
157     void setHierarchyIndexOn( AttributeType attrType ) throws NamingException;
158 
159     /***
160      * Sets the user provided distinguished name Index.
161      *
162      * @param attrType the updn Index
163      */    
164     void setUpdnIndexOn( AttributeType attrType ) throws NamingException;
165 
166     /***
167      * Sets the normalized distinguished name Index.
168      *
169      * @param attrType the ndn Index
170      */    
171     void setNdnIndexOn( AttributeType attrType ) throws NamingException;
172     
173     /***
174      * Sets the alias index mapping parent entries with scope expanding aliases 
175      * children one level below them; this system index is used to dereference
176      * aliases on one/single level scoped searches.
177      * 
178      * @param attrType a one level alias index
179      */
180     void setOneAliasIndexOn( AttributeType attrType ) throws NamingException;
181     
182     /***
183      * Sets the alias index mapping relative entries with scope expanding 
184      * alias descendents; this system index is used to dereference aliases on 
185      * subtree scoped searches.
186      * 
187      * @param attrType a subtree alias index
188      */
189     void setSubAliasIndexOn( AttributeType attrType ) throws NamingException;
190     
191     /***
192      * TODO Document me!
193      *
194      * @param attribute TODO
195      * @return TODO
196      * @throws IndexNotFoundException TODO
197      */
198     Index getUserIndex( String attribute ) throws IndexNotFoundException;
199 
200     /***
201      * TODO Document me!
202      *
203      * @param attribute TODO
204      * @return TODO
205      * @throws IndexNotFoundException TODO
206      */
207     Index getSystemIndex( String attribute ) throws IndexNotFoundException;
208 
209     /***
210      * TODO Document me!
211      *
212      * @param dn TODO
213      * @return TODO
214      * @throws NamingException TODO
215      */
216     BigInteger getEntryId( String dn ) throws NamingException;
217 
218     /***
219      * TODO Document me!
220      *
221      * @param id TODO
222      * @return TODO
223      * @throws NamingException TODO
224      */
225     String getEntryDn( BigInteger id ) throws NamingException;
226 
227     /***
228      * TODO Document me!
229      * 
230      * @param dn TODO
231      * @return TODO
232      * @throws NamingException TODO
233      */
234     BigInteger getParentId( String dn ) throws NamingException;
235 
236     /***
237      * TODO Document me!
238      *
239      * @param childId TODO
240      * @return TODO
241      * @throws NamingException TODO
242      */
243     BigInteger getParentId( BigInteger childId ) throws NamingException;
244 
245     /***
246      * Gets the user provided distinguished name.
247      *
248      * @param id the entry id
249      * @return the user provided distinguished name
250      * @throws NamingException if the updn index cannot be accessed
251      */
252     String getEntryUpdn( BigInteger id ) throws NamingException;
253 
254     /***
255      * Gets the user provided distinguished name.
256      *
257      * @param dn the normalized distinguished name
258      * @return the user provided distinguished name
259      * @throws NamingException if the updn and ndn indices cannot be accessed
260      */
261     String getEntryUpdn( String dn ) throws NamingException;
262 
263     /***
264      * TODO Document me!
265      *
266      * @param updn the user provided distinguished name of the entry
267      * @param dn TODO
268      * @param entry TODO
269      * @throws NamingException TODO
270      */
271     void add( String updn, Name dn, Attributes entry ) throws NamingException;
272 
273     /***
274      * TODO Document me!
275      *
276      * @param id TODO
277      * @return TODO
278      * @throws NamingException TODO
279      */
280     Attributes lookup( BigInteger id ) throws NamingException;
281 
282     /***
283      * TODO Document me!
284      *
285      * @param id TODO
286      * @throws NamingException TODO
287      */
288     void delete( BigInteger id ) throws NamingException;
289 
290     /***
291      * TODO Document me!
292      *
293      * @param id TODO
294      * @return TODO
295      * @throws NamingException TODO
296      */
297     NamingEnumeration list( BigInteger id ) throws NamingException;
298 
299     /***
300      * TODO Document me!
301      *
302      * @param id TODO
303      * @return TODO
304      * @throws NamingException TODO
305      */
306     int getChildCount( BigInteger id ) throws NamingException;
307 
308     /***
309      * @return TODO
310      */ 
311     Name getSuffix();
312 
313     /***
314      * TODO Document me!
315      *
316      * @return TODO
317      * @throws NamingException TODO
318      */
319     Attributes getSuffixEntry() throws NamingException;
320 
321     /***
322      * TODO Document me!
323      *
324      * @throws NamingException TODO
325      */
326     void sync() throws NamingException;
327 
328     /***
329      * TODO Document me!
330      *
331      * @throws NamingException TODO
332      */
333     void close() throws NamingException;
334 
335     /***
336      * Checks to see if this BackingStore has been closed or shut down.
337      * Operations against closed BackingStores will fail.
338      *
339      * @return true if shut down, false otherwise
340      */
341     boolean isClosed();
342 
343     /***
344      * TODO Document me!
345      *
346      * @param key TODO
347      * @param value TODO
348      * @throws NamingException TODO
349      */
350     void setProperty( String key, String value ) throws NamingException;
351 
352     /***
353      * TODO Document me!
354      *
355      * @param key TODO
356      * @return TODO
357      * @throws NamingException TODO
358      */
359     String getProperty( String key ) throws NamingException;
360 
361     /***
362      * TODO Document me!
363      *
364      * @return TODO
365      */
366     Iterator getUserIndices();
367     
368     /***
369      * TODO Document me!
370      *
371      * @return TODO
372      */
373     Iterator getSystemIndices();
374 
375     /***
376      * TODO Document me!
377      *
378      * @param id TODO
379      * @return TODO
380      * @throws NamingException TODO
381      */
382     Attributes getIndices( BigInteger id ) throws NamingException;
383 
384     /***
385      * TODO Document me!
386      *
387      * @param dn TODO
388      * @param modOp TODO
389      * @param mods TODO
390      * @throws NamingException TODO
391      */
392     void modify( Name dn, int modOp, Attributes mods ) throws NamingException;
393     
394     /***
395      * TODO Document me!
396      *
397      * @param dn TODO
398      * @param mods TODO
399      * @throws NamingException TODO
400      */
401     void modify( Name dn, ModificationItem [] mods ) throws NamingException;
402 
403     /***
404      * TODO Document me!
405      *
406      * @param dn TODO
407      * @param newRdn TODO
408      * @param deleteOldRdn TODO
409      * @throws NamingException TODO
410      */
411     void modifyRdn( Name dn, String newRdn, boolean deleteOldRdn ) throws NamingException;
412 
413     /***
414      * TODO Document me!
415      *
416      * @param oldChildDn TODO
417      * @param newParentDn TODO
418      * @throws NamingException TODO
419      */
420     void move( Name oldChildDn, Name newParentDn ) throws NamingException;
421 
422     /***
423      * Moves a child from one location to another while changing the Rdn 
424      * attribute used in the new location and optionally deleting the old 
425      * Rdn attribute value pair.
426      *
427      * @param oldChildDn the normalized child dn to move
428      * @param newParentDn the normalized new parent dn to move the child to
429      * @param newRdn the new rdn of the child at its new location
430      * @param deleteOldRdn switch to remove the old rdn attribute/value pair
431      * @throws NamingException if a database failure results
432      */
433     void move( Name oldChildDn, Name newParentDn, String newRdn,
434                boolean deleteOldRdn ) throws NamingException;
435 
436     /***
437      * Gets the count of the total number of entries in the database.
438      *
439      * TODO shouldn't this be a BigInteger instead of an int? 
440      * 
441      * @return the number of entries in the database 
442      * @throws NamingException if there is a failure to read the count
443      */
444     int count() throws NamingException;
445 }