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