001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.shared.ldap.subtree;
021    
022    
023    import org.apache.directory.shared.ldap.filter.ExprNode;
024    import org.apache.directory.shared.ldap.name.DN;
025    
026    import java.util.Set;
027    
028    
029    /**
030     * <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a> defined a
031     * subtree specification to be included within subentries.
032     * 
033     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034     * @version $Rev: 918756 $
035     */
036    public interface SubtreeSpecification
037    {
038        /** an unbounded maximum depth value in a subtree specification */
039        int UNBOUNDED_MAX = -1;
040    
041    
042        /**
043         * Gets an RDN relative to the administrative context where the subtree
044         * scope begins. All subentries containing these specifications are
045         * immediate subordinates to the administrative point, and are considered to
046         * be part of the same naming context. Hence the base for the subtree
047         * specification of a subentry immediately subordinate to dc=apache,dc=org
048         * would be relative to the dc=apache,dc=org context.
049         * 
050         * @return the RDN representing the base of the subtree, or the empty name
051         *         if the base is the administrative point - note that this Name is
052         *         not Normalized according to matchingRules.
053         */
054        DN getBase();
055    
056    
057        /**
058         * A set of RDNs relative to the base entry representing chopBefore
059         * specificExclusions from the subtree. According to RFC 3672: "If the
060         * chopBefore form is used then the specified entry and its subordinates are
061         * excluded from the subtree or subtree refinement."
062         * 
063         * @return a set of relative {@link javax.naming.Name}s to the subtree base
064         *         or the empty set
065         */
066        Set<DN> getChopBeforeExclusions();
067    
068    
069        /**
070         * A set of RDNs relative to the base entry representing chopAfter
071         * specificExclusions from the subtree. According to RFC 3672: "If the
072         * chopAfter form is used then only the subordinates of the specified entry
073         * are excluded from the subtree or subtree refinement."
074         * 
075         * @return a set of relative {@link javax.naming.Name}s to the subtree base
076         *         or the empty set
077         */
078        Set<DN> getChopAfterExclusions();
079    
080    
081        /**
082         * Gets the distance at which to start including entries in the subtree. All
083         * entries whose RDN arcs relative to the base are less than the minimum are
084         * excluded from the subtree or subtree refinement. The default is zero and
085         * therefore excludes nothing.
086         * 
087         * @return the minimum number of RDN arcs relative to base for inclusion
088         */
089        int getMinBaseDistance();
090    
091    
092        /**
093         * Gets the distance after which to start excluding entries in the subtree
094         * or subtree refinement. RFC 3672 Section 2.1.3 states: "Entries that are
095         * more than the maximum number of RDN arcs below the base entry are
096         * excluded from the subtree or subtree refinement. An absent maximum
097         * component indicates that there is no upper limit on the number of RDN
098         * arcs below the base entry for entries in the subtree or subtree
099         * refinement." If the maximum is limitless a negative value should be used
100         * to represent the maximum distance - which makes no sense other than to
101         * denote the lack of an upper limit.
102         * 
103         * @see #UNBOUNDED_MAX
104         * @return the number of arcs relative to the base after which entries are
105         *         excluded
106         */
107        int getMaxBaseDistance();
108    
109    
110        /**
111         * A subtree refinement represents a non-contiguous selection of entries
112         * using a limited filter expression where attribute assertions are based on
113         * the objectClass of the entries.
114         * 
115         * @return a limited filter expression tree representing a subtree
116         *         refinement or null if one does not exist for this subtree
117         *         specification
118         */
119        ExprNode getRefinement();
120        
121        
122        /**
123         * Converts this item into its string representation as stored
124         * in directory.
125         *
126         * @param buffer the string buffer
127         */
128        void printToBuffer( StringBuilder buffer );
129        
130    }