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.schema;
021    
022    
023    import javax.naming.NamingException;
024    
025    
026    /**
027     * A dITStructureRule definition. A dITStructureRules is a rule governing the
028     * structure of the DIT by specifying a permitted superior to subordinate entry
029     * relationship. A structure rule relates a nameForm, and therefore a STRUCTURAL
030     * objectClass, to superior dITStructureRules. This permits entries of the
031     * STRUCTURAL objectClass identified by the nameForm to exist in the DIT as
032     * subordinates to entries governed by the indicated superior dITStructureRules.
033     * Hence dITStructureRules only apply to structural object classes.
034     * <p>
035     * According to ldapbis [MODELS]:
036     * </p>
037     * 
038     * <pre>
039     *  DIT structure rule descriptions are written according to the ABNF:
040     *  
041     *    DITStructureRuleDescription = LPAREN WSP
042     *        ruleid                    ; rule identifier
043     *        [ SP &quot;NAME&quot; SP qdescrs ]  ; short names (descriptors)
044     *        [ SP &quot;DESC&quot; SP qdstring ] ; description
045     *        [ SP &quot;OBSOLETE&quot; ]         ; not active
046     *        SP &quot;FORM&quot; SP oid          ; NameForm
047     *        [ SP &quot;SUP&quot; ruleids ]      ; superior rules
048     *        extensions WSP RPAREN     ; extensions
049     * 
050     *    ruleids = ruleid / ( LPAREN WSP ruleidlist WSP RPAREN )
051     * 
052     *    ruleidlist = ruleid *( SP ruleid )
053     * 
054     *    ruleid = number
055     * 
056     *  where:
057     *    [ruleid] is the rule identifier of this DIT structure rule;
058     *    NAME [qdescrs] are short names (descriptors) identifying this DIT
059     *        structure rule;
060     *    DESC [qdstring] is a short descriptive string;
061     *    OBSOLETE indicates this DIT structure rule use is not active;
062     *    FORM is specifies the name form associated with this DIT structure
063     *        rule;
064     *    SUP identifies superior rules (by rule id); and
065     *    [extensions] describe extensions.
066     *  
067     *  If no superior rules are identified, the DIT structure rule applies
068     *  to an autonomous administrative point (e.g. the root vertex of the
069     *  subtree controlled by the subschema) [X.501].
070     * </pre>
071     * 
072     * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC2252 Section 6.33</a>
073     * @see <a
074     *      href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
075     *      [MODELS]</a>
076     * @see DescriptionUtils#getDescription(DITStructureRule)
077     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
078     * @version $Rev: 504281 $
079     */
080    public interface DITStructureRule extends SchemaObject
081    {
082        /**
083         * Gets the rule identifier for this DITStructureRule.
084         * 
085         * @return the rule identifier 
086         */
087        Integer getRuleId();
088        
089        
090        /**
091         * The nameForm associating this ditStructureRule with a structural
092         * objectClass.
093         * 
094         * @return the nameForm for the structural objectClass
095         * @throws NamingException
096         *             if there is a failure resolving the object
097         */
098        NameForm getNameForm() throws NamingException;
099    
100    
101        /**
102         * Gets a collection of all the superior StructureRules. The difference with
103         * getSuperClass is this method will resolve the entire superior class
104         * chain.
105         * 
106         * @return the chain of StructureRules
107         * @throws NamingException
108         *             if there is a failure resolving the object
109         */
110        DITStructureRule[] getSuperClasses() throws NamingException;
111    }