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 javax.naming.NamingException;
024    import java.util.Comparator;
025    
026    
027    /**
028     * A matchingRule definition. MatchingRules associate a comparator and a
029     * normalizer, forming the basic tools necessary to assert actions against
030     * attribute values. MatchingRules are associated with a specific Syntax for the
031     * purpose of resolving a normalized form and for comparisons.
032     * <p>
033     * According to ldapbis [MODELS]:
034     * </p>
035     * 
036     * <pre>
037     *  4.1.3. Matching Rules
038     *  
039     *    Matching rules are used by servers to compare attribute values against
040     *    assertion values when performing Search and Compare operations.  They
041     *    are also used to identify the value to be added or deleted when
042     *    modifying entries, and are used when comparing a purported
043     *    distinguished name with the name of an entry.
044     *  
045     *    A matching rule specifies the syntax of the assertion value.
046     * 
047     *    Each matching rule is identified by an object identifier (OID) and,
048     *    optionally, one or more short names (descriptors).
049     * 
050     *    Matching rule definitions are written according to the ABNF:
051     * 
052     *      MatchingRuleDescription = LPAREN WSP
053     *          numericoid                ; object identifier
054     *          [ SP &quot;NAME&quot; SP qdescrs ]  ; short names (descriptors)
055     *          [ SP &quot;DESC&quot; SP qdstring ] ; description
056     *          [ SP &quot;OBSOLETE&quot; ]         ; not active
057     *          SP &quot;SYNTAX&quot; SP numericoid ; assertion syntax
058     *          extensions WSP RPAREN     ; extensions
059     * 
060     *    where:
061     *      [numericoid] is object identifier assigned to this matching rule;
062     *      NAME [qdescrs] are short names (descriptors) identifying this
063     *          matching rule;
064     *      DESC [qdstring] is a short descriptive string;
065     *      OBSOLETE indicates this matching rule is not active;
066     *      SYNTAX identifies the assertion syntax by object identifier; and
067     *      [extensions] describe extensions.
068     * </pre>
069     * 
070     * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC 2252 Section 4.5</a>
071     * @see <a
072     *      href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
073     *      [MODELS]</a>
074     * @see DescriptionUtils#getDescription(MatchingRule)
075     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
076     * @version $Rev: 604361 $
077     */
078    public interface MatchingRule extends SchemaObject
079    {
080        /**
081         * Gets the SyntaxImpl used by this MatchingRule.
082         * 
083         * @return the SyntaxImpl of this MatchingRule
084         * @throws NamingException
085         *             if there is a failure resolving the object
086         */
087        Syntax getSyntax() throws NamingException;
088    
089    
090        /**
091         * Gets the Comparator enabling the use of this MatchingRule for ORDERING
092         * and sorted indexing.
093         * 
094         * @return the ordering Comparator
095         * @throws NamingException
096         *             if there is a failure resolving the object
097         */
098        Comparator getComparator() throws NamingException;
099    
100    
101        /**
102         * Gets the Normalizer enabling the use of this MatchingRule for EQUALITY
103         * matching and indexing.
104         * 
105         * @return the ordering Comparator
106         * @throws NamingException
107         *             if there is a failure resolving the object
108         */
109        Normalizer getNormalizer() throws NamingException;
110    }