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 *      Portions Copyright 2010-2024 Ping Identity Corporation
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   * Retrieves the normalized form of the provided value.
141   *
142   * @param  type   The associated attribute type.
143   * @param  value  The value to be normalized.
144   *
145   * @return  The normalized form of the provided value.
146   *
147   * @throws  LDAPException  If an error occurs while attempting to normalize
148   *                         the provided value (e.g., it does not conform to
149   *                         the appropriate syntax).
150   */
151  ByteString normalizeValue(final AttributeType type, final ByteString value)
152       throws LDAPException;
153
154
155
156  /**
157   * Indicates whether the provided attribute value may be considered logically
158   * equivalent to the provided assertion value according to the constraints of
159   * this matching rule..
160   *
161   * @param  normAttributeValue  The normalized form of the attribute value to
162   *                             be compared.
163   * @param  normAssertionValue  The normalized form of the assertion value to
164   *                             be compared.
165   *
166   * @return  {@code TRUE} if the values are considered equal,
167   *          {@code FALSE} if the values are considered different, or
168   *          {@code UNDEFINED} if the result is not defined for this matching
169   *          rule.
170   */
171  ConditionResult valuesMatch(final ByteString normAttributeValue,
172                              final ByteString normAssertionValue);
173
174
175
176  /**
177   * Retrieves the hash code for this matching rule.
178   *
179   * @return  The hash code for this matching rule.
180   */
181  int hashCode();
182
183
184
185  /**
186   * Indicates whether the provided object is equal to this matching rule.
187   *
188   * @param  o  The object for which to make the determination.
189   *
190   * @return  {@code true} if the provided object is equal to this matching
191   *          rule, or {@code false} if not.
192   */
193  boolean equals(final Object o);
194
195
196
197  /**
198   * Retrieves a string representation of this matching rule.
199   *
200   * @return  A string representation of this matching rule.
201   */
202  String toString();
203}