001 /*
002 * Copyright 2012 UnboundID Corp.
003 *
004 * This program is free software; you can redistribute it and/or modify
005 * it under the terms of the GNU General Public License (GPLv2 only)
006 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
007 * as published by the Free Software Foundation.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012 * GNU General Public License for more details.
013 *
014 * You should have received a copy of the GNU General Public License
015 * along with this program; if not, see <http://www.gnu.org/licenses>.
016 */
017
018 package com.unboundid.scim.sdk;
019
020 import com.unboundid.scim.data.BaseResource;
021
022
023
024 /**
025 * This class represents an individual operation within a bulk operation
026 * request or response. The fields are defined as follows, in the order that
027 * they must be encoded when XML is the content type:
028 *
029 * <pre>
030 * Each operation corresponds to a single HTTP request against a Resource
031 * endpoint. REQUIRED.
032 *
033 * method
034 * The HTTP method of the current operation. Possible values are POST,
035 * PUT, PATCH or DELETE. REQUIRED.
036 * bulkId
037 * The transient identifier of a newly created Resource, unique within
038 * a bulk request and created by the Consumer. The bulkId serves as a
039 * surrogate Resource id enabling Consumers to uniquely identify newly
040 * created Resources in the Response and cross reference new Resources
041 * in and across operations within a bulk request. REQUIRED when method
042 * is POST.
043 * version
044 * The current Resource version. Version is REQUIRED if the Service
045 * Provider supports ETags and the method is PUT, DELETE, or PATCH.
046 * path
047 * The Resource's relative path. If the method is POST the value must
048 * specify a Resource type endpoint; e.g., /Users or /Groups whereas
049 * all other method values must specify the path to a specific Resource;
050 * e.g., /Users/2819c223-7f76-453a-919d-413861904646.
051 * REQUIRED in a request.
052 * location
053 * The Resource endpoint URL. REQUIRED in a response, except in the
054 * event of a POST failure.
055 * data
056 * The Resource data as it would appear for a single POST, PUT or PATCH
057 * Resource operation. REQUIRED in a request when method is POST, PUT
058 * and PATCH.
059 * status
060 * A complex type that contains information about the success or failure
061 * of one operation within the bulk job. REQUIRED in a response.
062 *
063 * code
064 * The HTTP response code that would have been returned if a single
065 * HTTP request would have been used. REQUIRED.
066 * description
067 * A human readable error message. REQUIRED when an error occurred.
068 *
069 * </pre>
070 */
071 public class BulkOperation
072 {
073 /**
074 * The different methods that are supported within bulk operations.
075 */
076 public enum Method
077 {
078 /**
079 * The POST method, used to create a new SCIM resource.
080 */
081 POST,
082
083 /**
084 * The PUT method, used to replace the entire contents of a SCIM resource.
085 */
086 PUT,
087
088 /**
089 * The PATCH method, used to modify, add or delete attributes of a SCIM
090 * resource.
091 */
092 PATCH,
093
094 /**
095 * The DELETE method, used to delete a SCIM resource.
096 */
097 DELETE
098 }
099
100
101
102 /**
103 * The HTTP method of the operation. Possible values are POST, PUT, PATCH or
104 * DELETE.
105 */
106 private final Method method;
107
108 /**
109 * The bulk operation identifier, required when the method is POST.
110 */
111 private final String bulkId;
112
113 /**
114 * The current resource version, or {@code null} if not provided.
115 */
116 private final String version;
117
118 /**
119 * The relative path of the resource, required in a request.
120 */
121 private final String path;
122
123 /**
124 * The resource endpoint URL, or {code null} if this is a request, or if this
125 * is the response to a failed POST operation.
126 */
127 private final String location;
128
129 /**
130 * The resource data as it would appear for a single POST, PUT or PATCH
131 * operation. This field is required in a request when method is POST, PUT
132 * and PATCH.
133 */
134 private final BaseResource data;
135
136 /**
137 * Information about the success or failure of the operation.
138 */
139 private final Status status;
140
141
142 /**
143 * Construct a new BulkOperation object.
144 *
145 * @param method The HTTP method of the operation. Possible values are
146 * POST, PUT, PATCH or DELETE.
147 * @param bulkId The bulk operation identifier, required when the method
148 * is POST.
149 * @param version The current resource version, or {@code null} if not
150 * provided.
151 * @param path The relative path of the resource, or {@code null} if
152 * this is a response.
153 * @param location The resource endpoint URL, or {code null} if this is a
154 * request, or if this is the response to a failed POST
155 * operation.
156 * @param data The resource data as it would appear for a single POST,
157 * PUT or PATCH operation.
158 * @param status Information about the success or failure of the
159 * operation, or {@code null} if this is a request.
160 */
161 public BulkOperation(final Method method,
162 final String bulkId,
163 final String version,
164 final String path,
165 final String location,
166 final BaseResource data,
167 final Status status)
168 {
169 this.method = method;
170 this.bulkId = bulkId;
171 this.version = version;
172 this.path = path;
173 this.location = location;
174 this.data = data;
175 this.status = status;
176 }
177
178
179
180 /**
181 * Create a new operation for a bulk request.
182 *
183 * @param method The HTTP method of the operation. Possible values are
184 * POST, PUT, PATCH or DELETE.
185 * @param bulkId The bulk operation identifier, required when the method
186 * is POST.
187 * @param version The current resource version, or {@code null} if not
188 * provided.
189 * @param path The relative path of the resource, or {@code null} if
190 * this is a response.
191 * @param data The resource data as it would appear for a single POST,
192 * PUT or PATCH operation.
193 *
194 * @return The new bulk request operation.
195 */
196 public static BulkOperation createRequest(final Method method,
197 final String bulkId,
198 final String version,
199 final String path,
200 final BaseResource data)
201 {
202 return new BulkOperation(method, bulkId, version, path,
203 null, data, null);
204 }
205
206
207
208 /**
209 * Retrieve HTTP method of the operation. Possible values are POST, PUT,
210 * PATCH or DELETE.
211 * @return The HTTP method of the operation. Possible values are POST, PUT,
212 * PATCH or DELETE.
213 */
214 public Method getMethod()
215 {
216 return method;
217 }
218
219
220
221 /**
222 * Retrieve the bulk operation identifier, required when the method is POST.
223 * @return The bulk operation identifier, required when the method is POST.
224 */
225 public String getBulkId()
226 {
227 return bulkId;
228 }
229
230
231
232 /**
233 * Retrieve the The current resource version, or {@code null} if not provided.
234 * @return The The current resource version, or {@code null} if not provided.
235 */
236 public String getVersion()
237 {
238 return version;
239 }
240
241
242
243 /**
244 * Retrieve the The relative path of the resource, or {@code null} if this
245 * is a response.
246 * @return The The relative path of the resource, or {@code null} if this
247 * is a response.
248 */
249 public String getPath()
250 {
251 return path;
252 }
253
254
255
256 /**
257 * Retrieve the resource endpoint URL, or {@code null} if this is a request,
258 * or if this is the response to a failed POST operation.
259 * @return The resource endpoint URL, or {@code null} if this is a request,
260 * or if this is the response to a failed POST operation.
261 */
262 public String getLocation()
263 {
264 return location;
265 }
266
267
268
269 /**
270 * Retrieve the resource data as it would appear for a single POST, PUT or
271 * PATCH operation.
272 * @return The resource data as it would appear for a single POST, PUT or
273 * PATCH operation.
274 */
275 public BaseResource getData()
276 {
277 return data;
278 }
279
280
281
282 /**
283 * Retrieve information about the success or failure of the operation, or
284 * {@code null} if this is a request.
285 * @return Information about the success or failure of the operation, or
286 * {@code null} if this is a request.
287 */
288 public Status getStatus()
289 {
290 return status;
291 }
292
293
294
295 /**
296 * {@inheritDoc}
297 */
298 @Override
299 public String toString()
300 {
301 final StringBuilder sb = new StringBuilder();
302 sb.append("BulkOperation");
303 sb.append("{method='").append(method).append('\'');
304 sb.append(", bulkId='").append(bulkId).append('\'');
305 sb.append(", version='").append(version).append('\'');
306 sb.append(", path='").append(path).append('\'');
307 sb.append(", location='").append(location).append('\'');
308 sb.append(", data=").append(data);
309 sb.append(", status=").append(status);
310 sb.append('}');
311 return sb.toString();
312 }
313 }