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.10 and this clause.

Queue objects are addressed in CDMI™ in two ways:

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

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

Every queue object has a single, globally-unique object identifier (ID) that remains constant for the life of the object. Each queue object shall 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 message 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 international standard, 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 message 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

To create a new queue object, the following request shall be performed:

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

To create a new queue object by ID, see 9.10.

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 object shall also be accessible at <root URI>/cdmi_objectid/<objectID>.

The newly created queue shall have no values unless the queue is created as a result of copying or moving a source queue that has values or as a result of deserializing a serialized queue that has values.

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 queue object with a large number of enqueued values from a source URI). Such a response has the following implications:

   The server shall return a Location header with a URI to the object to be created along with an HTTP status code of 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.

   A client might not be able to immediately access the created object, e.g., due to delays resulting from the implementation’s 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 message 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 parent 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 81.

Table 81 - 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.2, 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 82.

Table 82 - 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

Optionala

copy

JSON String

URI of a CDMI queue object that shall be copied into the new queue object

Optionala

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.

Optionala

reference

JSON String

URI of a CDMI queue object that shall be redirected to by a reference. If other fields are supplied when creating a reference, the server shall respond with an HTTP status code of 400 Bad Request.

Optionala

deserializevalue

JSON String

A queue object serialized as specified in Clause 15 and encoded using base 64 encoding rules described in RFC 4648.

Optionala

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 83.

Table 83 - 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.2".

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 84.

Table 84 - 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

Mandatory

parentURI

JSON String

URI for the parent object

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

Mandatory

domainURI

JSON String

URI of the owning domain.

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

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

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer 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 message 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

The range of designators for enqueued values. Every enqueued value shall be assigned a unique, monotonically-incrementing positive integer designator, starting from 0. If no values are enqueued, an empty string shall be returned. If values are enqueued, the lowest designator, followed by a hyphen ("-"), followed by the highest designator shall be returned.

Mandatory

11.2.8   Response Status

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

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

HTTP Status

Description

201 Created

The new queue object was created.

202 Accepted

The queue object is in the process of being created. The CDMI client should monitor the completionStatus and percentComplete fields to determine the current status of the operation.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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.2

 

{

   "metadata" : {

        

   }

}

The following shows the response.

HTTP/1.1 201 Created

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

   "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

To read all fields from an existing queue object, the following request shall be performed:

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

To read one or more requested fields from an existing queue object, one of the following requests shall be performed:

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

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

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

To read one or more queue values from an existing queue object, the following request shall be performed:

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>.

Reading a queue object shall, by default, return the complete value of the oldest item in the queue, unless the queueValues range is empty.

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 86.

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

Header

Type

Description

Requirement

Accept

Header String

"application/cdmi-queue" or a consistent value as per clause 5.13.2

Optional

X-CDMI-Specification-Version

Header String

A comma-separated list of versions supported by the client, e.g., "1.0.2, 1.5, 2.0"

Mandatory

11.3.4   Request Message Body

A request message body shall not be provided.

11.3.5   Response Headers

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

Table 87 - 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.2".

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 redirects to if the object is a reference.

Conditional

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 88.

Table 88 - 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 does not exist and shall not be returned.

Conditional

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 does not exist and shall not be returned.

Appending the objectName to the parentURI shall always produce a valid URI for the object.

Conditional

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 does not exist and shall not be returned.

Conditional

domainURI

JSON String

URI of the owning domain

Mandatory

capabilitiesURI

JSON String

URI to the capabilities for the object

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

   When the value of completionStatus is "Processing", this field, if provided, shall indicate the percentage of completion as a numeric integer value from 0 through 100.

   When the value of completionStatus is "Complete", this field, if provided, shall contain the value "100".

   When the value of completionStatus is "Error", this field, if provided, may contain any integer 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 message 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

The range of designators for enqueued values. Every enqueued value shall be assigned a unique, monotonically-incrementing positive integer designator, starting from 0. If no values are enqueued, an empty string shall be returned. If values are enqueued, the lowest designator, followed by a hyphen ("-"), followed by the highest designator shall be returned.

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".

