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 java.util.List;
032    
033    import org.opends.server.admin.std.server.SubstringMatchingRuleCfg;
034    import org.opends.server.types.ByteString;
035    import org.opends.server.types.ConditionResult;
036    import org.opends.server.types.DirectoryException;
037    
038    
039    
040    /**
041     * This class defines the set of methods and structures that must be
042     * implemented by a Directory Server module that implements a matching
043     * rule used for substring matching.
044     */
045    @org.opends.server.types.PublicAPI(
046         stability=org.opends.server.types.StabilityLevel.VOLATILE,
047         mayInstantiate=false,
048         mayExtend=true,
049         mayInvoke=false)
050    public abstract class SubstringMatchingRule
051           extends MatchingRule<SubstringMatchingRuleCfg>
052    {
053      /**
054       * Normalizes the provided value fragment into a form that can be
055       * used to efficiently compare values.
056       *
057       * @param  substring  The value fragment to be normalized.
058       *
059       * @return  The normalized form of the value fragment.
060       *
061       * @throws  DirectoryException  If the provided value fragment is
062       *                              not acceptable according to the
063       *                              associated syntax.
064       */
065      public abstract ByteString normalizeSubstring(ByteString substring)
066             throws DirectoryException;
067    
068    
069    
070      /**
071       * Determines whether the provided value matches the given substring
072       * filter components.  Note that any of the substring filter
073       * components may be {@code null} but at least one of them must be
074       * non-{@code null}.
075       *
076       * @param  value           The normalized value against which to
077       *                         compare the substring components.
078       * @param  subInitial      The normalized substring value fragment
079       *                         that should appear at the beginning of
080       *                         the target value.
081       * @param  subAnyElements  The normalized substring value fragments
082       *                         that should appear in the middle of the
083       *                         target value.
084       * @param  subFinal        The normalized substring value fragment
085       *                         that should appear at the end of the
086       *                         target value.
087       *
088       * @return  {@code true} if the provided value does match the given
089       *          substring components, or {@code false} if not.
090       */
091      public abstract boolean valueMatchesSubstring(
092                                   ByteString value,
093                                   ByteString subInitial,
094                                   List<ByteString> subAnyElements,
095                                   ByteString subFinal);
096    
097    
098    
099      /**
100       * Indicates whether the provided attribute value should be
101       * considered a match for the given assertion value.  This will only
102       * be used for the purpose of extensible matching.
103       * <BR><BR>
104       * Note that substring matching rules by default do not support
105       * extensible matching, and therefore this method will always return
106       * {@code UNDEFINED}.  If a substring matching rule does support
107       * extensible matching operations, then it should override this
108       * method and provide an appropriate implementation.
109       *
110       * @param  attributeValue  The attribute value in a form that has
111       *                         been normalized according to this
112       *                         matching rule.
113       * @param  assertionValue  The assertion value in a form that has
114       *                         been normalized according to this
115       *                         matching rule.
116       *
117       * @return  {@code true} if the attribute value should be considered
118       *          a match for the provided assertion value, or
119       *          {@code false} if not.
120       */
121      public ConditionResult valuesMatch(ByteString attributeValue,
122                                         ByteString assertionValue)
123      {
124        return ConditionResult.UNDEFINED;
125      }
126    }
127