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}