/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions Copyright [year] [name of copyright owner]".
 *
 * Copyright 2012-2015 ForgeRock AS.
 */

package org.forgerock.json.resource;

import java.util.List;
import java.util.Map;

import org.forgerock.http.routing.Version;
import org.forgerock.json.JsonPointer;
import org.forgerock.json.JsonValue;
import org.forgerock.util.i18n.PreferredLocales;
import org.forgerock.util.query.QueryFilter;

/**
 * A request to search for all JSON resources matching a user specified set of criteria.
 * <p>
 * There are four types of query request: <ul> <li>default query: when neither a filter, expression or query ID are
 * specified all resources will be returned <li>query by filter: returns all resources which match the {@link
 * QueryFilters} specified using {@link #setQueryFilter(QueryFilter)} <li>query by ID: returns all resources which match
 * the named prepared query specified using {@link #setQueryId(String)} <li>query by expression: returns all resources
 * which match a native expression specified using {@link #setQueryExpression(String)}. Note that this type of query
 * should only be used in very rare cases since it introduces a tight coupling between the application and the
 * underlying JSON resource. In addition, applications should take care to prevent users from directly accessing this
 * form of query for security reasons. </ul>
 * <p>
 * In addition to the above mentioned query types queries may also be paged when a page size is found via {@link
 * #getPageSize()}. Paged requests should be used in most cases when an unknown number of query results will be
 * returned.
 */
public interface QueryRequest extends Request {
    /**
     * The name of the field which contains the paged results cookie in the JSON representation.
     */
    String FIELD_PAGED_RESULTS_COOKIE = "pagedResultsCookie";
    /**
     * The name of the field which contains the paged results offset in the JSON representation.
     */
    String FIELD_PAGED_RESULTS_OFFSET = "pagedResultsOffset";
    /**
     * The name of the field which contains the page size in the JSON representation.
     */
    String FIELD_PAGE_SIZE = "pageSize";
    /**
     * The name of the field which contains the query expression in the JSON representation.
     */
    String FIELD_QUERY_EXPRESSION = "queryExpression";
    /**
     * The name of the field which contains the query filter in the JSON representation.
     */
    String FIELD_QUERY_FILTER = "queryFilter";
    /**
     * The name of the field which contains the query ID in the JSON representation.
     */
    String FIELD_QUERY_ID = "queryId";
    /**
     * The name of the field which contains the sort keys in the JSON representation.
     */
    String FIELD_SORT_KEYS = "sortKeys";
    /**
     * The name of the field which contains the policy used for calculating the total number of paged results.
     */
    String FIELD_TOTAL_PAGED_RESULTS_POLICY = "totalPagedResultsPolicy";


    @Override
    <R, P> R accept(final RequestVisitor<R, P> v, final P p);


    @Override
    QueryRequest addField(JsonPointer... fields);


    @Override
    QueryRequest addField(String... fields);

    /**
     * Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.
     *
     * @param keys
     *         The sort keys which will be used for ordering the JSON resources returned by this query request.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the sort keys.
     */
    QueryRequest addSortKey(SortKey... keys);

    /**
     * Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.
     *
     * @param keys
     *         The sort keys which will be used for ordering the JSON resources returned by this query request.
     * @return This query request.
     * @throws IllegalArgumentException
     *         If one or more of the provided sort keys could not be parsed.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the sort keys.
     */
    QueryRequest addSortKey(String... keys);


    @Override
    String getAdditionalParameter(String name);


    @Override
    Map<String, String> getAdditionalParameters();


    @Override
    List<JsonPointer> getFields();

    /**
     * Returns the requested page results page size or {@code 0} if paged results are not required. For all paged result
     * requests other than the initial request, a cookie should be provided with the query request. See {@link
     * #getPagedResultsCookie()} for more information.
     *
     * @return The requested page results page size or {@code 0} if paged results are not required.
     * @see #getPagedResultsCookie()
     * @see #getPagedResultsOffset()
     */
    int getPageSize();

