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 import java.util.Map;
21
22 import org.forgerock.http.routing.Version;
23 import org.forgerock.json.JsonPointer;
24 import org.forgerock.json.JsonValue;
25 import org.forgerock.util.i18n.PreferredLocales;
26
27 /**
28 * A request to update a JSON resource by applying a set of changes to its existing content. See the documentation for
29 * {@link PatchOperation} for more details regarding the various types of patch operation, and their semantics.
30 */
31 public interface PatchRequest extends Request {
32
33 /**
34 * The name of the field which contains the patch content in the JSON representation.
35 */
36 String FIELD_PATCH = "patch";
37
38 /**
39 * The name of the field which contains the patch operations in the JSON representation.
40 */
41 String FIELD_PATCH_OPERATIONS = "patchOperations";
42
43 /**
44 * The name of the field which contains the resource version in the JSON representation.
45 */
46 String FIELD_REVISION = "revision";
47
48
49 @Override
50 <R, P> R accept(final RequestVisitor<R, P> v, final P p);
51
52
53 @Override
54 PatchRequest addField(JsonPointer... fields);
55
56
57 @Override
58 PatchRequest addField(String... fields);
59
60 /**
61 * Adds one or more patch operations which should be performed against the targeted resource.
62 *
63 * @param operations
64 * One or more patch operations which should be performed against the targeted resource.
65 * @return This patch request.
66 * @throws UnsupportedOperationException
67 * If this patch request does not permit changes to the patch operations.
68 */
69 PatchRequest addPatchOperation(PatchOperation... operations);
70
71 /**
72 * Adds a single patch operation which should be performed against the targeted resource.
73 *
74 * @param operation
75 * The type of patch operation to be performed.
76 * @param field
77 * The field targeted by the patch operation.
78 * @param value
79 * The possibly {@code null} value for the patch operation.
80 * @return This patch request.
81 * @throws UnsupportedOperationException
82 * If this patch request does not permit changes to the patch operations.
83 */
84 PatchRequest addPatchOperation(String operation, String field, JsonValue value);
85
86
87 @Override
88 String getAdditionalParameter(String name);
89
90
91 @Override
92 Map<String, String> getAdditionalParameters();
93
94
95 @Override
96 List<JsonPointer> getFields();
97
98 /**
99 * Returns the list of patch operations which should be performed against the targeted resource.
100 *
101 * @return The list of patch operations which should be performed against the targeted resource (never null).
102 */
103 List<PatchOperation> getPatchOperations();
104
105
106 @Override
107 PreferredLocales getPreferredLocales();
108
109
110 @Override
111 RequestType getRequestType();
112
113 @Override
114 String getResourcePath();
115
116 @Override
117 ResourcePath getResourcePathObject();
118
119 @Override
120 Version getResourceVersion();
121
122 /**
123 * Returns the expected version information associated with the JSON resource to be patched. Version information can
124 * be used in order to implement multi-version concurrency control (MVCC).
125 * <p>
126 * The returned version information may be {@code null} indicating that the client does not care if the resource has
127 * been modified concurrently. If the version information is non-{@code null}, and it does not match the current
128 * version of the targeted JSON resource, then the patch request will be rejected by the provider.
129 *
130 * @return The expected version information associated with the JSON resource to be patched.
131 */
132 String getRevision();
133
134 @Override
135 PatchRequest setAdditionalParameter(String name, String value) throws BadRequestException;
136
137 @Override
138 PatchRequest setPreferredLocales(PreferredLocales preferredLocales);
139
140 @Override
141 PatchRequest setResourcePath(ResourcePath path);
142
143 @Override
144 PatchRequest setResourcePath(String path);
145
146 @Override
147 PatchRequest setResourceVersion(Version resourceVersion);
148
149 /**
150 * Sets the expected version information associated with the JSON resource to be patched. Version information can be
151 * used in order to implement multi-version concurrency control (MVCC).
152 * <p>
153 * The provided version information may be {@code null} indicating that the client does not care if the resource has
154 * been modified concurrently. If the version information is non-{@code null}, and it does not match the current
155 * version of the targeted JSON resource, then the patch request will be rejected by the provider.
156 *
157 * @param version
158 * The expected version information associated with the JSON resource to be patched.
159 * @return This patch request.
160 * @throws UnsupportedOperationException
161 * If this patch request does not permit changes to the version information.
162 */
163 PatchRequest setRevision(String version);
164
165 @Override
166 JsonValue toJsonValue();
167 }