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