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