    /**
     * Returns the opaque cookie which is used by the resource provider to track its position in the set of query
     * results. Paged results will be enabled if and only if the page size is non-zero.
     * <p>
     * The cookie must be {@code null} in the initial query request sent by the client. For subsequent query requests
     * the client must include the cookie returned with the previous query result, until the resource provider returns a
     * {@code null} cookie indicating that the final page of results has been returned.
     * <p>
     * <em>Note:</em> Cookies and offsets are mutually exclusive.
     *
     * @return The opaque cookie which is used by the resource provider to track its position in the set of query
     * results, or {@code null} if paged results are not requested (when the page size is 0) or if the first page of
     * results is being requested (when the page size is non-zero).
     * @see #getPageSize()
     * @see #getPagedResultsOffset()
     */
    String getPagedResultsCookie();

    /**
     * Returns the zero-based index of the first resource which should be included in the query results. An offset of 0
     * (default) will return the first resource in the collection. An offset of {@code 1} will return the second, and so
     * on ...
     * <p>
     * <em>Note:</em> Offsets and cookies are mutually exclusive. When a cookie is supplied only the default {@code 0}
     * offset is supported.
     * <p>
     * Offset must be a zero-based integer denoting the number of records to skip. This is very similar to the
     * <code>LIMIT</code> and <code>SKIP</code> clauses in SQL databases.
     *
     * @return The zero-based index within the result set of the first result which should be returned.
     * @see #getPageSize()
     * @see #getPagedResultsCookie()
     */
    int getPagedResultsOffset();


    @Override
    PreferredLocales getPreferredLocales();

    /**
     * Returns the native query expression which will be used for processing the query request. An example of a native
     * query expression is a SQL statement.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @return The native query expression which will be used for processing the query request, or {@code null} if
     * another type of query is to be performed.
     * @see QueryRequest#getQueryFilter()
     * @see QueryRequest#getQueryId()
     */
    String getQueryExpression();

    /**
     * Returns the query filter which will be used for selecting which JSON resources will be returned.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @return The query filter which will be used for selecting which JSON resources will be returned, or {@code null}
     * if another type of query is to be performed.
     * @see QueryRequest#getQueryExpression()
     * @see QueryRequest#getQueryId()
     */
    QueryFilter<JsonPointer> getQueryFilter();

    /**
     * Returns the query identifier for pre-defined queries.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @return The query identifier for pre-defined queries, or {@code null} if a pre-defined query is not to be used,
     * or {@code null} if another type of query is to be performed.
     * @see QueryRequest#getQueryExpression()
     * @see QueryRequest#getQueryFilter()
     */
    String getQueryId();


    @Override
    RequestType getRequestType();

    @Override
    String getResourcePath();

    @Override
    ResourcePath getResourcePathObject();

    @Override
    Version getResourceVersion();

    /**
     * Returns the sort keys which should be used for ordering the JSON resources returned by this query request. The
     * returned list may be modified if permitted by this query request.
     *
     * @return The sort keys which should be used for ordering the JSON resources returned by this query request (never
     * {@code null}).
     */
    List<SortKey> getSortKeys();

    /**
     * Returns the {@link CountPolicy} used to calculate {@link QueryResponse#getTotalPagedResults()}.
     *
     * @return The count policy.
     * @see QueryResponse#getTotalPagedResults()
     */
    CountPolicy getTotalPagedResultsPolicy();

    @Override
    QueryRequest setAdditionalParameter(String name, String value) throws BadRequestException;

    /**
     * Sets the requested page results page size or {@code 0} if paged results are not required. For all paged result
     * requests other than the initial request, a cookie should be provided with the query request. See {@link
     * #setPagedResultsCookie(String)} for more information.
     *
     * @param size
     *         The requested page results page size or {@code 0} if paged results are not required.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the page size.
     * @see #getPagedResultsCookie()
     * @see #setPagedResultsOffset(int)
     */
    QueryRequest setPageSize(int size);