Conditional

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 89 describes the HTTP status codes that occur when reading a queue object using CDMI content type.

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

HTTP Status

Description

200 OK

The queue object content was returned in the reponse.

302 Found

The URI is a reference to another URI.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

   "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.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

   "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.2

The following shows the response:

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

   "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.2

The following shows the response.

HTTP/1.1 200 OK

Content-Type: application/cdmi-queue

X-CDMI-Specification-Version: 1.0.2

 

{

   "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

To update some or all fields in an existing queue object (excluding the enqueueing of values), the following request shall be performed:

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

To add, update, and remove specific metadata items of an existing queue object, the following request shall be performed:

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   Capability

The following capability describes 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 90.

Table 90 - 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.2, 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 91.

Table 91 - 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.

Optionala

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.

Optionala

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.

Optionala

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 92.

Table 92 - 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 redirects to if the object is a reference.

Conditional

11.4.6   Response Message Body

A response message body may be provided as per RFC 2616.

11.4.7   Response Status

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

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

HTTP Status

Description

204 No Content

The operation was successful; no data was returned.

302 Found

The URI is a reference to another URI.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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   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.2

 

{

   "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

To delete an existing queue object, along with all enqueued values, the following request shall be performed:

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   Capability

The following capability describes 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 94.

Table 94 - 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.2, 1.5, 2.0"

Mandatory

11.5.4   Request Message Body

A request message body may be provided as per RFC 2616.

11.5.5   Response Headers

Response headers may be provided as per RFC 2616.

11.5.6   Response Message Body

A response message body may be provided as per RFC 2616.

11.5.7   Response Status

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

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

HTTP Status

Description

204 No Content

The queue object was successfully deleted.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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.2

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

To enqueue one or more values into an existing queue object, the following request shall be performed:

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 enqueued into.

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

11.6.2   Capability

The following capability describes 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 96.

Table 96 - 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.2, 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 97.

Table 97 - 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(s) of the data value(s) 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 field shall be associated with the value in the corresponding position.

   This mimetype field 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 field values from the data object are 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 field values of the specified number of enqueued items are transferred to the queue object and atomically removed from the source queue object.

Optionala

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

Optionala

valuetransferencoding

JSON Array of JSON Strings

The value transfer encoding(s) used for the queue object value(s). 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 value(s) 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.

Optionala

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

Response headers may be provided as per RFC 2616.

11.6.6   Response Message Body

A response message body may be provided as per RFC 2616.

11.6.7   Response Status

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

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

HTTP Status

Description

204 No Content

The new queue values were enqueued.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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.2

 

{

   "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.2

 

{

    "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.2

 

{

    "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.2

 

{

   "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, one with base 64 transfer encoding and one with utf-8 transfer encoding:

POST /MyContainer/MyQueue HTTP/1.1

Host: cloud.example.com

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

  "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

To delete one or more of the oldest enqueued values in an existing queue, the following request shall be performed:

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, starting from the oldest, 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 shall be considered equal to the number of entries in the queue object.

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

The "?value" suffix at the end of the queue resource URI shall be included to distinguish the deletion of the oldest value from the deletion of the queue object itself, as described in 11.5 (which deletes all enqueued values).

11.7.2   Capability

The following capability describes 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 99.

Table 99 - 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.2, 1.5, 2.0"

Mandatory

11.7.4   Request Message Body

A request message body may be provided as per RFC 2616.

11.7.5   Response Headers

Response headers may be provided as per RFC 2616.

11.7.6   Response Message Body

A response message body may be provided as per RFC 2616.

11.7.7   Response Status

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

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

HTTP Status

Description

204 No Content

The queue object value was successfully deleted.

400 Bad Request

The request contains invalid parameters or field names.

401 Unauthorized

The authentication credentials are missing or invalid.

403 Forbidden

The client lacks the proper authorization to perform this request.

404 Not Found

The 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.2

The following shows the response.

HTTP/1.1 204 No Content