001/*
002 * Copyright 2012-2016 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
018package com.unboundid.scim.sdk;
019
020import 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 */
071public 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, null, data, null);
203  }
204
205
206
207  /**
208   * Create a new operation for a bulk response.
209   *
210   * @param method      The HTTP method of the operation. Possible values are
211   *                    POST, PUT, PATCH or DELETE.
212   * @param bulkId      The bulk operation identifier, required when the method
213   *                    is POST.
214   * @param version     The resource version, or {@code null} if version is
215   *                    not available or not supported.
216   * @param location    The resource endpoint URL, or {@code null} if this is
217   *                    the response to a DELETE operation or a failed POST
218   *                    operation.
219   * @param status      Information about the success or failure of the
220   *                    operation.
221   *
222   * @return  The new bulk request operation.
223   */
224  public static BulkOperation createResponse(final Method method,
225                                             final String bulkId,
226                                             final String version,
227                                             final String location,
228                                             final Status status)
229  {
230    return new BulkOperation(method, bulkId, version, null, location, null,
231                             status);
232  }
233
234
235
236  /**
237   * Retrieve HTTP method of the operation. Possible values are POST, PUT,
238   * PATCH or DELETE.
239   * @return  The HTTP method of the operation. Possible values are POST, PUT,
240   *          PATCH or DELETE.
241   */
242  public Method getMethod()
243  {
244    return method;
245  }
246
247
248
249  /**
250   * Retrieve the bulk operation identifier, required when the method is POST.
251   * @return  The bulk operation identifier, required when the method is POST.
252   */
253  public String getBulkId()
254  {
255    return bulkId;
256  }
257
258
259
260  /**
261   * Retrieve the The current resource version, or {@code null} if not provided.
262   * @return  The The current resource version, or {@code null} if not provided.
263   */
264  public String getVersion()
265  {
266    return version;
267  }
268
269
270
271  /**
272   * Retrieve the The relative path of the resource, or {@code null} if this
273   * is a response.
274   * @return  The The relative path of the resource, or {@code null} if this
275   *          is a response.
276   */
277  public String getPath()
278  {
279    return path;
280  }
281
282
283
284  /**
285   * Retrieve the resource endpoint URL, or {@code null} if this is a request,
286   * or if this is the response to a failed POST operation.
287   * @return  The resource endpoint URL, or {@code null} if this is a request,
288   *          or if this is the response to a failed POST operation.
289   */
290  public String getLocation()
291  {
292    return location;
293  }
294
295
296
297  /**
298   * Retrieve the resource data as it would appear for a single POST, PUT or
299   * PATCH operation.
300   * @return  The resource data as it would appear for a single POST, PUT or
301   *          PATCH operation.
302   */
303  public BaseResource getData()
304  {
305    return data;
306  }
307
308
309
310  /**
311   * Retrieve information about the success or failure of the operation, or
312   * {@code null} if this is a request.
313   * @return  Information about the success or failure of the operation, or
314   *          {@code null} if this is a request.
315   */
316  public Status getStatus()
317  {
318    return status;
319  }
320
321
322
323  /**
324   * {@inheritDoc}
325   */
326  @Override
327  public String toString()
328  {
329    final StringBuilder sb = new StringBuilder();
330    sb.append("BulkOperation");
331    sb.append("{method='").append(method).append('\'');
332    sb.append(", bulkId='").append(bulkId).append('\'');
333    sb.append(", version='").append(version).append('\'');
334    sb.append(", path='").append(path).append('\'');
335    sb.append(", location='").append(location).append('\'');
336    sb.append(", data=").append(data);
337    sb.append(", status=").append(status);
338    sb.append('}');
339    return sb.toString();
340  }
341}