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 create a new JSON resource.
29 */
30 public interface CreateRequest extends Request {
31
32 /**
33 * The name of the action which is reserved for performing "create" operations.
34 */
35 String ACTION_ID_CREATE = CreateRequest.ACTION_ID_CREATE;
36
37 /**
38 * The name of the field which contains the resource content in the JSON representation.
39 */
40 String FIELD_CONTENT = "content";
41
42 /**
43 * The name of the field which contains the new resource ID in the JSON representation.
44 */
45 String FIELD_NEW_RESOURCE_ID = "newResourceId";
46
47
48 @Override
49 <R, P> R accept(final RequestVisitor<R, P> v, final P p);
50
51
52 @Override
53 CreateRequest addField(JsonPointer... fields);
54
55
56 @Override
57 CreateRequest addField(String... fields);
58
59
60 @Override
61 String getAdditionalParameter(String name);
62
63
64 @Override
65 Map<String, String> getAdditionalParameters();
66
67 /**
68 * Returns the content of the JSON resource to be created.
69 *
70 * @return The content of the JSON resource to be created.
71 */
72 JsonValue getContent();
73
74
75 @Override
76 List<JsonPointer> getFields();
77
78 /**
79 * Returns the client provided ID of the resource to be created. The new resource ID will be appended to the
80 * resource path in order to obtain the full path of the new resource.
81 * <p>
82 * The new resource ID is optional and should be used in cases where the client wishes to determine the path of the
83 * resource to be created. If the new resource ID is not provided then the server will be responsible for generating
84 * the ID of the new resource.
85 *
86 * @return The client provided ID of the resource to be created, or {@code null} if the server should be responsible
87 * for generating the resource ID.
88 * @see #getResourcePath()
89 */
90 String getNewResourceId();
91
92
93 @Override
94 PreferredLocales getPreferredLocales();
95
96
97 @Override
98 RequestType getRequestType();
99
100 /**
101 * Returns the path of the JSON resource container beneath which the new resource should be created.
102 * <p>
103 * The path of the newly created resource will be the concatenation of the resource path and either the client
104 * provided resource ID, if provided, or a server generated resource ID.
105 *
106 * @return The path of the JSON resource container beneath which the new resource should be created.
107 * @see #getNewResourceId()
108 */
109 @Override
110 String getResourcePath();
111
112
113 @Override
114 ResourcePath getResourcePathObject();
115
116
117 @Override
118 Version getResourceVersion();
119
120
121 @Override
122 CreateRequest setAdditionalParameter(String name, String value) throws BadRequestException;
123
124 /**
125 * Sets the content of the JSON resource to be created.
126 *
127 * @param content
128 * The content of the JSON resource to be created.
129 * @return This create request.
130 * @throws UnsupportedOperationException
131 * If this create request does not permit changes to the content.
132 */
133 CreateRequest setContent(JsonValue content);
134
135 /**
136 * Sets the client provided ID of the resource to be created. The new resource ID will be appended to the resource
137 * path in order to obtain the full path of the new resource.
138 * <p>
139 * The new resource ID is optional and should be used in cases where the client wishes to determine the path of the
140 * resource to be created. If the new resource ID is not provided then the server will be responsible for generating
141 * the ID of the new resource.
142 *
143 * @param id
144 * The client provided ID of the resource to be created, or {@code null} if the server should be responsible
145 * for generating the resource ID.
146 * @return This create request.
147 * @throws UnsupportedOperationException
148 * If this create request does not permit changes to the new resource ID.
149 * @see #setResourcePath(String)
150 */
151 CreateRequest setNewResourceId(String id);
152
153
154 @Override
155 CreateRequest setPreferredLocales(PreferredLocales preferredLocales);
156
157 /**
158 * Sets the path of the JSON resource container beneath which the new resource should be created.
159 * <p>
160 * The path of the newly created resource will be the concatenation of the resource path and either the client
161 * provided resource ID, if provided, or a server generated resource ID.
162 *
163 * @param path
164 * The path of the JSON resource container beneath which the new resource should be created.
165 * @return This create request.
166 * @throws UnsupportedOperationException
167 * If this create request does not permit changes to the resource path.
168 * @see #setNewResourceId(String)
169 */
170 @Override
171 CreateRequest setResourcePath(String path);
172
173
174 @Override
175 CreateRequest setResourcePath(ResourcePath path);
176
177
178 @Override
179 CreateRequest setResourceVersion(Version resourceVersion);
180
181
182 @Override
183 JsonValue toJsonValue();
184 }