Synopsis:
Creates a new queue object at the specified URI. PUT <root URI>/<ContainerName>/<QueueName>
• <root URI> is the path to the CDMI cloud.
• <ContainerName> is zero or more intermediate containers that already exist. • <QueueName> is the name specified for the queue object to be created. Once created, the object can also be accessed at <root URI>/cdmi_objectid/<objectID>.
Delayed Completion of Create:
On a create operation for a queue, the server may return a response of "202 Accepted". In this case, the queue is in the process of being created. This response is particularly useful for long-running operations, for instance, for copying a large data object from a source URI. Such a response has the following implications:
• The server returns an object identifier along with the "202 Accepted". With "202 Accepted", the server implies that the following checks have passed:
— User authorization for creating the queue object
— User authorization for read access to any source object for move, copy, serialize, or deserialize
— Availability of space to create the queue or at least enough space to create a URI to report an error
Future accesses to the URI created (or the object ID) will succeed modulo any delays due to use of eventual consistency.
The client performs GET operations to the URI to track the progress of the operation. In particular, the server returns two fields in its response body to indicate progress:
• A completionStatus text field contains either "Processing", "Complete", or an error message • An optional percentComplete field that indicates the percentage to which the last PUT has
completed (0 to 100)
GET does not return any value for the object when completionStatus is not "Complete".
When the final result of the create operation is an error, the URI is created with the completionStatus field set to the error message. It is the client's responsibility to delete the URI after the error has been noted.
Capabilities:
The following capabilities describe the supported operations that can be performed when creating a new queue object:
• Support for the ability to create a new queue object is indicated by the presence of the "cdmi_create_queue" capability in the parent container.
• If the new queue object is a reference of an existing queue object, support for the ability to create the reference is indicated by the presence of the "cdmi_create_reference" capability in the parent container.
• If the new queue object is a copy of an existing queue object, support for the ability to copy is indicated by the presence of the "cdmi_copy_queue" capability in the patent container.
• If the new queue object is the destination of a move, support for the ability to move the queue object is indicated by the presence of the "cdmi_move_queue" capability in the parent container. • If the new queue object is the destination of a deserialize operation, support for the ability to
deserialize the source data object is indicated by the presence of the "cdmi_deserialize_queue" capability in the parent container.
Request Headers:
Request Message Body:
Header Type Value Mandatory/Optional
Accept Header String "application/vnd.org.snia.cdmi.queue+json" Mandatory Content-Type Header String "application/vnd.org.snia.cdmi.queue+json" Mandatory X-CDMI- Specification- Version Header String
A comma separated list of versions supported by the client, for example, "1.0, 1.5, 2.0".
Mandatory
X-CDMI- NoClobber
Header String
"true". Do not overwrite an existing queue object. If this header element is present and set to "true", it is an error for this operation to proceed. An update should be done instead.
Optional
Name Type Description Mandatory/Optional
metadata JSON
Object
Metadata for the queue object.
If this field is included when deserializing,
serializing, copying, or moving a queue object, the value provided shall be replace the metadata from the source URI.
This field shall not be included when referencing a queue object.
If this field is not specified, an empty JSON object ("{}") will be assigned as the field value.
Optional
domainURI JSON
String
URI of the owning domain.
If different from the parent domain, the user must have the "cross_domain" privilege.
If not specified, the parent domain will be used.
Optional
deserialize JSON
String
URI of a serialized CDMI data object that will be deserialized to create the new queue object.
Optional*
copy JSON
String
URI of a CDMI queue object that will be copied into the new queue object.
*Only one of these parameters shall be specified in any given operation and is not persisted.
Response Headers:
Response Message Body:
move JSON
String
URI of a CDMI queue object that will be copied into the new queue object. When the copy is
successfully completed, the queue object at the source URI is removed.
Optional*
reference JSON
String
URI of a CDMI queue object to which a reference points. No other fields may be specified when creating a reference.
Optional*
Header Type Value Mandatory/Optional
Content-Type Header String "application/vnd.org.snia.cdmi.queue+json" Mandatory X-CDMI- Specification- Version Header String
The server shall respond with the highest version supported by both the client and the server, for example, "1.0".
Mandatory
Name Type Description Mandatory/Optional
objectURI JSON
String
URI of the queue as specified in the request. Mandatory
objectID JSON
String
Object ID of the object Mandatory
parentURI JSON
String
URI for the parent object Mandatory
domainURI JSON
String
URI of the owning domain Mandatory
capabilitiesURI JSON String
URI to the capabilities for the object.
The capabilities URI returned is based on the object type and requested data system metadata fields.
Mandatory
completionStatus JSON String
A string indicating if the object is still in the process of being created, and once the operation is complete, if it was created successfully or an error occurred. The value shall be the string "Processing", the string "Complete", or an error message.
Mandatory
percentComplete JSON String
The value shall be an integer numeric value from 0 through 100.
Optional
Response Status:
Example Request:
PUT to the container URI the queue object name and contents
metadata JSON
Object
Metadata for the queue object. This field includes any user and data system metadata specified in the request body metadata field, along with storage system metadata generated by the cloud storage system. See Chapter 16, “Metadata” for a further description of metadata.
Mandatory
queueValues JSON
String
The number of values enqueued in the queue. Mandatory
HTTP Status Description
201 Created New queue object was created
202 Accepted Queue object is in the process of being created. Investigate completionStatus and percentComplete parameters to determine the current status of the operation
304 Not Modified The operation conflicts because the queue object already exists and the X- CDMI-NoClobber header element was set to "true".
400 Bad Request Invalid parameter of field names in the request 401 Unauthenticated Incorrect or missing authentication credentials
403 Unauthorized Client lacks the proper authorization to perform this request.
409 Conflict The operation conflicts with a non-CDMI access protocol lock, or could cause a state transition error on the server.
PUT /MyContainer/MyQueue HTTP/1.1 Host: cloud.example.com Accept: application/vnd.org.snia.cdmi.queue+json Content-Type: application/vnd.org.snia.cdmi.queue+json X-CDMI-Specification-Version: 1.0 { "metadata" : { } }
The response looks like: