diff --git a/docs/source/decisions/0009-queue-messages.rst b/docs/source/decisions/0009-queue-messages.rst new file mode 100644 index 0000000000..78714b083a --- /dev/null +++ b/docs/source/decisions/0009-queue-messages.rst @@ -0,0 +1,352 @@ +CWMS Queue Messages +=================== + + +Summary +======= + +The CWMS database publishes messages to JMS publish/subscibe queues to notify interesed clients of events sucn as time series CRUD +operations and storage of ratings. A generalized JMS message structure is needed to extend the covered events, while moving +message publication out of the database. + +Opinions +======== + +Opinion 1 +--------- + +Summary: Extend existing queue structure as described below. + +Author: Mike Perryman + +**Standards** + +Continue using ``javax.jms.MapMessage`` with the following characteristics to encapsulate notifications + +1. Every message has a ``String`` value named¹ ``'type'``, which specifies the message type². +2. Every message has a ``String`` value named ``'office_id'`` which specifies the office performing the action and/or owning + the data being referenced. +3. If the data being referenced has a text identifier, it is specified in a ``String`` value named 'xxx_id' + (e.g., ``'ts_id``', ``'rating_id'``) +4. If the data being referenced has a numeric code in the database, and that code is necessary for efficient post-notification + operations, it may be specified in a ``long`` value named ``xxx_code`` (e.g., ``'ts_code'``). Otherwise, the + code values should not be included in the message. +5. Any date/time values to be included in a message (e.g., ``'start_time'``, ``'end_time'``, ``'version_date'``) should be specified + as ``long`` values and should be in milliseconds into the Unix epoch (i.e., Java milliseconds) +6. Any boolean values to be included in a message should be specified as ``boolean`` values.³ + +¹ Current message value names are specified in ``snake_case`` (e.g., ``'type'``, ``'office_id'``, ``'ts_id'``) + +² Current message ``'type'`` values are specied in Pascal case (e.g., ``'TSCreated'``, ``'RatingStored'``) + +³ Note that existing messages may not follow this standard. + +**Existing Messages** + ++---------------+------------------+--------------------------------------------------------------------------+ +| Message Type | Queue Used | Structure | ++===============+==================+==========================================================================+ +| TSCreated | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSCreated'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| TSDeleted | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSDeleted'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| TSRenamed | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSRenamed'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The old time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'new_ts_id'`` | The new time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| TSDataStored | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSDataStored'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'start_time'`` | DATE_TIME of first value | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'end_time'`` | DATE_TIME of last value | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'version_date'`` | VERSION_DATE of values | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'store_time'`` | DATA_ENTRY_DATE of values | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'store_rule'`` | The store rule used | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| TSDataStored | XXX_REALTIME_OPS | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSDataStored'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'start_time'`` | DATE_TIME of first value | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'end_time'`` | DATE_TIME of last value | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| TSDataDeleted | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'TSDataDeleted'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'ts_id'`` | The time series identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'ts_code'`` | The time series numeric code | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'start_time'`` | DATE_TIME of first value | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'end_time'`` | DATE_TIME of last value | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'version_date'`` | VERSION_DATE of values | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'deleted_time'`` | The time values were deleted | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| RatingStored | XXX_TS_STORED | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'RatingStored'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'active'`` | The ACTIVE_FLAG ('T'/'F') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'is_virtual'`` | is a virtual rating | | +| | | | | | ('true'/'false') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'is_transitional'`` | is a transitional rating | | +| | | | | | ('true'/'false') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'create_date'`` | The date/time the rating was | | +| | | | | | stored to the database | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'effective_date'`` | The date/time the rating came | | +| | | | | | into effect | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'transition_date'`` | The date/time to begin | | +| | | | | | transition from the previous | | +| | | | | | rating | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| RatingStored | XXX_REALTIME_OPS | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'RatingStored'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office_id'`` | The office identifier | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'active'`` | The ACTIVE_FLAG ('T'/'F') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'is_virtual'`` | is a virtual rating | | +| | | | | | ('true'/'false') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'is_transitional'`` | is a transitional rating | | +| | | | | | ('true'/'false') | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'create_date'`` | The date/time the rating was | | +| | | | | | stored to the database | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'effective_date'`` | The date/time the rating came | | +| | | | | | into effect | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'transition_date'`` | The date/time to begin | | +| | | | | | transition from the previous | | +| | | | | | rating | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| Status | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'Status'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office publishing the msg | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project assoc with the message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the msg | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'source_id'``¹ | A souce identifier associated | | +| | | | | | with the message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'time_series_id'``¹ | A time series identifier assoc | | +| | | | | | with the message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'start_time'``¹ | A start time associated with | | +| | | | | | the message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'end_time'``¹ | An end time associated with | | +| | | | | | the message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | +| | | ¹ This value is optional depending on the purpose of the message | ++---------------+------------------+--------------------------------------------------------------------------+ +| project lock | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| requested | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'RequestAction'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'action'`` | ``'unlock project'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office of the project | | +| | | | | | to be unlocked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project to be unlocked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | request | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the | | +| | | | | | request | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``long`` | ``'force_time'`` | The time at which the project | | +| | | | | | lock will be forcibly revoked | | +| | | | | | if no reply (release or | | +| | | | | | denial) is received | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| project lock | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| released | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'State'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'old_state'`` | ``'locked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'new_state'`` | ``'unlocked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'action'`` | ``'lock released'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office of the unlocked | | +| | | | | | project | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project that has been unlocked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the msg | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| project lock | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| acquired | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'State'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'old_state'`` | ``'unlocked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'new_state'`` | ``'locked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'action'`` | ``'lock acquired'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office of the locked proj | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project that has been locked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the msg | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| project lock | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| request | | | Value Type | Value Name | Value | | +| denied | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'State'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'response'`` | ``'request denied'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'action'`` | ``'unlock project'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office of the project | | +| | | | | | requested to be unlocked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project requested to be | | +| | | | | | unlocked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ +| project lock | XXX_STATUS | +-------------+-----------------------+--------------------------------+ | +| revoked | | | Value Type | Value Name | Value | | +| | | +=============+=======================+================================+ | +| | | | ``String`` | ``'type'`` | ``'State'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'old_state'`` | ``'locked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'new_state'`` | ``'unlocked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'action'`` | ``'lock revoked'`` | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'office'`` | The office of the project | | +| | | | | | whose lock is revoked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'project'`` | The location identifier of the | | +| | | | | | project whose lock is revoked | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'application'`` | The application publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | +| | | | ``String`` | ``'user'`` | The user publishing the | | +| | | | | | message | | +| | | +-------------+-----------------------+--------------------------------+ | ++---------------+------------------+--------------------------------------------------------------------------+ + + +Decision Status +=============== + +Status: request for comments + +References +==========