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