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 Copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2012-2015 ForgeRock AS.
15 */
16
17 package org.forgerock.json.resource;
18
19 import java.util.List;
20
21 import org.forgerock.json.JsonPointer;
22 import org.forgerock.json.JsonValue;
23 import org.forgerock.util.promise.Promise;
24
25 /**
26 * A resource, comprising of a resource ID, a revision (etag), and its JSON
27 * content.
28 */
29 public interface ResourceResponse extends Response {
30
31 /**
32 * The name of the field which contains the resource ID in the JSON
33 * representation.
34 * <p>
35 * <b>Note:</b> when encoding the resource ID as part of a resource's
36 * content the field name {@link #FIELD_CONTENT_ID} should be used.
37 */
38 String FIELD_ID = "id";
39
40 /**
41 * The name of the field which contains the resource version in the JSON
42 * representation.
43 * <p>
44 * <b>Note:</b> when encoding the resource revision as part of a resource's
45 * content the field name {@link #FIELD_CONTENT_REVISION} should be used.
46 */
47 String FIELD_REVISION = "revision";
48
49 /**
50 * The name of the field in the resource content which contains the resource
51 * ID. This field is semantically equivalent to {@link #FIELD_ID} and is
52 * intended for use in cases where a commons REST API wishes to expose the
53 * resource ID as part of the resource content.
54 */
55 String FIELD_CONTENT_ID = "_id";
56
57 /**
58 * The name of the field in the resource content which contains the resource
59 * revision. This field is semantically equivalent to
60 * {@link #FIELD_REVISION} and is intended for use in cases where a commons
61 * REST API wishes to expose the resource revision as part of the resource
62 * content.
63 */
64 String FIELD_CONTENT_REVISION = "_rev";
65
66 /**
67 * The name of the field which contains the resource content in the JSON
68 * representation.
69 */
70 String FIELD_CONTENT = "content";
71
72 /**
73 * Returns the JSON content of this resource.
74 *
75 * @return The JSON content of this resource.
76 */
77 JsonValue getContent();
78
79 /**
80 * Returns the ID of this resource, if applicable.
81 *
82 * @return The ID of this resource, or {@code null} if this resource does
83 * not have an ID.
84 */
85 String getId();
86
87 /**
88 * Returns the revision of this resource, if known.
89 *
90 * @return The revision of this resource, or {@code null} if the version is
91 * not known.
92 */
93 String getRevision();
94
95 /**
96 * Returns the list of fields which should be included in this JSON resource
97 * after field filtering has occurred. This list will override the list of
98 * fields that is included in the request. An empty list indicates that the
99 * original list of fields in the request should be used for filtering the
100 * response.
101 *
102 * @return The list of fields which should be included in this JSON resource
103 * after field filtering has occurred.
104 */
105 List<JsonPointer> getFields();
106
107 /**
108 * Returns true if any fields have been added, indicating that the list of
109 * fields in this response should be included in this JSON resource after
110 * field filtering has occurred, otherwise returns false indicating that the
111 * original list of fields in the request should be used for filtering the
112 * response.
113 *
114 * @return true if any fields have been added, false otherwise.
115 */
116 boolean hasFields();
117
118 /**
119 * Adds a field to the list of fields which should be included in this JSON
120 * resource after field filtering has occurred. This list will override the
121 * list of fields that is included in the request.
122 *
123 * @param fields a {@link JsonPointer} representing the field to add.
124 */
125 void addField(JsonPointer... fields);
126
127 /**
128 * Return this response as a result Promise.
129 *
130 * @return A Promise whose result is this ResourceResponse object.
131 */
132 Promise<ResourceResponse, ResourceException> asPromise();
133
134 /**
135 * Returns {@code true} if the provided object is a resource having the same
136 * resource ID and revision as this resource.
137 * <p>
138 * {@inheritDoc}
139 */
140 @Override
141 boolean equals(final Object obj);
142
143 /**
144 * Returns the hash code for this resource. Two resources are guaranteed to
145 * have the same hash code if they share the same resource ID and revision.
146 * <p>
147 * {@inheritDoc}
148 */
149 @Override
150 int hashCode();
151 }