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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt.  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 2010-2016 UnboundID Corp.
026 */
027package com.unboundid.directory.sdk.common.schema;
028
029
030
031import com.unboundid.directory.sdk.common.types.ConditionResult;
032import com.unboundid.ldap.sdk.LDAPException;
033import com.unboundid.util.ByteString;
034import com.unboundid.util.NotExtensible;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038
039
040/**
041 * This interface provides an API for interacting with matching rules, which
042 * can be used to perform matching-related operations against data.
043 */
044@NotExtensible()
045@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
046public interface MatchingRule
047{
048  /**
049   * Retrieves the numeric OID for this matching rule.
050   *
051   * @return  The numeric OID for this matching rule.
052   */
053  String getOID();
054
055
056
057  /**
058   * Retrieves the name for this matching rule, if any.
059   *
060   * @return  The name for this matching rule, or {@code null} if it does not
061   *          have a name.
062   */
063  String getName();
064
065
066
067  /**
068   * Retrieves the name for this matching rule, or the numeric OID if it does
069   * not have a name.
070   *
071   * @return  The name for this matching rule, or the numeric OID if it does not
072   *          have a name.
073   */
074  String getNameOrOID();
075
076
077
078  /**
079   * Indicates whether the provided string matches the name or numeric OID for
080   * this matching rule.
081   *
082   * @param  name  The name for which to make the determination.
083   *
084   * @return  {@code true} if the provided string matches the name or numeric
085   *          OID for this matching rule, or {@code false} if not.
086   */
087  boolean hasNameOrOID(final String name);
088
089
090
091  /**
092   * Retrieves the description for this matching rule, if any.
093   *
094   * @return  The description for this matching rule, or {@code null} if it does
095   *          not have a description.
096   */
097  String getDescription();
098
099
100
101  /**
102   * Retrieves the OID of the attribute syntax with which this matching rule is
103   * most closely associated.
104   *
105   * @return  The OID of the attribute syntax with which this matching rule is
106   *          most closely associated.
107   */
108  String getSyntaxOID();
109
110
111
112  /**
113   * Indicates whether this matching rule is declared obsolete in the server
114   * schema.
115   *
116   * @return  {@code true} if this matching rule is declared obsolete, or
117   *          {@code false} if not.
118   */
119  boolean isObsolete();
120
121
122
123  /**
124   * Retrieves the normalized form of the provided value.
125   *
126   * @param  value  The value to be normalized.
127   *
128   * @return  The normalized form of the provided value.
129   *
130   * @throws  LDAPException  If an error occurs while attempting to normalize
131   *                         the provided value (e.g., it does not conform to
132   *                         the appropriate syntax).
133   */
134  ByteString normalizeValue(final ByteString value)
135       throws LDAPException;
136
137
138
139  /**
140   * Indicates whether the provided attribute value may be considered logically
141   * equivalent to the provided assertion value according to the constraints of
142   * this matching rule..
143   *
144   * @param  normAttributeValue  The normalized form of the attribute value to
145   *                             be compared.
146   * @param  normAssertionValue  The normalized form of the assertion value to
147   *                             be compared.
148   *
149   * @return  {@code TRUE} if the values are considered equal,
150   *          {@code FALSE} if the values are considered different, or
151   *          {@code UNDEFINED} if the result is not defined for this matching
152   *          rule.
153   */
154  ConditionResult valuesMatch(final ByteString normAttributeValue,
155                              final ByteString normAssertionValue);
156
157
158
159  /**
160   * Retrieves the hash code for this matching rule.
161   *
162   * @return  The hash code for this matching rule.
163   */
164  int hashCode();
165
166
167
168  /**
169   * Indicates whether the provided object is equal to this matching rule.
170   *
171   * @param  o  The object for which to make the determination.
172   *
173   * @return  {@code true} if the provided object is equal to this matching
174   *          rule, or {@code false} if not.
175   */
176  boolean equals(final Object o);
177
178
179
180  /**
181   * Retrieves a string representation of this matching rule.
182   *
183   * @return  A string representation of this matching rule.
184   */
185  String toString();
186}