View Javadoc
1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *  
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *  
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License. 
18   *  
19   */
20  package org.apache.directory.api.ldap.model.subtree;
21  
22  
23  import java.util.Set;
24  
25  import org.apache.directory.api.ldap.model.filter.ExprNode;
26  import org.apache.directory.api.ldap.model.name.Dn;
27  
28  
29  /**
30   * <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a> defined a
31   * subtree specification to be included within subentries.
32   * 
33   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
34   */
35  public interface SubtreeSpecification
36  {
37      /** an unbounded maximum depth value in a subtree specification */
38      int UNBOUNDED_MAX = -1;
39  
40  
41      /**
42       * Gets an Rdn relative to the administrative context where the subtree
43       * scope begins. All subentries containing these specifications are
44       * immediate subordinates to the administrative point, and are considered to
45       * be part of the same naming context. Hence the base for the subtree
46       * specification of a subentry immediately subordinate to dc=apache,dc=org
47       * would be relative to the dc=apache,dc=org context.
48       * 
49       * @return the Rdn representing the base of the subtree, or the empty name
50       *         if the base is the administrative point - note that this Name is
51       *         not Normalized according to matchingRules.
52       */
53      Dn getBase();
54  
55  
56      /**
57       * A set of RDNs relative to the base entry representing chopBefore
58       * specificExclusions from the subtree. According to RFC 3672: "If the
59       * chopBefore form is used then the specified entry and its subordinates are
60       * excluded from the subtree or subtree refinement."
61       * 
62       * @return a set of relative {@link javax.naming.Name}s to the subtree base
63       *         or the empty set
64       */
65      Set<Dn> getChopBeforeExclusions();
66  
67  
68      /**
69       * A set of RDNs relative to the base entry representing chopAfter
70       * specificExclusions from the subtree. According to RFC 3672: "If the
71       * chopAfter form is used then only the subordinates of the specified entry
72       * are excluded from the subtree or subtree refinement."
73       * 
74       * @return a set of relative {@link javax.naming.Name}s to the subtree base
75       *         or the empty set
76       */
77      Set<Dn> getChopAfterExclusions();
78  
79  
80      /**
81       * Gets the distance at which to start including entries in the subtree. All
82       * entries whose Rdn arcs relative to the base are less than the minimum are
83       * excluded from the subtree or subtree refinement. The default is zero and
84       * therefore excludes nothing.
85       * 
86       * @return the minimum number of Rdn arcs relative to base for inclusion
87       */
88      int getMinBaseDistance();
89  
90  
91      /**
92       * Gets the distance after which to start excluding entries in the subtree
93       * or subtree refinement. RFC 3672 Section 2.1.3 states: "Entries that are
94       * more than the maximum number of Rdn arcs below the base entry are
95       * excluded from the subtree or subtree refinement. An absent maximum
96       * component indicates that there is no upper limit on the number of Rdn
97       * arcs below the base entry for entries in the subtree or subtree
98       * refinement." If the maximum is limitless a negative value should be used
99       * to represent the maximum distance - which makes no sense other than to
100      * denote the lack of an upper limit.
101      * 
102      * @see #UNBOUNDED_MAX
103      * @return the number of arcs relative to the base after which entries are
104      *         excluded
105      */
106     int getMaxBaseDistance();
107 
108 
109     /**
110      * A subtree refinement represents a non-contiguous selection of entries
111      * using a limited filter expression where attribute assertions are based on
112      * the objectClass of the entries.
113      * 
114      * @return a refinement tree or null if one does not exist for this subtree
115      *         specification
116      */
117     ExprNode getRefinement();
118 
119 
120     /**
121      * Converts this item into its string representation as stored
122      * in directory.
123      *
124      * @param buffer the string buffer
125      */
126     void toString( StringBuilder buffer );
127 }