    /**
     * Sets the opaque cookie which is used by the resource provider to track its position in the set of query results.
     * Paged results will be enabled if and only if the page size is non-zero.
     * <p>
     * The cookie must be {@code null} in the initial query request sent by the client. For subsequent query requests
     * the client must include the cookie returned with the previous query result, until the resource provider returns a
     * {@code null} cookie indicating that the final page of results has been returned.
     * <p>
     * When subsequent paged requests are being made no query parameters may be altered; doing so will result in
     * undefined behavior. The only parameter that may be changed during paged requests is the page size.
     *
     * @param cookie
     *         The opaque cookie which is used by the resource provider to track its position in the set of query
     *         results.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the paged results cookie.
     * @see #setPageSize(int)
     * @see #addSortKey(SortKey...)
     * @see #addSortKey(String...)
     */
    QueryRequest setPagedResultsCookie(String cookie);

    /**
     * Sets the zero-based index of the first resource which should be included in the query results. An offset of 0
     * (default) will return the first resource in the collection. An offset of {@code 1} will return the second, and so
     * on ...
     * <p>
     * <em>Note:</em> Offsets and cookies are mutually exclusive. When a cookie is supplied only the default {@code 0}
     * offset is supported.
     * <p>
     * Offset must be a zero-based integer denoting the number of records to skip. This is very similar to the
     * <code>LIMIT</code> and <code>SKIP</code> clauses in SQL databases.
     *
     * @param offset
     *         The index within the result set of the first result which should be returned.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the paged results offset.
     * @see #setPageSize(int)
     * @see #setPagedResultsCookie(String)
     */
    QueryRequest setPagedResultsOffset(int offset);

    @Override
    QueryRequest setPreferredLocales(PreferredLocales preferredLocales);

    /**
     * Sets the native query expression which will be used for processing the query request. An example of a native
     * query expression is a SQL statement.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @param expression
     *         The native query expression which will be used for processing the query request, or {@code null} if
     *         another type of query is to be performed.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the query identifier.
     * @see QueryRequest#setQueryFilter(QueryFilter)
     * @see QueryRequest#setQueryId(String)
     */
    QueryRequest setQueryExpression(String expression);

    /**
     * Sets the query filter which will be used for selecting which JSON resources will be returned.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @param filter
     *         The query filter which will be used for selecting which JSON resources will be returned, or {@code null}
     *         if another type of query is to be performed.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the query filter.
     * @see QueryRequest#setQueryExpression(String)
     * @see QueryRequest#setQueryId(String)
     */
    QueryRequest setQueryFilter(QueryFilter<JsonPointer> filter);

    /**
     * Sets the query identifier for pre-defined queries.
     * <p>
     * <b>NOTE:</b> the native query expression, query filter, and query ID parameters are mutually exclusive and only
     * one of them may be specified.
     *
     * @param id
     *         The query identifier for pre-defined queries, or {@code null} if another type of query is to be
     *         performed.
     * @return This query request.
     * @throws UnsupportedOperationException
     *         If this query request does not permit changes to the query identifier.
     * @see QueryRequest#setQueryExpression(String)
     * @see QueryRequest#setQueryFilter(QueryFilter)
     */
    QueryRequest setQueryId(String id);

    @Override
    QueryRequest setResourcePath(ResourcePath path);

    @Override
    QueryRequest setResourcePath(String path);

    @Override
    QueryRequest setResourceVersion(Version resourceVersion);

    /**
     * Sets the policy for calculating the total number of paged results. If no count policy is supplied or paged
     * results are not requested a default of {@link CountPolicy#NONE} will be used. This will result in no count being
     * performed and no overhead incurred.
     *
     * @param policy
     *         The policy used to calculate total paged results
     * @return This query request.
     * @see QueryResponse#getTotalPagedResultsPolicy()
     * @see QueryResponse#getTotalPagedResults()
     */
    QueryRequest setTotalPagedResultsPolicy(CountPolicy policy);

    @Override
    JsonValue toJsonValue();
}