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 nameForm description. NameForms define the relationship between a
028 * STRUCTURAL objectClass definition and the attributeTypes allowed to be used
029 * for the naming of an Entry of that objectClass: it defines which attributes
030 * can be used for the RDN.
031 * <p>
032 * According to ldapbis [MODELS]:
033 * </p>
034 *
035 * <pre>
036 * 4.1.7.2. Name Forms
037 *
038 * A name form "specifies a permissible RDN for entries of a particular
039 * structural object class. A name form identifies a named object
040 * class and one or more attribute types to be used for naming (i.e.
041 * for the RDN). Name forms are primitive pieces of specification
042 * used in the definition of DIT structure rules" [X.501].
043 *
044 * Each name form indicates the structural object class to be named,
045 * a set of required attribute types, and a set of allowed attributes
046 * types. A particular attribute type cannot be listed in both sets.
047 *
048 * Entries governed by the form must be named using a value from each
049 * required attribute type and zero or more values from the allowed
050 * attribute types.
051 *
052 * Each name form is identified by an object identifier (OID) and,
053 * optionally, one or more short names (descriptors).
054 *
055 * Name form descriptions are written according to the ABNF:
056 *
057 * NameFormDescription = LPAREN WSP
058 * numericoid ; object identifier
059 * [ SP "NAME" SP qdescrs ] ; short names (descriptors)
060 * [ SP "DESC" SP qdstring ] ; description
061 * [ SP "OBSOLETE" ] ; not active
062 * SP "OC" SP oid ; structural object class
063 * SP "MUST" SP oids ; attribute types
064 * [ SP "MAY" SP oids ] ; attribute types
065 * extensions WSP RPAREN ; extensions
066 *
067 * where:
068 *
069 * [numericoid] is object identifier which identifies this name form;
070 * NAME [qdescrs] are short names (descriptors) identifying this name
071 * form;
072 * DESC [qdstring] is a short descriptive string;
073 * OBSOLETE indicates this name form is not active;
074 * OC identifies the structural object class this rule applies to,
075 * MUST and MAY specify the sets of required and allowed, respectively,
076 * naming attributes for this name form; and
077 * [extensions] describe extensions.
078 *
079 * All attribute types in the required ("MUST") and allowed ("MAY") lists
080 * shall be different.
081 * </pre>
082 *
083 * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC2252 Section 6.22</a>
084 * @see <a
085 * href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
086 * [MODELS]</a>
087 * @see DescriptionUtils#getDescription(NameForm)
088 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
089 * @version $Rev: 503982 $
090 */
091 public interface NameForm extends SchemaObject
092 {
093 /**
094 * Gets the STRUCTURAL ObjectClass this name form specifies naming
095 * attributes for.
096 *
097 * @return the ObjectClass this NameForm is for
098 * @throws NamingException
099 * if there is a failure resolving the object
100 */
101 ObjectClass getObjectClass() throws NamingException;
102
103
104 /**
105 * Gets all the AttributeTypes of the attributes this NameForm specifies as
106 * having to be used in the given objectClass for naming: as part of the
107 * Rdn.
108 *
109 * @return the AttributeTypes of the must use attributes
110 * @throws NamingException
111 * if there is a failure resolving the object
112 */
113 AttributeType[] getMustUse() throws NamingException;
114
115
116 /**
117 * Gets all the AttributeTypes of the attribute this NameForm specifies as
118 * being useable without requirement in the given objectClass for naming: as
119 * part of the Rdn.
120 *
121 * @return the AttributeTypes of the may use attributes
122 * @throws NamingException
123 * if there is a failure resolving the object
124 */
125 AttributeType[] getMayUse() throws NamingException;
126 }