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-2012 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.common.schema;
028
029
030
031 import com.unboundid.directory.sdk.common.types.ConditionResult;
032 import com.unboundid.ldap.sdk.LDAPException;
033 import com.unboundid.util.ByteString;
034 import com.unboundid.util.NotExtensible;
035 import com.unboundid.util.ThreadSafety;
036 import 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)
046 public 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 }