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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 *      Portions copyright 2014-2015 ForgeRock AS
026 */
027package org.forgerock.opendj.ldap.schema;
028
029import java.util.Collection;
030import java.util.List;
031
032import org.forgerock.opendj.ldap.Assertion;
033import org.forgerock.opendj.ldap.ByteSequence;
034import org.forgerock.opendj.ldap.ByteString;
035import org.forgerock.opendj.ldap.DecodeException;
036import org.forgerock.opendj.ldap.spi.Indexer;
037import org.forgerock.opendj.ldap.spi.IndexingOptions;
038
039/**
040 * This interface defines the set of methods that must be implemented to define
041 * a new matching rule.
042 */
043public interface MatchingRuleImpl {
044
045    /**
046     * Retrieves the normalized form of the provided assertion value, which is
047     * best suited for efficiently performing less than matching operations on
048     * that value. The assertion value is guaranteed to be valid against this
049     * matching rule's assertion syntax.
050     *
051     * @param schema
052     *            The schema in which this matching rule is defined.
053     * @param assertionValue
054     *            The syntax checked assertion value to be normalized.
055     * @return The normalized version of the provided assertion value.
056     * @throws DecodeException
057     *             if an syntax error occurred while parsing the value.
058     */
059    Assertion getAssertion(Schema schema, ByteSequence assertionValue) throws DecodeException;
060
061    /**
062     * Retrieves the normalized form of the provided assertion substring values,
063     * which is best suited for efficiently performing matching operations on
064     * that value.
065     *
066     * @param schema
067     *            The schema in which this matching rule is defined.
068     * @param subInitial
069     *            The normalized substring value fragment that should appear at
070     *            the beginning of the target value.
071     * @param subAnyElements
072     *            The normalized substring value fragments that should appear in
073     *            the middle of the target value.
074     * @param subFinal
075     *            The normalized substring value fragment that should appear at
076     *            the end of the target value.
077     * @return The normalized version of the provided assertion value.
078     * @throws DecodeException
079     *             if an syntax error occurred while parsing the value.
080     */
081    Assertion getSubstringAssertion(Schema schema, ByteSequence subInitial,
082            List<? extends ByteSequence> subAnyElements, ByteSequence subFinal)
083            throws DecodeException;
084
085    /**
086     * Retrieves the normalized form of the provided assertion value, which is
087     * best suited for efficiently performing greater than or equal matching
088     * operations on that value. The assertion value is guaranteed to be valid
089     * against this matching rule's assertion syntax.
090     *
091     * @param schema
092     *            The schema in which this matching rule is defined.
093     * @param value
094     *            The syntax checked assertion value to be normalized.
095     * @return The normalized version of the provided assertion value.
096     * @throws DecodeException
097     *             if an syntax error occurred while parsing the value.
098     */
099    Assertion getGreaterOrEqualAssertion(Schema schema, ByteSequence value) throws DecodeException;
100
101    /**
102     * Retrieves the normalized form of the provided assertion value, which is
103     * best suited for efficiently performing less than or equal matching
104     * operations on that value. The assertion value is guaranteed to be valid
105     * against this matching rule's assertion syntax.
106     *
107     * @param schema
108     *            The schema in which this matching rule is defined.
109     * @param value
110     *            The syntax checked assertion value to be normalized.
111     * @return The normalized version of the provided assertion value.
112     * @throws DecodeException
113     *             if an syntax error occurred while parsing the value.
114     */
115    Assertion getLessOrEqualAssertion(Schema schema, ByteSequence value) throws DecodeException;
116
117    /**
118     * Retrieves the normalized form of the provided attribute value, which is
119     * best suited for efficiently performing matching operations on that value.
120     * Equality and ordering matching rules should return a normalized
121     * representation which can be compared with other normalized values using
122     * {@link ByteSequence#equals(Object)} and
123     * {@link ByteSequence#compareTo(ByteSequence)}.
124     *
125     * @param schema
126     *            The schema in which this matching rule is defined.
127     * @param value
128     *            The attribute value to be normalized.
129     * @return The normalized version of the provided attribute value.
130     * @throws DecodeException
131     *             If an syntax error occurred while parsing the value.
132     */
133    ByteString normalizeAttributeValue(Schema schema, ByteSequence value) throws DecodeException;
134
135    /**
136     * Returns the indexers for this matching rule.
137     * @param options
138     *          The indexing options
139     * @return a non null collection of indexers for this matching rule.
140     */
141    Collection<? extends Indexer> createIndexers(IndexingOptions options);
142}