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.spi;
018
019import java.util.Collection;
020
021import org.forgerock.opendj.ldap.ByteSequence;
022
023/**
024 * A factory for creating arbitrarily complex index queries. This
025 * interface is implemented by the underlying backend implementation
026 * and passed to extensible matching rules so that they can construct
027 * arbitrarily complex index queries.
028 *
029 * @param <T>
030 *          The type of query created by this factory.
031 */
032public interface IndexQueryFactory<T> {
033
034    /**
035     * Returns a query requesting an index record matching the provided key.
036     *
037     * @param indexID
038     *          An identifier of the index type.
039     * @param key
040     *          A byte sequence containing the key.
041     * @return A query requesting the index record matching the key.
042     */
043    T createExactMatchQuery(String indexID, ByteSequence key);
044
045    /**
046     * Returns a query requesting all index records. A backend implementation
047     * may choose to return all or no records as part of the optimization.
048     *
049     * @return A query requesting all index records.
050     */
051    T createMatchAllQuery();
052
053    /**
054     * Returns a query requesting all index records in the specified range.
055     *
056     * @param indexID
057     *          An identifier of the index type.
058     * @param lower
059     *          The lower bound of the range. A 0 length byte array indicates no
060     *          lower bound and the range will start from the smallest key.
061     * @param upper
062     *          The upper bound of the range. A 0 length byte array indicates no
063     *          upper bound and the range will end at the largest key.
064     * @param lowerIncluded
065     *          true if a key exactly matching the lower bound is included in
066     *          the range, false if only keys strictly greater than the lower
067     *          bound are included. This value is ignored if the lower bound is
068     *          not specified.
069     * @param upperIncluded
070     *          true if a key exactly matching the upper bound is included in
071     *          the range, false if only keys strictly less than the upper bound
072     *          are included. This value is ignored if the upper bound is not
073     *          specified.
074     * @return A query requesting all index records in the specified range.
075     */
076    T createRangeMatchQuery(String indexID, ByteSequence lower,
077            ByteSequence upper, boolean lowerIncluded, boolean upperIncluded);
078
079    /**
080     * Returns a query which returns the intersection of a collection of
081     * sub-queries.
082     *
083     * @param subqueries
084     *          A collection of sub-queries.
085     * @return A query which returns the intersection of a collection of
086     *         sub-queries.
087     */
088    T createIntersectionQuery(Collection<T> subqueries);
089
090    /**
091     * Returns a query which combines the results of a collection of
092     * sub-queries.
093     *
094     * @param subqueries
095     *          A collection of sub-queries.
096     * @return A query which combines the results of a collection of
097     *         sub-queries.
098     */
099    T createUnionQuery(Collection<T> subqueries);
100
101    /**
102     * Returns the indexing options for this factory.
103     *
104     * @return the indexing options for this factory.
105     */
106    IndexingOptions getIndexingOptions();
107}