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 * An attributeType specification. attributeType specifications describe the
028 * nature of attributes within the directory. The attributeType specification's
029 * properties are accessible through this interface.
030 * <p>
031 * According to ldapbis [MODELS]:
032 * </p>
033 *
034 * <pre>
035 * 4.1.2. Attribute Types
036 *
037 * Attribute Type definitions are written according to the ABNF:
038 *
039 * AttributeTypeDescription = LPAREN WSP
040 * numericoid ; object identifier
041 * [ SP "NAME" SP qdescrs ] ; short names (descriptors)
042 * [ SP "DESC" SP qdstring ] ; description
043 * [ SP "OBSOLETE" ] ; not active
044 * [ SP "SUP" SP oid ] ; supertype
045 * [ SP "EQUALITY" SP oid ] ; equality matching rule
046 * [ SP "ORDERING" SP oid ] ; ordering matching rule
047 * [ SP "SUBSTR" SP oid ] ; substrings matching rule
048 * [ SP "SYNTAX" SP noidlen ] ; value syntax
049 * [ SP "SINGLE-VALUE" ] ; single-value
050 * [ SP "COLLECTIVE" ] ; collective
051 * [ SP "NO-USER-MODIFICATION" ]; not user modifiable
052 * [ SP "USAGE" SP usage ] ; usage
053 * extensions WSP RPAREN ; extensions
054 *
055 * usage = "userApplications" / ; user
056 * "directoryOperation" / ; directory operational
057 * "distributedOperation" / ; DSA-shared operational
058 * "dSAOperation" ; DSA-specific operational
059 *
060 * where:
061 * [numericoid] is object identifier assigned to this attribute type;
062 * NAME [qdescrs] are short names (descriptors) identifying this
063 * attribute type;
064 * DESC [qdstring] is a short descriptive string;
065 * OBSOLETE indicates this attribute type is not active;
066 * SUP oid specifies the direct supertype of this type;
067 * EQUALITY, ORDERING, SUBSTRING provide the oid of the equality,
068 * ordering, and substrings matching rules, respectively;
069 * SYNTAX identifies value syntax by object identifier and may suggest
070 * a minimum upper bound;
071 * COLLECTIVE indicates this attribute type is collective [X.501];
072 * NO-USER-MODIFICATION indicates this attribute type is not user
073 * modifiable;
074 * USAGE indicates the application of this attribute type; and
075 * [extensions] describe extensions.
076 *
077 * Each attribute type description must contain at least one of the SUP
078 * or SYNTAX fields.
079 *
080 * Usage of userApplications, the default, indicates that attributes of
081 * this type represent user information. That is, they are user
082 * attributes.
083 *
084 * COLLECTIVE requires usage userApplications. Use of collective
085 * attribute types in LDAP is not discussed in this technical
086 * specification.
087 *
088 * A usage of directoryOperation, distributedOperation, or dSAOperation
089 * indicates that attributes of this type represent operational and/or
090 * administrative information. That is, they are operational attributes.
091 *
092 * directoryOperation usage indicates that the attribute of this type is
093 * a directory operational attribute. distributedOperation usage
094 * indicates that the attribute of this DSA-shared usage operational
095 * attribute. dSAOperation usage indicates that the attribute of this
096 * type is a DSA-specific operational attribute.
097 *
098 * NO-USER-MODIFICATION requires an operational usage.
099 *
100 * Note that the [AttributeTypeDescription] does not list the matching
101 * rules which can be used with that attribute type in an extensibleMatch
102 * search filter. This is done using the 'matchingRuleUse' attribute
103 * described in Section 4.1.4.
104 *
105 * This document refines the schema description of X.501 by requiring
106 * that the SYNTAX field in an [AttributeTypeDescription] be a string
107 * representation of an object identifier for the LDAP string syntax
108 * definition with an optional indication of the suggested minimum bound
109 * of a value of this attribute.
110 *
111 * A suggested minimum upper bound on the number of characters in a value
112 * with a string-based syntax, or the number of bytes in a value for all
113 * other syntaxes, may be indicated by appending this bound count inside
114 * of curly braces following the syntax's OBJECT IDENTIFIER in an
115 *
116 * Attribute Type Description. This bound is not part of the syntax name
117 * itself. For instance, "1.3.6.4.1.1466.0{64}" suggests that server
118 * implementations should allow a string to be 64 characters long,
119 * although they may allow longer strings. Note that a single character
120 * of the Directory String syntax may be encoded in more than one octet
121 * since UTF-8 is a variable-length encoding.
122 * </pre>
123 *
124 * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC 2252 Section 4.2</a>
125 * @see <a
126 * href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">
127 * ldapbis [MODELS]</a>
128 * @see DescriptionUtils#getDescription(AttributeType)
129 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
130 * @version $Rev: 702493 $
131 */
132 public interface AttributeType extends SchemaObject
133 {
134 /**
135 * Gets whether or not this AttributeType is single-valued.
136 *
137 * @return true if only one value can exist for this AttributeType, false
138 * otherwise
139 */
140 boolean isSingleValue();
141
142
143 /**
144 * Gets whether or not this AttributeType can be modified by a user.
145 *
146 * @return true if users can modify it, false if only the directory can.
147 */
148 boolean isCanUserModify();
149
150
151 /**
152 * Gets whether or not this AttributeType is a collective attribute.
153 *
154 * @return true if the attribute is collective, false otherwise
155 */
156 boolean isCollective();
157
158
159 /**
160 * Determines the usage for this AttributeType.
161 *
162 * @return a type safe UsageEnum
163 */
164 UsageEnum getUsage();
165
166
167 /**
168 * Gets the name of the superior class for this AttributeType.
169 *
170 * @return the super class for this AttributeType
171 * @throws NamingException
172 * if there is a failure to resolve the superior
173 */
174 AttributeType getSuperior() throws NamingException, NamingException;
175
176
177 /**
178 * The Syntax for this AttributeType's values.
179 *
180 * @return the value syntax
181 * @throws NamingException
182 * if there is a failure to resolve the syntax
183 */
184 Syntax getSyntax() throws NamingException;
185
186
187 /**
188 * Gets a length limit for this AttributeType.
189 *
190 * @return the length of the attribute
191 */
192 int getLength();
193
194
195 /**
196 * Gets the MatchingRule for this AttributeType used for equality matching.
197 *
198 * @return the equality matching rule
199 * @throws NamingException
200 * if there is a failure to resolve the matchingRule
201 */
202 MatchingRule getEquality() throws NamingException;
203
204
205 /**
206 * Gets the MatchingRule for this AttributeType used for ordering.
207 *
208 * @return the ordering matching rule
209 * @throws NamingException
210 * if there is a failure to resolve the matchingRule
211 */
212 MatchingRule getOrdering() throws NamingException;
213
214
215 /**
216 * Gets the MatchingRule for this AttributeType used for substring matching.
217 *
218 * @return the substring matching rule
219 * @throws NamingException
220 * if there is a failure to resolve the matchingRule
221 */
222 MatchingRule getSubstr() throws NamingException;
223
224
225 /**
226 * Checks to see if this AttributeType is the ancestor of another
227 * attributeType.
228 *
229 * @param descendant the perspective descendant to check
230 * @return true if the descendant is truely a derived from this AttributeType
231 * @throws NamingException if there are problems resolving superior types
232 */
233 boolean isAncestorOf( AttributeType descendant ) throws NamingException;
234
235
236 /**
237 * Checks to see if this AttributeType is the descendant of another
238 * attributeType.
239 *
240 * @param ancestor the perspective ancestor to check
241 * @return true if this AttributeType truely descends from the ancestor
242 * @throws NamingException if there are problems resolving superior types
243 */
244 boolean isDescendantOf( AttributeType ancestor ) throws NamingException;
245 }