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 java.util.List;
024
025 import javax.naming.NamingException;
026
027 import org.apache.directory.shared.ldap.schema.registries.Registries;
028 import org.apache.directory.shared.ldap.schema.syntaxCheckers.OctetStringSyntaxChecker;
029
030
031 /**
032 * A syntax definition. Each attribute stored in a directory has a defined
033 * syntax (i.e. data type) which constrains the structure and format of its
034 * values. The description of each syntax specifies how attribute or assertion
035 * values conforming to the syntax are normally represented when transferred in
036 * LDAP operations. This representation is referred to as the LDAP-specific
037 * encoding to distinguish it from other methods of encoding attribute values.
038 * <p>
039 * According to ldapbis [MODELS]:
040 * </p>
041 *
042 * <pre>
043 * 4.1.5. LDAP Syntaxes
044 *
045 * LDAP Syntaxes of (attribute and assertion) values are described in
046 * terms of ASN.1 [X.680] and, optionally, have an octet string encoding
047 * known as the LDAP-specific encoding. Commonly, the LDAP-specific
048 * encoding is constrained to string of Universal Character Set (UCS)
049 * [ISO10646] characters in UTF-8 [UTF-8] form.
050 *
051 * Each LDAP syntax is identified by an object identifier (OID).
052 *
053 * LDAP syntax definitions are written according to the ABNF:
054 *
055 * SyntaxDescription = LPAREN WSP
056 * numericoid ; object identifier
057 * [ SP "DESC" SP qdstring ] ; description
058 * extensions WSP RPAREN ; extensions
059 *
060 * where:
061 * [numericoid] is object identifier assigned to this LDAP syntax;
062 * DESC [qdstring] is a short descriptive string; and
063 * [extensions] describe extensions.
064 * </pre>
065 *
066 * @see <a href="http://www.faqs.org/rfcs/rfc2252.html"> RFC2252 Section 4.3.3</a>
067 * @see <a href=
068 * "http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-09.txt">
069 * ldapbis [MODELS]</a>
070 * @see DescriptionUtils#getDescription(Syntax)
071 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
072 * @version $Rev: 437007 $
073 */
074 public class LdapSyntax extends AbstractSchemaObject
075 {
076 /** The serialVersionUID */
077 public static final long serialVersionUID = 1L;
078
079 /** the human readable flag */
080 protected boolean isHumanReadable = false;
081
082 /** The associated SyntaxChecker */
083 protected SyntaxChecker syntaxChecker;
084
085
086 /**
087 * Creates a Syntax object using a unique OID.
088 *
089 * @param oid the OID for this Syntax
090 */
091 public LdapSyntax( String oid )
092 {
093 super( SchemaObjectType.LDAP_SYNTAX, oid );
094 }
095
096
097 /**
098 * Creates a Syntax object using a unique OID.
099 *
100 * @param oid the OID for this Syntax
101 */
102 public LdapSyntax( String oid, String description )
103 {
104 super( SchemaObjectType.LDAP_SYNTAX, oid );
105 this.description = description;
106 }
107
108
109 /**
110 * Creates a Syntax object using a unique OID.
111 *
112 * @param oid the OID for this Syntax
113 */
114 public LdapSyntax( String oid, String description, boolean isHumanReadable )
115 {
116 super( SchemaObjectType.LDAP_SYNTAX, oid );
117 this.description = description;
118 this.isHumanReadable = isHumanReadable;
119 }
120
121
122 /**
123 * Gets whether or not the Syntax is human readable.
124 *
125 * @return true if the syntax can be interpreted by humans, false otherwise
126 */
127 public boolean isHumanReadable()
128 {
129 return isHumanReadable;
130 }
131
132
133 /**
134 * Sets the human readable flag value.
135 *
136 * @param isHumanReadable the human readable flag value to set
137 */
138 public void setHumanReadable( boolean isHumanReadable )
139 {
140 if ( !isReadOnly )
141 {
142 this.isHumanReadable = isHumanReadable;
143 }
144 }
145
146
147 /**
148 * Gets the SyntaxChecker used to validate values in accordance with this
149 * Syntax.
150 *
151 * @return the SyntaxChecker
152 */
153 public SyntaxChecker getSyntaxChecker()
154 {
155 return syntaxChecker;
156 }
157
158
159 /**
160 * Sets the associated SyntaxChecker
161 *
162 * @param syntaxChecker The associated SyntaxChecker
163 */
164 public void setSyntaxChecker( SyntaxChecker syntaxChecker )
165 {
166 if ( !isReadOnly )
167 {
168 this.syntaxChecker = syntaxChecker;
169 }
170 }
171
172
173 /**
174 * Update the associated SyntaxChecker, even if the SchemaObject is readOnly
175 *
176 * @param syntaxChecker The associated SyntaxChecker
177 */
178 public void updateSyntaxChecker( SyntaxChecker syntaxChecker )
179 {
180 this.syntaxChecker = syntaxChecker;
181 }
182
183
184 /**
185 * @see Object#toString()
186 */
187 public String toString()
188 {
189 return objectType + " " + DescriptionUtils.getDescription( this );
190 }
191
192
193 /**
194 * Inject the Syntax into the registries, updating the references to
195 * other SchemaObject
196 *
197 * @param registries The Registries
198 * @exception If the addition failed
199 */
200 public void addToRegistries( List<Throwable> errors, Registries registries ) throws NamingException
201 {
202 if ( registries != null )
203 {
204 try
205 {
206 // Gets the associated SyntaxChecker
207 syntaxChecker = registries.getSyntaxCheckerRegistry().lookup( oid );
208 }
209 catch ( NamingException ne )
210 {
211 // No SyntaxChecker ? Associate the Syntax to a catch all SyntaxChecker
212 syntaxChecker = new OctetStringSyntaxChecker( oid );
213 }
214
215 // Add the references for S :
216 // S -> SC
217 if ( syntaxChecker != null )
218 {
219 registries.addReference( this, syntaxChecker );
220 }
221 }
222 }
223
224
225 /**
226 * Remove the SDyntax from the registries, updating the references to
227 * other SchemaObject.
228 *
229 * If one of the referenced SchemaObject does not exist (),
230 * an exception is thrown.
231 *
232 * @param registries The Registries
233 * @exception If the Syntx is not valid
234 */
235 public void removeFromRegistries( List<Throwable> errors, Registries registries ) throws NamingException
236 {
237 if ( registries != null )
238 {
239 /**
240 * Remove the Syntax references (using and usedBy) :
241 * S -> SC
242 */
243 if ( syntaxChecker != null )
244 {
245 registries.delReference( this, syntaxChecker );
246 }
247 }
248 }
249
250
251 /**
252 * Copy a LdapSyntax
253 */
254 public LdapSyntax copy()
255 {
256 LdapSyntax copy = new LdapSyntax( oid );
257
258 // Copy the SchemaObject common data
259 copy.copy( this );
260
261 // Copy the HR flag
262 copy.isHumanReadable = isHumanReadable;
263
264 // All the references to other Registries object are set to null.
265 copy.syntaxChecker = null;
266
267 return copy;
268 }
269
270
271 /**
272 * @see Object#equals()
273 */
274 public boolean equals( Object o )
275 {
276 if ( !super.equals( o ) )
277 {
278 return false;
279 }
280
281 if ( !( o instanceof LdapSyntax ) )
282 {
283 return false;
284 }
285
286 LdapSyntax that = ( LdapSyntax ) o;
287
288 // IsHR
289 if ( isHumanReadable != that.isHumanReadable )
290 {
291 return false;
292 }
293
294 // Check the SyntaxChecker (not a equals)
295 return syntaxChecker.getOid().equals( that.syntaxChecker.getOid() );
296 }
297
298
299 /**
300 * {@inheritDoc}
301 */
302 public void clear()
303 {
304 // Clear the common elements
305 super.clear();
306
307 // Clear the references
308 syntaxChecker = null;
309 }
310 }