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