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 */
020package org.apache.directory.api.ldap.model.subtree;
021
022
023import java.util.Set;
024
025import org.apache.directory.api.ldap.model.filter.ExprNode;
026import org.apache.directory.api.ldap.model.name.Dn;
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 */
035public interface SubtreeSpecification
036{
037    /** an unbounded maximum depth value in a subtree specification */
038    int UNBOUNDED_MAX = -1;
039
040
041    /**
042     * Gets an Rdn relative to the administrative context where the subtree
043     * scope begins. All subentries containing these specifications are
044     * immediate subordinates to the administrative point, and are considered to
045     * be part of the same naming context. Hence the base for the subtree
046     * specification of a subentry immediately subordinate to dc=apache,dc=org
047     * would be relative to the dc=apache,dc=org context.
048     * 
049     * @return the Rdn representing the base of the subtree, or the empty name
050     *         if the base is the administrative point - note that this Name is
051     *         not Normalized according to matchingRules.
052     */
053    Dn getBase();
054
055
056    /**
057     * A set of RDNs relative to the base entry representing chopBefore
058     * specificExclusions from the subtree. According to RFC 3672: "If the
059     * chopBefore form is used then the specified entry and its subordinates are
060     * excluded from the subtree or subtree refinement."
061     * 
062     * @return a set of relative {@link javax.naming.Name}s to the subtree base
063     *         or the empty set
064     */
065    Set<Dn> getChopBeforeExclusions();
066
067
068    /**
069     * A set of RDNs relative to the base entry representing chopAfter
070     * specificExclusions from the subtree. According to RFC 3672: "If the
071     * chopAfter form is used then only the subordinates of the specified entry
072     * are excluded from the subtree or subtree refinement."
073     * 
074     * @return a set of relative {@link javax.naming.Name}s to the subtree base
075     *         or the empty set
076     */
077    Set<Dn> getChopAfterExclusions();
078
079
080    /**
081     * Gets the distance at which to start including entries in the subtree. All
082     * entries whose Rdn arcs relative to the base are less than the minimum are
083     * excluded from the subtree or subtree refinement. The default is zero and
084     * therefore excludes nothing.
085     * 
086     * @return the minimum number of Rdn arcs relative to base for inclusion
087     */
088    int getMinBaseDistance();
089
090
091    /**
092     * Gets the distance after which to start excluding entries in the subtree
093     * or subtree refinement. RFC 3672 Section 2.1.3 states: "Entries that are
094     * more than the maximum number of Rdn arcs below the base entry are
095     * excluded from the subtree or subtree refinement. An absent maximum
096     * component indicates that there is no upper limit on the number of Rdn
097     * arcs below the base entry for entries in the subtree or subtree
098     * refinement." If the maximum is limitless a negative value should be used
099     * 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}