PartitionNexus


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