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 ditContentRule specification. ditContentRules identify the content of
028 * entries of a particular structural objectClass. They specify the AUXILIARY
029 * objectClasses and additional attribute types permitted to appear, or excluded
030 * from appearing in entries of the indicated STRUCTURAL objectClass.
031 * <p>
032 * According to ldapbis [MODELS]:
033 * </p>
034 *
035 * <pre>
036 * 4.1.6. DIT Content Rules
037 *
038 * A DIT content rule is a "rule governing the content of entries of a
039 * particular structural object class" [X.501].
040 *
041 * For DIT entries of a particular structural object class, a DIT content
042 * rule specifies which auxiliary object classes the entries are allowed
043 * to belong to and which additional attributes (by type) are required,
044 * allowed or not allowed to appear in the entries.
045 *
046 * The list of precluded attributes cannot include any attribute listed
047 * as mandatory in rule, the structural object class, or any of the
048 * allowed auxiliary object classes.
049 *
050 * Each content rule is identified by the object identifier, as well as
051 * any short names (descriptors), of the structural object class it
052 * applies to.
053 *
054 * An entry may only belong to auxiliary object classes listed in the
055 * governing content rule.
056 *
057 * An entry must contain all attributes required by the object classes
058 * the entry belongs to as well as all attributed required by the
059 * governing content rule.
060 *
061 * An entry may contain any non-precluded attributes allowed by the
062 * object classes the entry belongs to as well as all attributes allowed
063 * by the governing content rule.
064 *
065 * An entry cannot include any attribute precluded by the governing
066 * content rule.
067 *
068 * An entry is governed by (if present and active in the subschema) the
069 * DIT content rule which applies to the structural object class of the
070 * entry (see Section 2.4.2). If no active rule is present for the
071 * entry's structural object class, the entry's content is governed by
072 * the structural object class (and possibly other aspects of user and
073 * system schema).
074 *
075 * DIT content rule descriptions are written according to the ABNF:
076 *
077 * DITContentRuleDescription = LPAREN WSP
078 * numericoid ; object identifier
079 * [ SP "NAME" SP qdescrs ] ; short names (descriptors)
080 * [ SP "DESC" SP qdstring ] ; description
081 * [ SP "OBSOLETE" ] ; not active
082 * [ SP "AUX" SP oids ] ; auxiliary object classes
083 * [ SP "MUST" SP oids ] ; attribute types
084 * [ SP "MAY" SP oids ] ; attribute types
085 * [ SP "NOT" SP oids ] ; attribute types
086 * extensions WSP RPAREN ; extensions
087 *
088 * where:
089 *
090 * [numericoid] is the object identifier of the structural object class
091 * associated with this DIT content rule;
092 * NAME [qdescrs] are short names (descriptors) identifying this DIT
093 * content rule;
094 * DESC [qdstring] is a short descriptive string;
095 * OBSOLETE indicates this DIT content rule use is not active;
096 * AUX specifies a list of auxiliary object classes which entries
097 * subject to this DIT content rule may belong to;
098 * MUST, MAY, and NOT specify lists of attribute types which are
099 * required, allowed, or precluded, respectively, from appearing in
100 * entries subject to this DIT content rule; and
101 * [extensions] describe extensions.
102 * </pre>
103 *
104 * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC 2252 Section 5.4.3</a>
105 * @see <a
106 * href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
107 * [MODELS]</a>
108 * @see DescriptionUtils#getDescription(DITContentRule)
109 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
110 * @version $Rev: 437007 $
111 */
112 public interface DITContentRule extends SchemaObject
113 {
114 /**
115 * Gets the STRUCTURAL ObjectClass this DITContentRule specifies attributes
116 * for.
117 *
118 * @return the ObjectClass this DITContentRule specifies attributes for
119 * @throws NamingException
120 * if there is a failure resolving the object
121 */
122 ObjectClass getObjectClass() throws NamingException;
123
124
125 /**
126 * Gets all the AUXILIARY ObjectClasses this DITContentRule specifies for
127 * the given STRUCTURAL objectClass.
128 *
129 * @return the extra AUXILIARY ObjectClasses
130 * @throws NamingException
131 * if there is a failure resolving the object
132 */
133 ObjectClass[] getAuxObjectClasses() throws NamingException;
134
135
136 /**
137 * Gets all the AttributeTypes of the "must" attribute names this
138 * DITContentRule specifies for the given STRUCTURAL objectClass.
139 *
140 * @return the AttributeTypes of attributes that must be included in entries
141 * @throws NamingException
142 * if there is a failure resolving the object
143 */
144 AttributeType[] getMustNames() throws NamingException;
145
146
147 /**
148 * Gets all the AttributeTypes of the "may" attribute names this
149 * DITContentRule specifies for the given STRUCTURAL objectClass.
150 *
151 * @return the AttributeTypes of attributes that may be included in entries
152 * @throws NamingException
153 * if there is a failure resolving the object
154 */
155 AttributeType[] getMayNames() throws NamingException;
156
157
158 /**
159 * Gets all the AttributeTypes of the "not" attribute names this
160 * DITContentRule specifies for the given STRUCTURAL objectClass.
161 *
162 * @return the AttributeTypes of attributes that are excluded in entries
163 * @throws NamingException
164 * if there is a failure resolving the object
165 */
166 AttributeType[] getNotNames() throws NamingException;
167 }