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 Copyrighted [year] [name of copyright owner]".
013 *
014 * Copyright © 2012 ForgeRock AS. All rights reserved.
015 */
016
017package org.forgerock.json.resource;
018
019import org.forgerock.util.promise.Promise;
020
021/**
022 * The final result of a query request returned after all resources matching the
023 * request have been returned. In addition to indicating that no more resources
024 * are to be returned by the query, the query result will contain page results
025 * state information if result paging has been enabled for the query.
026 */
027public interface QueryResponse extends Response {
028
029    /**
030     * The name of the field which contains the error in the JSON
031     * representation.
032     */
033    String FIELD_ERROR = "error";
034
035    /**
036     * The name of the field which contains the paged results cookie in the JSON
037     * representation.
038     */
039    String FIELD_PAGED_RESULTS_COOKIE = QueryRequest.FIELD_PAGED_RESULTS_COOKIE;
040
041    /**
042     * The name of the field which contains the policy used for calculating
043     * the total number of paged results in the JSON representation.
044     */
045    String FIELD_TOTAL_PAGED_RESULTS_POLICY = QueryRequest.FIELD_TOTAL_PAGED_RESULTS_POLICY;
046
047    /**
048     * The name of the field which contains the total paged results in the JSON
049     * representation.
050     */
051    String FIELD_TOTAL_PAGED_RESULTS = "totalPagedResults";
052
053    /**
054     * The name of the field which contains the remaining paged results in the
055     * JSON representation.
056     */
057    String FIELD_REMAINING_PAGED_RESULTS = "remainingPagedResults";
058
059    /**
060     * The name of the field which contains the result count in the JSON
061     * representation.
062     */
063    String FIELD_RESULT_COUNT = "resultCount";
064
065    /**
066     * The name of the field which contains the array of matching resources in
067     * the JSON representation.
068     */
069    String FIELD_RESULT = "result";
070
071    /**
072     * The value provided when no count is known or can reasonably be supplied.
073     */
074    int NO_COUNT = -1;
075
076    /**
077     * Returns the policy that was used to calculate the {@literal totalPagedResults}.
078     *
079     * @return The count policy.
080     * @see #getTotalPagedResults()
081     */
082    CountPolicy getTotalPagedResultsPolicy();
083
084    /**
085     * Returns the opaque cookie which can be used for the next cookie-based
086     * paged request. A cookie will only be returned if paged results have
087     * been requested via a non-zero {@code pageSize}. Cookies are only
088     * guaranteed for {@link org.forgerock.util.query.QueryFilter}-based
089     * queries. Implicit sorting may be supported by the resource provider
090     * but it is not required. Given the arbitrary nature of query expressions
091     * (and expression-backed queryIds) there can be no guarantee made of
092     * cookie support for these queries.
093     *
094     * <p>
095     *     <em>Note:</em>Cookies have a limited lifespan. They should
096     *     not be stored long-term. Cookies should only be used on immediate
097     *     subsequent requests or behavior is undefined.
098     * </p>
099     *
100     * @return The opaque cookie which should be used with the next cookie-based paged
101     *         results query request, or {@code null} if paged results were not
102     *         requested, there are no more pages to be returned, or cookies are not
103     *         supported for this query.
104     *
105     * @see QueryRequest#getPagedResultsCookie()
106     * @see QueryRequest#setPagedResultsCookie(String)
107     * @see QueryRequest#addSortKey(SortKey...)
108     * @see QueryRequest#addSortKey(String...)
109     */
110    String getPagedResultsCookie();
111
112    /**
113     * Returns the total number of paged results in adherence with
114     * the {@link QueryRequest#getTotalPagedResultsPolicy()} in the request
115     * or {@link #NO_COUNT} if paged results were not requested, the count
116     * policy is {@code NONE}, or the total number of paged
117     * results is unknown.
118     *
119     * @return A count of the total number of paged results to be
120     *         returned in subsequent paged results query requests, or
121     *         {@link #NO_COUNT} if paged results were not requested, or if the total
122     *         number of paged results is unknown.
123     */
124    int getTotalPagedResults();
125
126    /**
127     * Returns an estimate of the total number of remaining results to be
128     * returned in subsequent paged results query requests.
129     *
130     * @return An estimate of the total number of remaining results to be
131     *         returned in subsequent paged results query requests, or
132     *         {@code -1} if paged results were not requested, or if the total
133     *         number of remaining results is unknown.
134     */
135    int getRemainingPagedResults();
136
137    /**
138     * Return this response as a result Promise.
139     *
140     * @return A Promise whose result is this QueryResponse object.
141     */
142    Promise<QueryResponse, ResourceException> asPromise();
143}