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 javax.naming.Name;
21 import javax.naming.NamingException;
22 import javax.naming.ldap.LdapContext;
23 import java.util.Iterator;
24
25
26 /***
27 * The PartitionNexus is a special type of BackingStore designed to route
28 * BackingStore operations to ContextPartitions based on namespace to respective
29 * ContextPartitions attached to the nexus at the appropriate naming contexts.
30 * These naming contexts are also the suffixes of ContextPartitions. All
31 * entries within a ContextPartition have the same suffix. The PartitionNexus
32 * is a singleton where as ContextPartitions can be many hanging off of
33 * different contexts on the nexus.
34 *
35 * The PartitionNexus routes or proxies BackingStore calls to the appropriate
36 * PartitionContext implementation. It also provides some extended operations
37 * for the entire backend apparatus like listing the various naming contexts or
38 * partition suffixes within the system. The nexus is also responsibe for
39 * returning the entry Attributes for the root DSE when the approapriate search
40 * is conducted: empty filter String and base scope search.
41 *
42 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
43 * @version $Rev: 159259 $
44 */
45 public interface PartitionNexus extends BackingStore
46 {
47 /***
48 * Gets the LdapContext associated with the calling thread.
49 *
50 * @return The LdapContext associated with the thread of execution or null
51 * if no context is associated with the calling thread.
52 */
53 LdapContext getLdapContext();
54
55 /***
56 * Gets the most significant Dn that exists within the server for any Dn.
57 *
58 * @param dn the normalized distinguished name to use for matching.
59 * @param normalized boolean if true cause the return of a normalized Dn,
60 * if false it returns the original user provided distinguished name for
61 * the matched portion of the Dn as it was provided on entry creation.
62 * @return a distinguished name representing the matching portion of dn,
63 * as originally provided by the user on creation of the matched entry or
64 * the empty string distinguished name if no match was found.
65 * @throws NamingException if there are any problems
66 */
67 Name getMatchedDn( Name dn, boolean normalized ) throws NamingException;
68
69 /***
70 * Gets the distinguished name of the suffix that would hold an entry with
71 * the supplied distinguished name parameter. If the DN argument does not
72 * fall under a partition suffix then the empty string Dn is returned.
73 *
74 * @param dn the normalized distinguished name to use for finding a suffix.
75 * @param normalized if true causes the return of a normalized Dn, but
76 * if false it returns the original user provided distinguished name for
77 * the suffix Dn as it was provided on suffix entry creation.
78 * @return the suffix portion of dn, or the valid empty string Dn if no
79 * naming context was found for dn.
80 * @throws NamingException if there are any problems
81 */
82 Name getSuffix( Name dn, boolean normalized ) throws NamingException;
83
84 /***
85 * Gets an iteration over the Name suffixes of the Backends managed by this
86 * BackendNexus.
87 *
88 * @param normalized if true the returned Iterator contains normalized Dn
89 * but, if false, it returns the original user provided distinguished names
90 * in the Iterator.
91 * @return Iteration over ContextPartition suffix names as Names.
92 * @throws NamingException if there are any problems
93 */
94 Iterator listSuffixes( boolean normalized ) throws NamingException;
95
96 /***
97 * Registers an ContextPartition with this BackendManager. Called by each
98 * ContextPartition implementation after it has started to register for
99 * backend operation calls. This method effectively puts the
100 * ContextPartition's naming context online.
101 *
102 * Operations against the naming context should result in an LDAP BUSY
103 * result code in the returnValue if the naming context is not online.
104 *
105 * @param partition ContextPartition component to register with this
106 * BackendNexus.
107 */
108 void register( ContextPartition partition );
109
110 /***
111 * Unregisters an ContextPartition with this BackendManager. Called for each
112 * registered Backend right befor it is to be stopped. This prevents
113 * protocol server requests from reaching the Backend and effectively puts
114 * the ContextPartition's naming context offline.
115 *
116 * Operations against the naming context should result in an LDAP BUSY
117 * result code in the returnValue if the naming context is not online.
118 *
119 * @param partition ContextPartition component to unregister with this
120 * BackendNexus.
121 */
122 void unregister( ContextPartition partition );
123 }