View Javadoc
1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    * 
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   * 
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   * 
19   */
20  package org.apache.directory.api.ldap.model.schema;
21  
22  
23  
24  
25  /**
26   * A matchingRule definition. MatchingRules associate a comparator and a
27   * normalizer, forming the basic tools necessary to assert actions against
28   * attribute values. MatchingRules are associated with a specific Syntax for the
29   * purpose of resolving a normalized form and for comparisons.
30   * <p>
31   * According to ldapbis [MODELS]:
32   * </p>
33   * 
34   * <pre>
35   *  4.1.3. Matching Rules
36   * 
37   *    Matching rules are used by servers to compare attribute values against
38   *    assertion values when performing Search and Compare operations.  They
39   *    are also used to identify the value to be added or deleted when
40   *    modifying entries, and are used when comparing a purported
41   *    distinguished name with the name of an entry.
42   * 
43   *    A matching rule specifies the syntax of the assertion value.
44   * 
45   *    Each matching rule is identified by an object identifier (OID) and,
46   *    optionally, one or more short names (descriptors).
47   * 
48   *    Matching rule definitions are written according to the ABNF:
49   * 
50   *      MatchingRuleDescription = LPAREN WSP
51   *          numericoid                ; object identifier
52   *          [ SP &quot;NAME&quot; SP qdescrs ]  ; short names (descriptors)
53   *          [ SP &quot;DESC&quot; SP qdstring ] ; description
54   *          [ SP &quot;OBSOLETE&quot; ]         ; not active
55   *          SP &quot;SYNTAX&quot; SP numericoid ; assertion syntax
56   *          extensions WSP RPAREN     ; extensions
57   * 
58   *    where:
59   *      [numericoid] is object identifier assigned to this matching rule;
60   *      NAME [qdescrs] are short names (descriptors) identifying this
61   *          matching rule;
62   *      DESC [qdstring] is a short descriptive string;
63   *      OBSOLETE indicates this matching rule is not active;
64   *      SYNTAX identifies the assertion syntax by object identifier; and
65   *      [extensions] describe extensions.
66   * </pre>
67   * 
68   * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC 2252 Section 4.5</a>
69   * @see <a
70   *      href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
71   *      [MODELS]</a>
72   * @see DescriptionUtils#getDescription(MatchingRule)
73   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
74   */
75  public class MatchingRule extends AbstractSchemaObject
76  {
77      /** The mandatory serialVersionUID */
78      public static final long serialVersionUID = 1L;
79  
80      /** The associated Comparator */
81      protected LdapComparator<? super Object> ldapComparator;
82  
83      /** The associated Normalizer */
84      protected Normalizer normalizer;
85  
86      /** The associated LdapSyntax */
87      protected LdapSyntax ldapSyntax;
88  
89      /** The associated LdapSyntax OID */
90      protected String ldapSyntaxOid;
91  
92  
93      /**
94       * Creates a new instance of MatchingRule.
95       *
96       * @param oid The MatchingRule OID
97       */
98      public MatchingRule( String oid )
99      {
100         super( SchemaObjectType.MATCHING_RULE, oid );
101     }
102 
103 
104     /**
105      * Gets the LdapSyntax used by this MatchingRule.
106      * 
107      * @return the LdapSyntax of this MatchingRule
108      */
109     public LdapSyntax getSyntax()
110     {
111         return ldapSyntax;
112     }
113 
114 
115     /**
116      * Gets the LdapSyntax OID used by this MatchingRule.
117      * 
118      * @return the LdapSyntax of this MatchingRule
119      */
120     public String getSyntaxOid()
121     {
122         return ldapSyntaxOid;
123     }
124 
125 
126     /**
127      * Gets the LdapComparator enabling the use of this MatchingRule for ORDERING
128      * and sorted indexing.
129      * 
130      * @return the ordering LdapComparator
131      */
132     public LdapComparator<? super Object> getLdapComparator()
133     {
134         return ldapComparator;
135     }
136 
137 
138     /**
139      * Gets the Normalizer enabling the use of this MatchingRule for EQUALITY
140      * matching and indexing.
141      * 
142      * @return the associated normalizer
143      */
144     public Normalizer getNormalizer()
145     {
146         return normalizer;
147     }
148 
149 
150     /**
151      * @see Object#toString()
152      */
153     public String toString()
154     {
155         return SchemaObjectRenderer.OPEN_LDAP_SCHEMA_RENDERER.render( this );
156     }
157 
158 
159     /**
160      * Copy an MatchingRule
161      */
162     public MatchingRule copy()
163     {
164         MatchingRule copy = new MutableMatchingRule( oid );
165 
166         // Copy the SchemaObject common data
167         copy.copy( this );
168 
169         // All the references to other Registries object are set to null.
170         copy.ldapComparator = null;
171         copy.ldapSyntax = null;
172         copy.normalizer = null;
173 
174         // Copy the syntax OID
175         copy.ldapSyntaxOid = ldapSyntaxOid;
176 
177         return copy;
178     }
179 
180 
181     /**
182      * @see Object#equals()
183      */
184     @Override
185     public boolean equals( Object o )
186     {
187         if ( !super.equals( o ) )
188         {
189             return false;
190         }
191 
192         if ( !( o instanceof MatchingRule ) )
193         {
194             return false;
195         }
196 
197         MatchingRule that = ( MatchingRule ) o;
198 
199         // Check the Comparator
200         if ( ldapComparator != null )
201         {
202             if ( !ldapComparator.equals( that.ldapComparator ) )
203             {
204                 return false;
205             }
206         }
207         else
208         {
209             if ( that.ldapComparator != null )
210             {
211                 return false;
212             }
213         }
214 
215         // Check the Normalizer
216         if ( normalizer != null )
217         {
218             if ( !normalizer.equals( that.normalizer ) )
219             {
220                 return false;
221             }
222         }
223         else
224         {
225             if ( that.normalizer != null )
226             {
227                 return false;
228             }
229         }
230 
231         // Check the Syntax OID
232         if ( !compareOid( ldapSyntaxOid, that.ldapSyntaxOid ) )
233         {
234             return false;
235         }
236 
237         // Check the Syntax
238         if ( ldapSyntax != null )
239         {
240             if ( !ldapSyntax.equals( that.ldapSyntax ) )
241             {
242                 return false;
243             }
244         }
245         else
246         {
247             if ( that.ldapSyntax != null )
248             {
249                 return false;
250             }
251         }
252 
253         return true;
254     }
255 }