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 */
020package org.apache.directory.api.ldap.model.schema;
021
022
023import org.apache.directory.api.i18n.I18n;
024
025
026/**
027 * A matchingRule definition. MatchingRules associate a comparator and a
028 * normalizer, forming the basic tools necessary to assert actions against
029 * attribute values. MatchingRules are associated with a specific Syntax for the
030 * purpose of resolving a normalized form and for comparisons.
031 * <p>
032 * According to ldapbis [MODELS]:
033 * </p>
034 * 
035 * <pre>
036 *  4.1.3. Matching Rules
037 * 
038 *    Matching rules are used by servers to compare attribute values against
039 *    assertion values when performing Search and Compare operations.  They
040 *    are also used to identify the value to be added or deleted when
041 *    modifying entries, and are used when comparing a purported
042 *    distinguished name with the name of an entry.
043 * 
044 *    A matching rule specifies the syntax of the assertion value.
045 * 
046 *    Each matching rule is identified by an object identifier (OID) and,
047 *    optionally, one or more short names (descriptors).
048 * 
049 *    Matching rule definitions are written according to the ABNF:
050 * 
051 *      MatchingRuleDescription = LPAREN WSP
052 *          numericoid                ; object identifier
053 *          [ SP &quot;NAME&quot; SP qdescrs ]  ; short names (descriptors)
054 *          [ SP &quot;DESC&quot; SP qdstring ] ; description
055 *          [ SP &quot;OBSOLETE&quot; ]         ; not active
056 *          SP &quot;SYNTAX&quot; SP numericoid ; assertion syntax
057 *          extensions WSP RPAREN     ; extensions
058 * 
059 *    where:
060 *      [numericoid] is object identifier assigned to this matching rule;
061 *      NAME [qdescrs] are short names (descriptors) identifying this
062 *          matching rule;
063 *      DESC [qdstring] is a short descriptive string;
064 *      OBSOLETE indicates this matching rule is not active;
065 *      SYNTAX identifies the assertion syntax by object identifier; and
066 *      [extensions] describe extensions.
067 * </pre>
068 * 
069 * @see <a href="http://www.faqs.org/rfcs/rfc2252.html">RFC 2252 Section 4.5</a>
070 * @see <a
071 *      href="http://www.ietf.org/internet-drafts/draft-ietf-ldapbis-models-11.txt">ldapbis
072 *      [MODELS]</a>
073 * @see DescriptionUtils#getDescription(MutableMatchingRule)
074 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
075 */
076public class MutableMatchingRule extends MatchingRule
077{
078    /** The mandatory serialVersionUID */
079    public static final long serialVersionUID = 1L;
080
081
082    /**
083     * Creates a new instance of MatchingRule.
084     *
085     * @param oid The MatchingRule OID
086     */
087    public MutableMatchingRule( String oid )
088    {
089        super( oid );
090    }
091
092
093    /**
094     * Sets the Syntax's OID
095     *
096     * @param oid The Syntax's OID
097     */
098    public void setSyntaxOid( String oid )
099    {
100        if ( locked )
101        {
102            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
103        }
104
105        if ( !isReadOnly )
106        {
107            this.ldapSyntaxOid = oid;
108        }
109    }
110
111
112    /**
113     * Sets the Syntax
114     *
115     * @param ldapSyntax The Syntax
116     */
117    public void setSyntax( LdapSyntax ldapSyntax )
118    {
119        if ( locked )
120        {
121            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
122        }
123
124        if ( !isReadOnly )
125        {
126            this.ldapSyntax = ldapSyntax;
127            this.ldapSyntaxOid = ldapSyntax.getOid();
128        }
129    }
130
131
132    /**
133     * Update the associated Syntax, even if the SchemaObject is readOnly
134     *
135     * @param ldapSyntax The Syntax
136     */
137    public void updateSyntax( LdapSyntax ldapSyntax )
138    {
139        if ( locked )
140        {
141            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
142        }
143
144        this.ldapSyntax = ldapSyntax;
145        this.ldapSyntaxOid = ldapSyntax.getOid();
146    }
147
148
149    /**
150     * Sets the LdapComparator
151     *
152     * @param ldapComparator The LdapComparator
153     */
154    @SuppressWarnings("unchecked")
155    public void setLdapComparator( LdapComparator<?> ldapComparator )
156    {
157        if ( locked )
158        {
159            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
160        }
161
162        if ( !isReadOnly )
163        {
164            this.ldapComparator = ( LdapComparator<? super Object> ) ldapComparator;
165        }
166    }
167
168
169    /**
170     * Update the associated Comparator, even if the SchemaObject is readOnly
171     *
172     * @param ldapComparator The LdapComparator
173     */
174    @SuppressWarnings("unchecked")
175    public void updateLdapComparator( LdapComparator<?> ldapComparator )
176    {
177        if ( locked )
178        {
179            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
180        }
181
182        this.ldapComparator = ( LdapComparator<? super Object> ) ldapComparator;
183    }
184
185
186    /**
187     * Sets the Normalizer
188     *
189     * @param normalizer The Normalizer
190     */
191    public void setNormalizer( Normalizer normalizer )
192    {
193        if ( locked )
194        {
195            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
196        }
197
198        if ( !isReadOnly )
199        {
200            this.normalizer = normalizer;
201        }
202    }
203
204
205    /**
206     * Update the associated Normalizer, even if the SchemaObject is readOnly
207     *
208     * @param normalizer The Normalizer
209     */
210    public void updateNormalizer( Normalizer normalizer )
211    {
212        if ( locked )
213        {
214            throw new UnsupportedOperationException( I18n.err( I18n.ERR_04441, getName() ) );
215        }
216
217        this.normalizer = normalizer;
218    }
219
220
221    /**
222     * {@inheritDoc}
223     */
224    public void clear()
225    {
226        // Clear the common elements
227        super.clear();
228
229        // Clear the references
230        ldapComparator = null;
231        ldapSyntax = null;
232        normalizer = null;
233    }
234}