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   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
73   */
74  public class MatchingRule extends AbstractSchemaObject
75  {
76      /** The mandatory serialVersionUID */
77      public static final long serialVersionUID = 1L;
78  
79      /** The associated Comparator */
80      protected LdapComparator<? super Object> ldapComparator;
81  
82      /** The associated Normalizer */
83      protected Normalizer normalizer;
84  
85      /** The associated LdapSyntax */
86      protected LdapSyntax ldapSyntax;
87  
88      /** The associated LdapSyntax OID */
89      protected String ldapSyntaxOid;
90  
91  
92      /**
93       * Creates a new instance of MatchingRule.
94       *
95       * @param oid The MatchingRule OID
96       */
97      public MatchingRule( String oid )
98      {
99          super( SchemaObjectType.MATCHING_RULE, oid );
100     }
101 
102 
103     /**
104      * Gets the LdapSyntax used by this MatchingRule.
105      * 
106      * @return the LdapSyntax of this MatchingRule
107      */
108     public LdapSyntax getSyntax()
109     {
110         return ldapSyntax;
111     }
112 
113 
114     /**
115      * Gets the LdapSyntax OID used by this MatchingRule.
116      * 
117      * @return the LdapSyntax of this MatchingRule
118      */
119     public String getSyntaxOid()
120     {
121         return ldapSyntaxOid;
122     }
123 
124 
125     /**
126      * Gets the LdapComparator enabling the use of this MatchingRule for ORDERING
127      * and sorted indexing.
128      * 
129      * @return the ordering LdapComparator
130      */
131     public LdapComparator<? super Object> getLdapComparator()
132     {
133         return ldapComparator;
134     }
135 
136 
137     /**
138      * Gets the Normalizer enabling the use of this MatchingRule for EQUALITY
139      * matching and indexing.
140      * 
141      * @return the associated normalizer
142      */
143     public Normalizer getNormalizer()
144     {
145         return normalizer;
146     }
147 
148 
149     /**
150      * @see Object#toString()
151      */
152     @Override
153     public String toString()
154     {
155         return SchemaObjectRenderer.OPEN_LDAP_SCHEMA_RENDERER.render( this );
156     }
157 
158 
159     /**
160      * Copy an MatchingRule
161      */
162     @Override
163     public MatchingRule copy()
164     {
165         MatchingRule copy = new MutableMatchingRule( oid );
166 
167         // Copy the SchemaObject common data
168         copy.copy( this );
169 
170         // All the references to other Registries object are set to null.
171         copy.ldapComparator = null;
172         copy.ldapSyntax = null;
173         copy.normalizer = null;
174 
175         // Copy the syntax OID
176         copy.ldapSyntaxOid = ldapSyntaxOid;
177 
178         return copy;
179     }
180 
181 
182     /**
183      * @see Object#equals(Object)
184      */
185     @Override
186     public boolean equals( Object o )
187     {
188         if ( !super.equals( o ) )
189         {
190             return false;
191         }
192 
193         if ( !( o instanceof MatchingRule ) )
194         {
195             return false;
196         }
197 
198         MatchingRule that = ( MatchingRule ) o;
199 
200         // Check the Comparator
201         if ( ldapComparator != null )
202         {
203             if ( !ldapComparator.equals( that.ldapComparator ) )
204             {
205                 return false;
206             }
207         }
208         else
209         {
210             if ( that.ldapComparator != null )
211             {
212                 return false;
213             }
214         }
215 
216         // Check the Normalizer
217         if ( normalizer != null )
218         {
219             if ( !normalizer.equals( that.normalizer ) )
220             {
221                 return false;
222             }
223         }
224         else
225         {
226             if ( that.normalizer != null )
227             {
228                 return false;
229             }
230         }
231 
232         // Check the Syntax OID
233         if ( !compareOid( ldapSyntaxOid, that.ldapSyntaxOid ) )
234         {
235             return false;
236         }
237 
238         // Check the Syntax
239         if ( ldapSyntax != null )
240         {
241             if ( !ldapSyntax.equals( that.ldapSyntax ) )
242             {
243                 return false;
244             }
245         }
246         else
247         {
248             if ( that.ldapSyntax != null )
249             {
250                 return false;
251             }
252         }
253 
254         return true;
255     }
256 }