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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. 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 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.api;
028
029
030
031 import org.opends.server.admin.std.server.EqualityMatchingRuleCfg;
032 import org.opends.server.loggers.debug.DebugTracer;
033 import org.opends.server.types.AttributeValue;
034 import org.opends.server.types.ByteString;
035 import org.opends.server.types.ConditionResult;
036 import org.opends.server.types.DebugLogLevel;
037
038 import static org.opends.server.loggers.debug.DebugLogger.*;
039
040
041
042 /**
043 * This class defines the set of methods and structures that must be
044 * implemented by a Directory Server module that implements a matching
045 * rule used for equality matching.
046 */
047 @org.opends.server.types.PublicAPI(
048 stability=org.opends.server.types.StabilityLevel.VOLATILE,
049 mayInstantiate=false,
050 mayExtend=true,
051 mayInvoke=false)
052 public abstract class EqualityMatchingRule
053 extends MatchingRule<EqualityMatchingRuleCfg>
054 {
055 /**
056 * The tracer object for the debug logger.
057 */
058 private static final DebugTracer TRACER = getTracer();
059
060 /**
061 * Indicates whether the two provided normalized values are equal to
062 * each other.
063 *
064 * @param value1 The normalized form of the first value to
065 * compare.
066 * @param value2 The normalized form of the second value to
067 * compare.
068 *
069 * @return {@code true} if the provided values are equal, or
070 * {@code false} if not.
071 */
072 public abstract boolean areEqual(ByteString value1,
073 ByteString value2);
074
075
076
077 /**
078 * Indicates whether the provided attribute value should be
079 * considered a match for the given assertion value. This will only
080 * be used for the purpose of extensible matching. Other forms of
081 * matching against equality matching rules should use the
082 * {@code areEqual} method.
083 *
084 * @param attributeValue The attribute value in a form that has
085 * been normalized according to this
086 * matching rule.
087 * @param assertionValue The assertion value in a form that has
088 * been normalized according to this
089 * matching rule.
090 *
091 * @return {@code true} if the attribute value should be considered
092 * a match for the provided assertion value, or
093 * {@code false} if not.
094 */
095 public ConditionResult valuesMatch(ByteString attributeValue,
096 ByteString assertionValue)
097 {
098 if (areEqual(attributeValue, assertionValue))
099 {
100 return ConditionResult.TRUE;
101 }
102 else
103 {
104 return ConditionResult.FALSE;
105 }
106 }
107
108
109
110 /**
111 * Generates a hash code for the provided attribute value. This
112 * version of the method will simply create a hash code from the
113 * normalized form of the attribute value. For matching rules
114 * explicitly designed to work in cases where byte-for-byte
115 * comparisons of normalized values is not sufficient for
116 * determining equality (e.g., if the associated attribute syntax is
117 * based on hashed or encrypted values), then this method must be
118 * overridden to provide an appropriate implementation for that
119 * case.
120 *
121 * @param attributeValue The attribute value for which to generate
122 * the hash code.
123 *
124 * @return The hash code generated for the provided attribute
125 * value.
126 */
127 public int generateHashCode(AttributeValue attributeValue)
128 {
129 try
130 {
131 return attributeValue.getNormalizedValue().hashCode();
132 }
133 catch (Exception e)
134 {
135 if (debugEnabled())
136 {
137 TRACER.debugCaught(DebugLogLevel.ERROR, e);
138 }
139
140 try
141 {
142 return attributeValue.getValue().hashCode();
143 }
144 catch (Exception e2)
145 {
146 if (debugEnabled())
147 {
148 TRACER.debugCaught(DebugLogLevel.ERROR, e2);
149 }
150
151 return 0;
152 }
153 }
154 }
155 }
156