11-Queue_Objects

11 Queue Object Resource Operations

11.1 Overview

Queue objects provide first-in, first-out access when storing and retrieving data. A queue object writer POSTs data into a queue object, and a queue object reader GETs value(s) from the queue object and subsequently deletes the value(s) to acknowledge receipt of the value(s) that it received. Queuing provides a simple mechanism for one or more writers to send data to a single reader in a reliable way. If supported by the cloud storage system, cloud clients create the queue objects by using the mechanism described in 9.11 and this clause.

Queue objects are addressed in CDMI™ in two ways:

• by URI (e.g., http://cloud.example.com/queueobject); and

• by object ID (e.g, http://cloud.example.com/cdmi_objectid/0000706D0010B84FAD185C425D8B537E).

The first example addresses the queue object by URI, and the second addresses the queue object by object ID. Every queue object has a single, globally-unique object identifier (ID) that remains constant for the life of the object. Each queue object may also have one or more URI addresses that allow the object to be accessed.

A queue object may have a parent object. In this case, the queue object inherits data system metadata that is not explicitly specified in the queue object itself.

EXAMPLE 1 The "receipts.queue" queue object stored at the following URI would inherit data system metadata from its parent container, "finance":

http://cloud.example.com/finance/receipts.queue

Individual fields within a queue object may be accessed by specifying the field name after a question mark "?" that is appended to the end of the data object URI.

EXAMPLE 2 The following URI returns the value field containing the oldest queue object value in the response body:

http://cloud.example.com/queueobject?value

The encoding of the data transported in the queue object value field depends on the queue object valuetransferencoding field:

• If the value transfer encoding of the object is set to "utf-8", the data stored in the value of the queue object shall be a valid UTF-8 string, and it shall be transported as a UTF-8 string in the value field.

• If the value transfer encoding of the object is set to "base64", the data stored in the value of the queue object can contain arbitrary binary sequences, and it shall be transported as a base 64-encoded string in the value field.

Specific ranges of the value of a queue object may be accessed by specifying a byte range after the value field name. Thus, the following URI returns the first thousand bytes of the oldest value enqueued:

http://cloud.example.com/queueobject?value:0-999

Because a byte range of a UTF-8 string is often not a valid UTF-8 string, the response to a range request shall always be transported in the value field as a base 64-encoded string.

Byte ranges are specified as single, inclusive byte ranges as per Section 14.35.1 of RFC 2616.

When a client provides or includes deserialization fields that are not defined in this specification, these fields shall be stored as part of the object.

11.1.1 Queue Object Metadata

Queue object metadata may also include arbitrary user-supplied metadata and data system metadata, as specified in Clause 16.

11.1.2 Queue Object Addressing

Each queue object is addressed via one or more unique URIs, and all operations may be performed through any of these URIs.

11.1.3 Queue Object Representations

The representations in this clause are shown using JSON notation. Both clients and servers shall support UTF-8 JSON representation. The request and response body JSON fields may be specified or returned in any order, with the exception that, if present, for queue objects, the valuerange and value fields shall appear last and in that order.

11.2 Create a Queue Object using CDMI Content Type

11.2.1 Synopsis

The following HTTP PUT creates a new queue object at the specified URI.

PUT <root URI>/<ContainerName>/<QueueName>

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers that already exist, with one slash (i.e., "/") between each pair of container names.

• <QueueName> is the name specified for the queue object to be created.

After it is created, the data object shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

11.2.2 Delayed Completion of Create:

In response to a create operation for a queue object, the server may return a response of 202 Accepted. In this case, the queue object is in the process of being created. This response is particularly useful for long-running operations, (e.g., for copying a queueobject with a large number of enqueued values from a source URI). Such a response has the following implications:

• The server shall return an object ID 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; and

— availability of space to create the queue object or at least enough space to create a URI to report an error.

• Future accesses to the URI created (or the object ID) shall succeed notwithstanding any delays due to use of eventual consistency.

The client performs GET operations to the URI to track the progress of the operation. In response, the server returns two fields in its response body to indicate progress.

• A completionStatus text field contains either “Processing”, “Complete”, or an error string starting with the value "Error".

• An optional percentComplete field contains the percentage that the Accepted 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.

11.2.3 Capabilities

The following capabilities describe the supported operations that may 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 object being created in the parent container is a reference, support for that ability 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.

11.2.4 Request Headers

The HTTP request headers for creating a CDMI queue object using CDMI content type are shown in Table 82.

Table 82 - Request Headers - Create a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
Accept	Header String	"application/cdmi-queue"	Mandatory
Content-Type	Header String	"application/cdmi-queue"	Mandatory
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.2.5 Request Message Body

The request message body fields for creating a queue object using CDMI content type are shown in Table 83.

Table 83 - Request Message Body - Create a Queue Object using CDMI Content Type

Field Name	Type	Description	Requirement
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 in this field shall replace the metadata from the source URI. • If this field is not included when deserializing, serializing, copying, or moving a queue object, the metadata from the source URI shall be used. • If this field is included when creating a new queue object by specifying a value, the value provided in this field shall be used as the metadata. • If this field is not included when creating a new queue object by specifying a value, an empty JSON object (i.e., "{}") shall be assigned as the field value. • This field shall not be included when referencing a queue object.	Optional
domainURI	JSON String	URI of the owning domain • If different from the parent domain, the user shall have the "cross_domain" privilege (see cdmi_member_privileges in Table 64). • If not specified, the parent domain shall be used.	Optional
deserialize	JSON String	URI of a serialized CDMI data object that shall be deserialized to create the new queue object	Optional^a
copy	JSON String	URI of a CDMI queue object that shall be copied into the new queue object	Optional^a
move	JSON String	URI of an existing local or remote CDMI queue object (source URI) that shall be relocated to the URI specified in the PUT. The contents of the queue object, including the object ID, shall be preserved by a move, and the queue object at the source URI shall be removed after the queue object at the destination has been successfully created. If there are insufficient permissions to read the queue object at the source URI, write the queue object at the destination URI, or delete the queue object at the source URI, or if any of these operations fail, the move shall return a 400 Bad Request result code, and the source and destination are left unchanged.	Optional^a
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^a
deserializevalue	JSON String	A queue object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648.	Optional^a
^aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored. If more than one of these fields is supplied, the server shall respond with a 400 Bad Request error response.

11.2.6 Response Headers

The HTTP response headers for creating a CDMI queue object using CDMI content type are shown in Table 84.

Table 84 - Response Headers - Create a Queue Object using CDMI Content Type

Header

Type

Description

Requirement

Content-Type

Header String

"application/cdmi-queue"

Mandatory

X-CDMI-Specification-Version

Header String

The server shall respond with the highest version supported by both the client and the server, e.g., "1.0.1".

If the server does not support any of the versions supported by the client, the server shall return a 400 Bad Request status code.

Mandatory

11.2.7 Response Message Body

The response message body fields for creating a CDMI queue object using CDMI content type are shown in Table 85.

Table 85 - Response Message Body - Create a Queue Object using CDMI Content Type

Field Name	Type	Description	Requirement
objectType	JSON String	”application/cdmi-queue”	Mandatory
objectID	JSON String	Object ID of the object	Mandatory
objectName	JSON String	Name of the object • For objects in a container, the objectName field shall be returned. • For objects not in a container (objects that are only accessible by ID), the objectName field shall not be returned.	Mandatory
parentURI	JSON String	URI for the parent object • For objects in a container, the parentURI field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentURI field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object.	Mandatory
parentID	JSON String	Object ID of the parent container object • For objects in a container, the parentID field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentID field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the 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 after 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 string starting with the value "Error".	Mandatory
percentComplete	JSON String	The value shall be an integer numeric value from 0 through 100.	Optional
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 Clause 16 for a further description of metadata.	Mandatory
queueValues	JSON String	A range of values enqueued in the queue object. The first value increases as items are deleted, and the second value increases as items are enqueued, e.g., • Create: -> "", • Enqueue: -> "0-0", • Enqueue: -> "0-1", • Enqueue: -> "0-2", • Delete: -> "1-2", • Delete: -> "2-2", • Delete: -> "", and • Enqueue: -> "3-3". Clients should ensure that they use sufficient precision (e.g. 64-bits) when storing these values in an internal representation to avoid overflow.	Mandatory

11.2.8 Response Status

Table 86 describes the HTTP status codes that occur when creating a queue object using CDMI content type.

Table 86 - HTTP Status Codes - Create a Queue Object using CDMI Content Type

HTTP Status	Description
201 Created	New queue object was created.
202 Accepted	Queue object is in the process of being created. The CDMI client should monitor completionStatus and percentComplete fields to determine the current status of the operation.
400 Bad Request	Invalid parameter or field names in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
409 Conflict	The operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server.

11.2.9 Example

EXAMPLE PUT to the container URI the queue object name and contents

PUT /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-queue

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"metadata" : {

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"objectType" : "application/cdmi-queue",

"objectID" : "00007E7F00104BE66AB53A9572F9F51E",

"objectName" : "MyQueue",

"parentURI " : "/MyContainer/",

"parentID" : "0000706D0010B84FAD185C425D8B537E",

"domainURI" : "/cdmi_domains/MyDomain/",

"capabilitiesURI" : "/cdmi_capabilities/queue/",

"completionStatus" : "Complete",

"metadata" : {

"queueValues" : ""

}

11.3 Read a Queue Object using CDMI Content Type

11.3.1 Synopsis

The following HTTP GET reads from an existing queue object at the specified URI.

GET <root URI>/<ContainerName>/<QueueName>

GET <root URI>/<ContainerName>/<QueueName>?<fieldname>;<fieldname>;...

GET <root URI>/<ContainerName>/<QueueName>?value:<range>;...

GET <root URI>/<ContainerName>/<QueueName>?metadata:<prefix>;...

GET <root URI>/<ContainerName>/<QueueName>?values:<count>

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers.

• <QueueName> is the name of the queue object to be read from.

• <fieldname> is the name of a field.

• <range> is a byte range of the queue object value to be returned in the value field. If a byte range is requested, the range returned shall be from the oldest queue object value.

• <prefix> is a matching prefix that returns all metadata items that start with the prefix value.

• <count> is the number of values to be retrieved from the queue object. If more queue object entries are requested to be retrieved than exist in the queue object, the count is processed as if it is equal to the number of entries in the queue object.

The object shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

11.3.2 Capabilities

The following capabilities describe the supported operations that may be performed when reading an existing queue object:

• Support for the ability to read the metadata of an existing queue object is indicated by the presence of the "cdmi_read_metadata" capability in the specified queue object.

• Support for the ability to read the value of an existing queue object is indicated by the presence of the "cdmi_read_value" capability in the specified queue object.

11.3.3 Request Headers

The HTTP request headers for reading a CDMI queue object using CDMI content type are shown in Table 87.

Table 87 - Request Headers - Read a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
Accept	Header String	"application/cdmi-queue". This header shall contain a list of one or more of the five CDMI MIME types (see RFC 6208).	Mandatory
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.3.4 Request Message Body

No request message body fields are specified by this international standard.

11.3.5 Response Headers

The HTTP response headers for reading a CDMI queue object using CDMI content type are shown in Table 88.

Table 88 - Response Headers - Read a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
X-CDMI-Specification-Version	Header String	The server shall respond with the highest version supported by both the client and the server, e.g., "1.0.1". If the server does not support any of the versions supported by the client, the server shall return a 400 Bad Request status code.	Mandatory
Content-Type	Header String	"application/cdmi-queue"	Mandatory
Location	Header String	The server shall respond with the URI that the reference points to if the object is a reference.	Mandatory

11.3.6 Response Message Body

The response message body fields for reading a CDMI queue object using CDMI content type are shown in Table 89.

Table 89 - Response Message Body - Read a Queue Object using CDMI Content Type

Field Name	Type	Description	Requirement
objectType	JSON String	”application/cdmi-queue”	Mandatory
objectID	JSON String	Object ID of the object	Mandatory
objectName	JSON String	Name of the object • For objects in a container, the objectName field shall be returned. • For objects not in a container (objects that are only accessible by ID), the objectName field shall not be returned.	Mandatory
parentURI	JSON String	URI for the parent object • For objects in a container, the parentURI field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentURI field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object.	Mandatory
parentID	JSON String	Object ID of the parent container object • For objects in a container, the parentID field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentID field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the 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 after 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 string starting with the value "Error".	Mandatory
percentComplete	JSON String	The value shall be an integer numeric value from 0 through 100.	Optional
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 Clause 16 for a further description of metadata.	Mandatory
queueValues	JSON String	A range of values enqueued in the queue object. The first value increases as items are deleted, and the second value increases as items are enqueued, e.g., • Create: -> "", • Enqueue: -> "0-0", • Enqueue: -> "0-1", • Enqueue: -> "0-2", • Delete: -> "1-2", • Delete: -> "2-2", • Delete: -> "", and • Enqueue: -> "3-3". Clients should ensure that they use sufficient precision (e.g. 64-bits) when storing these values in an internal representation to avoid overflow.	Mandatory
mimetype	JSON Array of JSON Strings	MIME types for each queue object value • The MIME types of the values are returned, each corresponding to the value in the same position in the JSON array. • This field shall only be provided when completionStatus is "Complete" and when one or more values are enqueued.	Optional
valuerange	JSON Array of JSON Strings	The range of bytes of the queue object values to be returned in the value field • The value ranges of the values are returned, each corresponding to the value in the same position in the JSON array. • If a specific value range has been requested, the entry in the value range field shall correspond to the bytes requested. If the request extends beyond the end of the value, the value range field shall indicate the smaller byte range returned. • The valuerange field shall only be provided when the "completionStatus" field contains "Complete".	Optional
valuetransferencoding	JSON Array of JSON String	The value transfer encoding used for each queue object value. Two value transfer encodings are defined: • "utf-8" indicates that the queue object value contains a valid UTF-8 string, and itshall be transported as a UTF-8 string in the value field. • "base64" indicates that the queue object value may contain arbitrary binary sequences, and it shall be transported as a base 64-encoded string in the value field. The value transfer encodings are returned, each corresponding to the value in the same position in the JSON array. The valuetransferencoding field shall only be provided when the completionStatus field contains "Complete".	Optional
value	JSON Array of JSON Strings	The oldest enqueued queue object values • The values in the JSON array are returned in order from oldest to newest. • If the valuetransferencoding field indicates UTF-8 encoding, the corresponding value field shall contain a UTF-8 string using JSON escaping rules described in RFC 4627. • If the valuetransferencoding field indicates base 64 encoding, the corresponding value field shall contain a base 64-encoded string as described in RFC RFC 4648. • The value field shall only be provided when the "completionStatus" field contains "Complete".	Optional

If individual fields are specified in the GET request, only these fields are returned in the result body. Optional fields that are requested but do not exist are omitted from the result body.

11.3.7 Response Status

Table 90 describes the HTTP status codes that occur when reading a queue object using CDMI content type.

Table 90 - HTTP Status Codes - Read a Queue Object using CDMI Content Type

HTTP Status	Description
200 OK	Valid response is enclosed.
302 Found	The URI is a reference to another URI.
400 Bad Request	Invalid parameter or field names in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
406 Not Acceptable	The server is unable to provide the object in the content-type specified in the Accept header.

11.3.8 Examples

EXAMPLE 1 GET to the queue object URI to read all fields of the queue object

GET /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"objectType": "application/cdmi-queue",

"objectID": "00007E7F00104BE66AB53A9572F9F51E",

"objectName": "MyQueue",

"parentURI": "/MyContainer/",

"parentID" : "0000706D0010B84FAD185C425D8B537E",

"domainURI": "/cdmi_domains/MyDomain/",

"capabilitiesURI": "/cdmi_capabilities/queue/",

"completionStatus": "Complete",

"metadata": {},

"queueValues": "1-2",

"mimetype": [

"text/plain"

"valuerange": [

"0-19"

"valuetransferencoding": [

"utf-8"

"value": [

"First Enqueued Value"

]

}

EXAMPLE 2 GET to the queue object URI to read the value and queue items of the queue object

GET /MyContainer/MyQueue?value;queueValues HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"queueValues" : "1-2",

"value" : [

"First Enqueued Value"

]

}

EXAMPLE 3 GET to the queue object URI to read the first five bytes of the value of the queue object

GET /MyContainer/MyQueue?value:0-5 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

The following shows the response:

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"value" : [

"First"

]

}

EXAMPLE 4 GET to the queue object URI to read two values of the queue object

GET /MyContainer/MyQueue?mimetype;valuerange;values:2 HTTP/1.1

Host: cloud.example.com

Accept: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"mimetype" : [

"text/plain",

"text/plain"

"valuerange" : [

"0-19",

"0-20"

"value" : [

"First Enqueued Value",

"Second Enqueued Value"

]

}

11.4 Update a Queue Object using CDMI Content Type

11.4.1 Synopsis

The following HTTP PUT updates an existing queue object at the specified URI.

PUT <root URI>/<ContainerName>/<QueueName>

PUT <root URI>/<ContainerName>/<QueueName>?metadata:<metadataname>;...

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers.

• <QueueName> is the name of the queue object to be updated.

The object shall also be accessible at <root URI>/cdmi_objectid/<objectID>. An update shall not result in a change to the object ID.

11.4.2 Capabilities

The following capabilities describe the supported operations that may be performed when updating an existing queue object:

Support for the ability to modify the metadata of an existing queue object is indicated by the presence of the "cdmi_modify_metadata" capability in the specified queue object.

11.4.3 Request Headers

The HTTP request headers for updating a CDMI queue object using CDMI content type are shown in Table 91.

Table 91 - Request Headers - Update a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
Content-Type	Header String	"application/cdmi-queue "	Mandatory
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.4.4 Request Message Body

The request message body fields for updating a queue object using CDMI content type are shown in Table 92.

Table 92 - Request Message Body - Update a Queue Object using CDMI Content Type

Field Name	Type	Description	Requirement
metadata	JSON Object	Metadata for the queue object. If present, the new metadata specified replaces the existing object metadata. If individual metadata items are specified in the URI, only those items are replaced, with other items being preserved. See Clause 16 for a further description of metadata.	Optional
domainURI	JSON String	URI of the owning domain. If different from the parent domain, the user shall have the "cross_domain” privilege (see cdmi_member_privileges in Table 64). If not specified, the parent domain shall be used.	Optional
deserialize	JSON String	URI of a serialized CDMI queue object that shall be deserialized to update an existing queue object. The object ID of the serialized queue object shall match the object ID of the destination queue object. All enqueued items in the serialized queue object shall be added to the destination queue object.	Optional^a
copy	JSON String	URI of a CDMI queue object that shall be copied into the existing queue object. Queue Object copy does not copy enqueued items. See 11.6 to copy enqueued items.	Optional^a
deserializevalue	JSON String	A data object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648. The object ID of the serialized data object shall match the object ID of the destination data object. All enqueued items in the serialized queue object shall be added to the destination queue object.	Optional^a
^aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored.

11.4.5 Response Header

The HTTP response header for updating a CDMI queue object using CDMI content type is shown in Table 93.

Table 93 - Response Header - Update a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
Location	Header String	The server shall respond with the URI that the reference points to if the object is a reference.	Mandatory

11.4.6 Response Message Body

No response message body fields are specified by this international standard.

11.4.7 Response Status

Table 94 describes the HTTP status codes that occur when updating a queue object using CDMI content type.

Table 94 - HTTP Status Codes - Update a Queue Object using CDMI Content Type

HTTP Status	Description
204 No Content	Operation successful, no data
302 Found	The URI is a reference to another URI.
400 Bad Request	Invalid parameter or field names in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
409 Conflict	The operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server.

11.4.8 Example

EXAMPLE 5 PUT to the queue object URI to set new metadata

PUT /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"metadata" : {

}

The following shows the response.

HTTP/1.1 204 No Content

11.5 Delete a Queue Object using CDMI Content Type

11.5.1 Synopsis

The following HTTP DELETE deletes an existing queue object and all enqueued values at the specified URI.

DELETE <root URI>/<ContainerName>/<QueueName>

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers.

• <QueueName> is the name of the queue object to be deleted.

The object shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

11.5.2 Capabilities

The following capabilities describe the supported operations that may be performed when deleting an existing data object:

Support for the ability to delete an existing queue object is indicated by the presence of the "cdmi_delete_queue" capability in the specified queue object.

11.5.3 Request Header

The HTTP request header for deleting a CDMI queue object using CDMI content type is shown in Table 95.

Table 95 - Request Header - Delete a Queue Object using CDMI Content Type

Header	Type	Description	Requirement
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.5.4 Request Message Body

No request message body fields are specified by this international standard.

11.5.5 Response Headers

No response headers are specified by this international standard.

11.5.6 Response Message Body

No response message body fields are specified by this international standard.

11.5.7 Response Status

Table 96 describes the HTTP status codes that occur when deleting a queue object using CDMI content type.

Table 96 - HTTP Status Codes - Delete a Queue Object using CDMI Content Type

HTTP Status	Description
204 No Content	Queue object was successfully deleted.
400 Bad Request	Invalid parameter or field names in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
409 Conflict	The queue object may not be deleted (may be immutable).

11.5.8 Example

EXAMPLE DELETE to the queue object URI

DELETE /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

X-CDMI-Specification-Version: 1.0.1

The following shows the response.

HTTP/1.1 204 No Content

11.6 Enqueue a New Queue Value using CDMI Content Type

11.6.1 Synopsis

The following HTTP POST enqueues a new data value in an existing qqueue object at the specified container URI.

POST <root URI>/<ContainerName>/<QueueName>

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers that already exist, with one slash (i.e., "/") between each pair of container names.

• <QueueName> is the name of the queue object to be read from.

11.6.2 Capabilities

The following capabilities describe the supported operations that may be performed when enqueuing a new value into an existing queue object:

Support for the ability to modify the value of an existing queue object is indicated by the presence of the "cdmi_modify_value" capability in the specified queue object.

11.6.3 Request Headers

The HTTP request headers for enqueuing a new CDMI queue object value using CDMI content type are shown in Table 97.

Table 97 - Request Headers - Enqueue a New Queue Object Value using CDMI Content Type

Header	Type	Description	Requirement
Content-Type	Header String	"application/cdmi-queue"	Mandatory
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.6.4 Request Message Body

The request message body fields for enqueuing a new queue object value using CDMI content type are shown in Table 98.

Table 98 - Request Message Body - Enqueue a New Queue Value using CDMI Content Type

Field Name	Type	Description	Requirement
mimetype	JSON Array of JSON Strings	MIME type of the data to be enqueued into the queue object. • This field shall be stored as part of the object. • If this field is not specified, the value of "text/plain" shall be assigned as the field value. • The same number of array elements shall be present as is present in the value field, and the mimetype shall be associated with the value in the corresponding position. • This mimetype value shall be converted to lower case before being stored.	Optional
copy	JSON String	URI of a CDMI data object or queue object from which the value shall be moved and enqueued • If a URI to a data object is provided, the value, mimetype, and valuetransferencoding from the data object is used to enqueue the new item into the queue object, and the data object is atomically deleted. • If a URI to a queue object is provided, the corresponding value, mimetype, and valuetransferencoding of the specified number of enqueued items are transferred to the queue object and atomically removed from the source queue object.	Optional^a
move	JSON String	URI of a CDMI data object or queue object from which the value shall be enqueued, and removed the data object or queue object value at the source URI upon the successful completion of the enqueue	Optional^a
valuetransferencoding	JSON Array of JSON Strings	The value transfer encoding used for the queue object value. Two value transfer encodings are defined: • "utf-8" indicates that the queue object value contains a valid UTF-8 string, and shall be transported as a UTF-8 string in the value field. • "base64" indicates that the queue object value may contain arbitrary binary sequences, and shall be transported as a base 64 encoded string in the value field. Setting the contents of the queue object value field to any value other than a valid base 64 string shall result in error 400 Bad Request being returned to the client. If this field is not specified, the value of "utf-8" shall be assigned as the field value. This field shall be stored as part of the object.	Optional
value	JSON Array of JSON Strings	Data to be enqueued into the queue object. • If the corresponding value transfer encoding field indicates UTF-8 encoding, the value shall be a UTF-8 string escaped using the JSON escaping rules described in RFC 4627. • If the corresponding value transfer encoding field indicates base 64 encoding, the value shall be first encoded using the base 64 encoding rules as described in RFC 4648.	Optional^a
^aOnly one of these fields shall be specified in any given operation. Except for value, these fields shall not be stored. If more than one of these fields is supplied, the server shall respond with a 400 Bad Request error response.

11.6.5 Response Headers

No response headers are specified by this international standard.

11.6.6 Response Message Body

No response message body fields are specified by this international standard.

11.6.7 Response Status

Table 99 describes the HTTP status codes that occur when enqueuing a new queue object using CDMI content type.

Table 99 - HTTP Status Codes - Enqueue a New Queue Object Value using CDMI Content Type

HTTP Status	Description
204 No Content	New queue values were enqueued.
400 Bad Request	Invalid parameter in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
409 Conflict	The operation conflicts with a non-CDMI access protocol lock or may cause a state transition error on the server.

11.6.8 Examples

EXAMPLE 1 POST to the queue object URI a new value

POST /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.1

{

"mimetype" : [

"text/plain"

"value" : [

"Value to Enqueue"

]

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 2 POST to the queue object URI to copy an existing value

POST /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.1

{

"copy" : "/MyContainer/MyDataObject"

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 3 POST to the queue object URI to transfer twenty values from another queue object

POST /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.1

{

"move" : "/MyContainer/FirstQueue?values:20"

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 4 POST to the queue object URI two new values

POST /MyContainer/MyQueue

HTTP/1.1 Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.1

{

"mimetype" : [

"text/plain",

"text/plain"

"value" : [

"First",

"Second"

]

}

The following shows the response.

HTTP/1.1 204 No Content

EXAMPLE 5 POST to the queue object URI two new values with base 64 transfer encoding:

POST /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.1

{

"mimetype": [

"text/plain",

"text/plain"

"valuetransferencoding": [

"utf-8",

"base64"

"value": [

"First",

"U2Vjb25k"

]

}

The following shows the response.

HTTP/1.1 204 No Content

11.7 Delete a Queue Object Value using CDMI Content Type

11.7.1 Synopsis

The following HTTP DELETE deletes the oldest enqueued value in an existing queue object at the specified URI.

DELETE <root URI>/<ContainerName>/<QueueName>?value

DELETE <root URI>/<ContainerName>/<QueueName>?values:<count>

Where:

• <root URI> is the path to the CDMI cloud.

• <ContainerName> is zero or more intermediate containers.

• <QueueName> is the name of the queue object to be deleted.

• <count> is the number of values to be removed from the queue object. If more queue object entries are requested to be deleted than exist in the queue object, the count is considered equal to the number of entries in the queue object.

The object shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

11.7.2 Capabilities

The following capabilities describe the supported operations that may be performed when deleting an existing data object:

Support for the ability to modify the value of an existing queue object is indicated by the presence of the "cdmi_modify_value" capability in the specified queue object.

11.7.3 Request Header

The HTTP request header for deleting a CDMI queue object value using CDMI content type is shown in Table 100.

Table 100 - Request Header - Delete a Queue Object Value using CDMI Content Type

Header	Type	Description	Requirement
X-CDMI-Specification-Version	Header String	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

11.7.4 Request Message Body

No request message body fields are specified by this international standard.

11.7.5 Response Headers

No response headers are specified by this international standard.

11.7.6 Response Message Body

No response message body fields are specified by this international standard.

11.7.7 Response Status

Table 101 describes the HTTP status codes that occur when deleting a queue object using CDMI content type.

Table 101 - HTTP Status Codes - Delete a Queue Object Value using CDMI Content Type

HTTP Status	Description
204 No Content	Queue object value was successfully deleted.
400 Bad Request	Invalid parameter or field names in the request
401 Unauthorized	Incorrect or missing authentication credentials
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
409 Conflict	The queue object may not be deleted (may be immutable).

11.7.8 Example

EXAMPLE DELETE to the queue object URI value to access the next enqueued value

DELETE /MyContainer/MyQueue?value HTTP/1.1

Host: cloud.example.com

X-CDMI-Specification-Version: 1.0.1

The following shows the response.

HTTP/1.1 204 No Content