1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions Copyrighted [year] [name of copyright owner]".
13 *
14 * Copyright © 2012 ForgeRock AS. All rights reserved.
15 */
16
17 package org.forgerock.json.resource;
18
19 import org.forgerock.util.promise.Promise;
20
21 /**
22 * The final result of a query request returned after all resources matching the
23 * request have been returned. In addition to indicating that no more resources
24 * are to be returned by the query, the query result will contain page results
25 * state information if result paging has been enabled for the query.
26 */
27 public interface QueryResponse extends Response {
28
29 /**
30 * The name of the field which contains the error in the JSON
31 * representation.
32 */
33 String FIELD_ERROR = "error";
34
35 /**
36 * The name of the field which contains the paged results cookie in the JSON
37 * representation.
38 */
39 String FIELD_PAGED_RESULTS_COOKIE = QueryRequest.FIELD_PAGED_RESULTS_COOKIE;
40
41 /**
42 * The name of the field which contains the policy used for calculating
43 * the total number of paged results in the JSON representation.
44 */
45 String FIELD_TOTAL_PAGED_RESULTS_POLICY = QueryRequest.FIELD_TOTAL_PAGED_RESULTS_POLICY;
46
47 /**
48 * The name of the field which contains the total paged results in the JSON
49 * representation.
50 */
51 String FIELD_TOTAL_PAGED_RESULTS = "totalPagedResults";
52
53 /**
54 * The name of the field which contains the remaining paged results in the
55 * JSON representation.
56 */
57 String FIELD_REMAINING_PAGED_RESULTS = "remainingPagedResults";
58
59 /**
60 * The name of the field which contains the result count in the JSON
61 * representation.
62 */
63 String FIELD_RESULT_COUNT = "resultCount";
64
65 /**
66 * The name of the field which contains the array of matching resources in
67 * the JSON representation.
68 */
69 String FIELD_RESULT = "result";
70
71 /**
72 * The value provided when no count is known or can reasonably be supplied.
73 */
74 int NO_COUNT = -1;
75
76 /**
77 * Returns the policy that was used to calculate the {@literal totalPagedResults}.
78 *
79 * @return The count policy.
80 * @see #getTotalPagedResults()
81 */
82 CountPolicy getTotalPagedResultsPolicy();
83
84 /**
85 * Returns the opaque cookie which can be used for the next cookie-based
86 * paged request. A cookie will only be returned if paged results have
87 * been requested via a non-zero {@code pageSize}. Cookies are only
88 * guaranteed for {@link org.forgerock.util.query.QueryFilter}-based
89 * queries. Implicit sorting may be supported by the resource provider
90 * but it is not required. Given the arbitrary nature of query expressions
91 * (and expression-backed queryIds) there can be no guarantee made of
92 * cookie support for these queries.
93 *
94 * <p>
95 * <em>Note:</em>Cookies have a limited lifespan. They should
96 * not be stored long-term. Cookies should only be used on immediate
97 * subsequent requests or behavior is undefined.
98 * </p>
99 *
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 }