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