21    Notification Queues

A cloud storage system may optionally implement notification functionality. The implementation of notification is indicated by the presence of the cloud storage system-wide capabilities for notification and requires support for CDMI™ queues.

Notification queues allow CDMI clients to efficiently discover what changes have occurred to the system. As queue data is persistent, no session state needs to be retained by the client. If different notification queues are used for different clients, then each client operates independently from the others (e.g., a storage management application may use a notification queue to keep its database current without having to do full scans of a container to discover what data objects have been added, modified, or removed).

When a client wishes to receive notifications, it may first check if the system is capable of providing notifications by checking for the presence of the cdmi_notification capability in the root container capabilities. If this capability is not present, creating a notification queue shall be successful, but no notifications shall be enqueued into the notification queue.

To create a notification queue, the client creates a regular CDMI queue and adds metadata instructing the storage system to treat the queue as a notification queue. This added metadata also instructs the system about what types of notifications shall be generated and what information shall be included with each notification.

After the notification queue is created, all subsequent matching events after the queue creation time shall result in notification results being enqueued into the queue. CDMI does not mandate any specific ordering of events, and clients must be able to handle events that arrive out of order.

When creating a notification queue, the metadata described in Table 122 shall be provided. Attempts to alter metadata in this table shall result in an HTTP status code of 403 Forbidden. After a notification queue has been created, with the exception of cdmi_queue_type, the metadata items in this table cannot be altered. cdmi_queue_type can only be removed, indicating to the system that the notification queue shall no longer receive notifications and shall be treated as a regular CDMI queue object.

Table 122 - Required Metadata for a Notification Queue

Metadata Name

Type

Description

Requirement

cdmi_queue_type

JSON String

The queue type indicates how the cloud storage system shall manage the queue object. The type of cdmi_notification_queue is defined for notification queues.

Mandatory

cdmi_notification_events

JSON Array of JSON Strings

Contains a JSON array that indicates which events generate notifications. Defined values are:

   cdmi_create_processing - Notifications are generated when a new object is created, but is still in the processing completion status.

   cdmi_create_complete - Notifications are generated when a new object is created immediately or when a new object in the process of being created transitions from the "processing" completion status.

   cdmi_read - Notifications are generated when an object is read.

   cdmi_modify_processing - Notifications are generated when an existing object is modified, but is still in the processing completion status.

Mandatory

 

 

   cdmi_modify_complete - Notifications are generated when an existing object is modified and is in the complete completion status. This notification is also generated when an existing object being modified transitions from "Processing" to "Complete".

   cdmi_rename - Notifications are generated when an object is renamed as part of a move request message operation.

   cdmi_copy - Notifications are generated for the newly created copied object when the copy is completed.

   cdmi_reference - Notifications are generated when a reference is created.

   cdmi_delete - Notifications are generated when an object is deleted.

   cdmi_export - Notifications are generated when an container is exported.

   cdmi_snapshot - Notifications are generated when an container is snapshotted.

   <implementor-specific events>

Clients may include the desired notification event types in the cdmi_notification_events JSON array. If all notifications events are desired, an empty JSON array shall be used.

 

cdmi_scope_specification

JSON Array of JSON Objects

The scope specification determines the set of objects on which operations trigger the generation of notifications. If notifications are desired for all objects, include an empty JSON array.

See Clause 18 for how to construct a scope specification.

Mandatory

cdmi_results_specification

JSON Object

Contains the JSON fields to be returned for each object that matches the notification scope specification. See Clause 19 for how to construct a results specification.

In addition to the fields defined in Clause 19, for notifications, four additional fields are defined:

   cdmi_event - Indicates the event as specified in the cdmi_notification_events field that triggered the notification;

   cdmi_event_result - Indicates the status result of the event that triggered the notification. The status is the same as the status that was returned over the HTTP request, i.e., 200 OK, 404 Not Found, etc.;

   cdmi_event_time - Indicates the time of the event that triggered the notification. The time will be formatted in ISO-8601 time (see 5.14 and ISO 8601:2004); and

   cdmi_event_user - Indicates the principal (ACL name) of the user that caused the event that triggered the notification. If the system triggered the event, the name will be left as an empty string.

Mandatory

EXAMPLE 1   The metadata associated with a notification queue is as follows:

{

   "metadata" : {

       "cdmi_queue_type" : "cdmi_notification_queue",

       "cdmi_notification_events" : [

           "cdmi_create_complete",

           "cdmi_read",

           "cdmi_modify_complete",

            "cdmi_delete"

       ],

       "cdmi_scope_specification" : [

           {

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

               "parentURI" : "starts /sandbox",

               "metadata" : {

                   "cdmi_size" : ">+100000"

                }

            }

       ],

       "cdmi_results_specification" : {

           "cdmi_event" : "",

           "cdmi_event_result" : "",

           "cdmi_event_time" : "",

           "objectID" : "",

           "metadata" : {

                "cdmi_size" : ""

            }

        }

    }

}

When notification results are stored in a notification queue, each enqueued value shall consist of a JSON object of MIME type "application/json". This JSON object contains the specified values requested in the cdmi_results_specification of the notification queue metadata.

EXAMPLE 2   A notification result JSON object is as follows:

{

   "cdmi_event" : "cdmi_read",

   "cdmi_event_result" : "200 OK",

   "cdmi_event_time" : "2010-11-15T13:12:52.342324Z",

   "objectID" : "00007E7F0010EB9092B29F6CD6AD6824",

   "metadata" : {

        "cdmi_size" : "108263"

    }

}

Objects shall only be included in the notification results if the user who created the notification queue is able to read the matching object.

If the notification queue was created by the administrator, then all matching objects that the administrator is allowed to read are included in the results. If the notification queue was created by user "jdoe", then only matching objects that "jdoe" is allowed to read are included in the results.

Table 123 describes the system-created metadata that provides details on the status of the notification queue.

Table 123 - Notification Status Metadata

Metadata Name

Type

Description

Requirement

cdmi_notification_status

JSON String

A string indicating the state of the notification queue. Defined values are:

   Processing - Indicates that the notification queue is scanning for results;

   Halted - Indicates that new notifications will no longer be enqueued;

   Current - Indicates that the notification queue contained all notifications that can be found at this time; and

   Error - Indicates that the notification queue metadata is not valid, or other errors were encountered that prevented notification messages from being enqueued. Arbitrary vendor-defined text may follow the string "Error".

If this metadata item does not exist, then notifications have not yet started being enqueued.

Mandatory