001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.api;
028 import org.opends.messages.Message;
029
030
031
032 import java.util.List;
033
034 import org.opends.server.admin.std.server.AttributeSyntaxCfg;
035 import org.opends.server.config.ConfigException;
036 import org.opends.server.types.ByteString;
037 import org.opends.server.types.InitializationException;
038
039 import org.opends.messages.MessageBuilder;
040
041
042 /**
043 * This class defines the set of methods and structures that must be
044 * implemented by a Directory Server module that implements an
045 * attribute syntax.
046 *
047 * @param <T> The type of configuration handled by this attribute
048 * syntax.
049 */
050 @org.opends.server.types.PublicAPI(
051 stability=org.opends.server.types.StabilityLevel.VOLATILE,
052 mayInstantiate=false,
053 mayExtend=true,
054 mayInvoke=false)
055 public abstract class AttributeSyntax<T extends AttributeSyntaxCfg>
056 {
057 /**
058 * Initializes this attribute syntax based on the information in the
059 * provided configuration entry.
060 *
061 * @param configuration The configuration to use to initialize
062 * this attribute syntax.
063 *
064 * @throws ConfigException If an unrecoverable problem arises in
065 * the process of performing the
066 * initialization.
067 *
068 * @throws InitializationException If a problem occurs during
069 * initialization that is not
070 * related to the server
071 * configuration.
072 */
073 public abstract void initializeSyntax(T configuration)
074 throws ConfigException, InitializationException;
075
076
077
078 /**
079 * Indicates whether the provided configuration is acceptable for
080 * this attribute syntax. It should be possible to call this method
081 * on an uninitialized attribute syntax instance in order to
082 * determine whether the syntax would be able to use the provided
083 * configuration.
084 * <BR><BR>
085 * Note that implementations which use a subclass of the provided
086 * configuration class will likely need to cast the configuration
087 * to the appropriate subclass type.
088 *
089 * @param configuration The attribute syntax configuration
090 * for which to make the determination.
091 * @param unacceptableReasons A list that may be used to hold the
092 * reasons that the provided
093 * configuration is not acceptable.
094 *
095 * @return {@code true} if the provided configuration is acceptable
096 * for this attribute syntax, or {@code false} if not.
097 */
098 public boolean isConfigurationAcceptable(
099 AttributeSyntaxCfg configuration,
100 List<Message> unacceptableReasons)
101 {
102 // This default implementation does not perform any special
103 // validation. It should be overridden by attribute syntax
104 // implementations that wish to perform more detailed validation.
105 return true;
106 }
107
108
109
110 /**
111 * Performs any finalization that may be necessary for this
112 * attribute syntax. By default, no finalization is performed.
113 */
114 public void finalizeSyntax()
115 {
116 // No implementation required.
117 }
118
119
120
121 /**
122 * Retrieves the common name for this attribute syntax.
123 *
124 * @return The common name for this attribute syntax.
125 */
126 public abstract String getSyntaxName();
127
128
129
130 /**
131 * Retrieves the OID for this attribute syntax.
132 *
133 * @return The OID for this attribute syntax.
134 */
135 public abstract String getOID();
136
137
138
139 /**
140 * Retrieves a description for this attribute syntax.
141 *
142 * @return A description for this attribute syntax.
143 */
144 public abstract String getDescription();
145
146
147
148 /**
149 * Retrieves the default equality matching rule that will be used
150 * for attributes with this syntax.
151 *
152 * @return The default equality matching rule that will be used for
153 * attributes with this syntax, or {@code null} if equality
154 * matches will not be allowed for this type by default.
155 */
156 public abstract EqualityMatchingRule getEqualityMatchingRule();
157
158
159
160 /**
161 * Retrieves the default ordering matching rule that will be used
162 * for attributes with this syntax.
163 *
164 * @return The default ordering matching rule that will be used for
165 * attributes with this syntax, or {@code null} if ordering
166 * matches will not be allowed for this type by default.
167 */
168 public abstract OrderingMatchingRule getOrderingMatchingRule();
169
170
171
172 /**
173 * Retrieves the default substring matching rule that will be used
174 * for attributes with this syntax.
175 *
176 * @return The default substring matching rule that will be used
177 * for attributes with this syntax, or {@code null} if
178 * substring matches will not be allowed for this type by
179 * default.
180 */
181 public abstract SubstringMatchingRule getSubstringMatchingRule();
182
183
184
185 /**
186 * Retrieves the default approximate matching rule that will be used
187 * for attributes with this syntax.
188 *
189 * @return The default approximate matching rule that will be used
190 * for attributes with this syntax, or {@code null} if
191 * approximate matches will not be allowed for this type by
192 * default.
193 */
194 public abstract ApproximateMatchingRule
195 getApproximateMatchingRule();
196
197
198
199 /**
200 * Indicates whether the provided value is acceptable for use in an
201 * attribute with this syntax. If it is not, then the reason may be
202 * appended to the provided buffer.
203 *
204 * @param value The value for which to make the
205 * determination.
206 * @param invalidReason The buffer to which the invalid reason
207 * should be appended.
208 *
209 * @return {@code true} if the provided value is acceptable for use
210 * with this syntax, or {@code false} if not.
211 */
212 public abstract boolean valueIsAcceptable(ByteString value,
213 MessageBuilder invalidReason);
214
215
216
217 /**
218 * Retrieves the hash code for this attribute syntax. It will be
219 * calculated as the sum of the characters in the OID.
220 *
221 * @return The hash code for this attribute syntax.
222 */
223 public final int hashCode()
224 {
225 int hashCode = 0;
226
227 String oidString = getOID();
228 int oidLength = oidString.length();
229 for (int i=0; i < oidLength; i++)
230 {
231 hashCode += oidString.charAt(i);
232 }
233
234 return hashCode;
235 }
236
237
238
239 /**
240 * Indicates whether the provided object is equal to this attribute
241 * syntax. The provided object will be considered equal to this
242 * attribute syntax only if it is an attribute syntax with the same
243 * OID.
244 *
245 * @param o The object for which to make the determination.
246 *
247 * @return {@code true} if the provided object is equal to this
248 * attribute syntax, or {@code false} if it is not.
249 */
250 public final boolean equals(Object o)
251 {
252 if (o == null)
253 {
254 return false;
255 }
256
257 if (this == o)
258 {
259 return true;
260 }
261
262 if (! (o instanceof AttributeSyntax))
263 {
264 return false;
265 }
266
267 return getOID().equals(((AttributeSyntax) o).getOID());
268 }
269
270
271
272 /**
273 * Retrieves a string representation of this attribute syntax in the
274 * format defined in RFC 2252.
275 *
276 * @return A string representation of this attribute syntax in the
277 * format defined in RFC 2252.
278 */
279 public final String toString()
280 {
281 StringBuilder buffer = new StringBuilder();
282 toString(buffer);
283 return buffer.toString();
284 }
285
286
287
288 /**
289 * Appends a string representation of this attribute syntax in the
290 * format defined in RFC 2252 to the provided buffer.
291 *
292 * @param buffer The buffer to which the information should be
293 * appended.
294 */
295 public final void toString(StringBuilder buffer)
296 {
297 buffer.append("( ");
298 buffer.append(getOID());
299
300 String description = getDescription();
301 if ((description == null) || (description.length() == 0))
302 {
303 buffer.append(" )");
304 }
305 else
306 {
307 buffer.append(" DESC '");
308 buffer.append(description);
309 buffer.append("' )");
310 }
311 }
312 }
313