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 ForgeRock AS
026 */
027package org.forgerock.opendj.ldap;
028
029
030import org.forgerock.opendj.ldap.spi.IndexQueryFactory;
031
032/**
033 * A compiled attribute value assertion.
034 */
035public interface Assertion {
036
037    /** An assertion that always return UNDEFINED for matches and that creates a match all query. */
038    Assertion UNDEFINED_ASSERTION = new Assertion() {
039        @Override
040        public ConditionResult matches(final ByteSequence normalizedAttributeValue) {
041            return ConditionResult.UNDEFINED;
042        }
043
044        @Override
045        public <T> T createIndexQuery(IndexQueryFactory<T> factory) throws DecodeException {
046            // Subclassing this class will always work, albeit inefficiently.
047            // This is better than throwing an exception for no good reason.
048            return factory.createMatchAllQuery();
049        }
050    };
051
052    /**
053     * Indicates whether the provided attribute value should be considered a
054     * match for this assertion value according to the matching rule.
055     *
056     * @param normalizedAttributeValue
057     *            The normalized attribute value.
058     * @return {@code TRUE} if the attribute value should be considered a match
059     *         for the provided assertion value, {@code FALSE} if it does not
060     *         match, or {@code UNDEFINED} if the result is undefined.
061     */
062    ConditionResult matches(ByteSequence normalizedAttributeValue);
063
064    /**
065     * Returns an index query appropriate for the provided attribute
066     * value assertion.
067     *
068     * @param <T>
069     *          The type of index query created by the {@code factory}.
070     * @param factory
071     *          The index query factory which should be used to
072     *          construct the index query.
073     * @return The index query appropriate for the provided attribute
074     *         value assertion.
075     * @throws DecodeException
076     *           If an error occurs while generating the index query.
077     */
078    <T> T createIndexQuery(IndexQueryFactory<T> factory) throws DecodeException;
079
080}