Merge branch 'master' into issue1492-prelanding

CHANGES_NEXT_RELEASE

@@ -1,3 +1,5 @@
 - Fix: allow limit=0 in all paginated operations in the NGSIv2 API (entities, entity types, subscriptions and registrations) (#1492)
 - Add: conditions.alterationTypes subscription fuctionality (#1494)
+- Add: alterationType built-in atrribute in notifications (#1494)
+- Fix: covered notifications in subscriptions (#3693)
 - Reference distribution changed RHEL/CentOS 8 to Debian 11

doc/manuals.jp/admin/database_model.md

@@ -247,6 +247,11 @@ Orion Context Broker は、データベース内で次のサブセクション
 -   **failsCounter**: サブスクリプションに関連付けられた連続して失敗した通知の数。これは、通知の試行が失敗するたびに1つずつ増加します。通知の試行が成功すると、0にリセットされます
 -   **altTypes**: サブスクリプションに関連付けられた変更タイプ (alteration types) のリストを含む配列。フィールドが含まれていない場合は、デフォルトが想定されます ([このドキュメント](../user/subscriptions_alttype.md)を確認してください)
 
+-   **covered**: すべての `attrs` を通知に含める必要があるか (値がtrueの場合)、トリガー・エンティティに存在するものだけを含める必要があるか
+    (値がfalseの場合、またはフィールドが省略されている場合) を指定するブール・フィールド
+    詳細については、ユーザ・マニュアル・ドキュメントの[対象サブスクリプション・セクション](../user/ngsiv2_implementation_notes.md#covered-subscriptions)
+    を参照してください。
+
 サンプルドキュメント :
 
 ```

doc/manuals.jp/devel/subscriptionCache.md

@@ -70,6 +70,7 @@ Broker が起動すると、サブスクリプション・キャッシュには
   SubscriptionExpression           expression;
   bool                             blacklist;
   bool                             onlyChanged;
+  bool                             covered;
   ngsiv2::HttpInfo                 httpInfo;
   ngsiv2::MqttInfo                 mqttInfo;
   int64_t                          lastFailure;  // timestamp of last notification failure

doc/manuals.jp/user/ngsiv2_implementation_notes.md

@@ -13,6 +13,7 @@
 * [日時サポート](#datetime-support)
 * [ユーザ属性または組み込み名前と一致するメタデータ](#user-attributes-or-metadata-matching-builtin-name)
 * [サブスクリプション・ペイロードの検証](#subscription-payload-validations)
+* [`alterationType` 属性](#alterationtype-attribute)
 * [`actionType` メタデータ](#actiontype-metadata)
 * [`ignoreType` メタデータ](#ignoretype-metadata)
 * [`noAttrDetail` オプション](#noattrdetail-option)
@@ -23,6 +24,7 @@
 * [ペイロードなしのカスタム通知](#custom-notifications-without-payload)
 * [MQTT 通知](#mqtt-notifications)
 * [変更された属性のみを通知](#notify-only-attributes-that-change)
+* [カバード・サブスクリプション (Covered subscriptions)](#covered-subscriptions)
 * [`timeout` サブスクリプション・オプション](#timeout-subscriptions-option)
 * [`lastFailureReason` および `lastSuccessCode` のサブスクリプション・フィールド](#lastfailurereason-and-lastsuccesscode-subscriptions-fields)
 * [`failsCounter` と `maxFailsLimit` サブスクリプション・フィールド](#failscounter-and-maxfailslimit-subscriptions-fields)
@@ -338,6 +340,26 @@ Orion が NGSIv2 サブスクリプション・ペイロードで実装する特
 
 [トップ](#top)
 
+<a name="alterationtype-attribute"></a>
+## `alterationType` 属性
+
+NGSIv2 仕様の "組み込み属性" (Builtin Attributes) セクションで説明されている属性から、Orion は
+`alterationType` 属性を実装します。
+
+この属性は通知でのみ使用でき (`GET /v2/entities?attrs=alterationType` などのクエリでは無視されます)、
+次の値をとることができます:
+
+* `entityCreate` 通知をトリガーする更新がエンティティ作成操作の場合
+* `entityUpdate` 通知をトリガーする更新が更新であったが、実際の変更ではなかった場合
+* `entityChange` 通知をトリガーする更新が実際の変更を伴う更新であった場合
+* `entityDelete` 通知をトリガーする更新がエンティティ削除操作であった場合
+
+この属性のタイプは `Text` です。
+
+この組み込み属性は、[変更タイプに基づくサブスクリプション](subscriptions_alttype.md) 機能に関連しています。
+
+[トップ](#top)
+
 <a name="actiontype-metadata"></a>
 ## `actionType` メタデータ
 
@@ -467,6 +489,71 @@ A のみを修正した場合、A, B, C が通知されます(つまり、トリ
 
 [トップ](#top)
 
+<a name="covered-subscriptions"></a>
+## カバード・サブスクリプション (Covered subscriptions)
+
+`notification` 内の `attrs` フィールドは、サブスクリプションがトリガーされたときに通知に含まれる
+エンティティ属性のサブセットを指定します。デフォルトでは、Orion はエンティティに存在する属性のみを
+通知します。たとえば、サブスクリプションが次のようになっている場合:
+
+```
+"notification": {
+  ...
+  "attrs": [
+    "temperature",
+    "humidity",
+    "brightness"
+  ]
+}
+```
+
+ただし、エンティティには `temperature` 属性と `humidity` 属性しかないため、`brightness`
+属性は通知に含まれません。
+
+このデフォルトの動作は、次のように `true` に設定された `covered` フィールドを使用して変更できます:
+
+```
+"notification": {
+  ...
+  "attrs": [
+    "temperature",
+    "humidity",
+    "brightness"
+  ],
+  "covered": true
+}
+```
+
+この場合、エンティティに存在するかどうかに関係なく、すべての属性が通知に含まれます。存在しないこれらの
+属性 (この例では `brightness`) には、`null` 値 (タイプ `"None"`) が使用されます。
+
+通知が `notification.attrs` フィールドのすべての属性を完全に "カバーする" (covers) という意味で
+"カバーされる" (covered) という用語を使用します。これは、可変の属性セットに対して十分な柔軟性がなく、
+受信したすべての通知で常に同じ着信属性のセットを必要とする通知エンドポイントに役立ちます。
+
+対象となるサブスクリプションには、`notification` に `attrs` の明示的なリストが必要であることに
+注意してください。 したがって、次の場合は無効です:
+
+```
+"notification": {
+  ...
+  "attrs": [],
+  "covered": true
+}
+```
+
+そして、それを使用してサブスクリプションを作成/更新しようとすると、次のような 400 Bad Request エラーが
+発生します:
+
+```
+{
+    "description": "covered true cannot be used if notification attributes list is empty",
+    "error": "BadRequest"
+}
+```
+
+[トップ](#top)
+
 <a name="timeout-subscriptions-option"></a>
 ## `timeout` サブスクリプション・オプション
 

doc/manuals.jp/user/subscriptions_alttype.md

@@ -35,3 +35,6 @@
 
 デフォルトの `alterationTypes` (つまり、サブスクリプションが明示的に指定していないもの) は
 `["entityCreate", "entityChange"]` です。
+
+特定の変更タイプは、[`alterationType` 組み込み属性](ngsiv2_implementation_nodes.md#alterationtype-attribute)
+を使用して通知で取得できます。

doc/manuals/admin/database_model.md

@@ -334,6 +334,9 @@ notifications. It is a number between 0 and 1800000. If defined to 0 or omitted,
 -   **maxFailsLimit**: An optional field used to specify the maximum limit of connection attempts, so when that number of failing notifications is reached, then the subscription passes automatically to inactive state.
 -   **failsCounter**: the number of consecutive failing notifications associated to the subscription. This is increased by one each time a notification attempt fails. It is reset to 0 if a notification attempt successes.
 -   **altTypes**: array with a list of alteration types associated to the subscription. If the field is not included, a default is assumed (check [this document](../user/subscriptions_alttype.md)).
+-   **covered**: a boolean field that specifies if all `attrs` have to be included in notifications (if value is true)
+    or only the ones existing in the triggering entity (if value is false or field is omitted).
+    More information in [covered subscription section in user manual documentation](../user/ngsiv2_implementation_notes.md#covered-subscriptions).
 
 Example document:
 

doc/manuals/devel/subscriptionCache.md

@@ -68,6 +68,7 @@ When the broker starts, the subscription cache is populated with the subscriptio
   SubscriptionExpression           expression;
   bool                             blacklist;
   bool                             onlyChanged;
+  bool                             covered;
   ngsiv2::HttpInfo                 httpInfo;
   ngsiv2::MqttInfo                 mqttInfo;
   int64_t                          lastFailure;  // timestamp of last notification failure

doc/manuals/user/ngsiv2_implementation_notes.md

@@ -13,6 +13,7 @@
 * [Datetime support](#datetime-support)
 * [User attributes or metadata matching builtin name](#user-attributes-or-metadata-matching-builtin-name)
 * [Subscription payload validations](#subscription-payload-validations)
+* [`alterationType` attribute](#alterationtype-attribute)
 * [`actionType` metadata](#actiontype-metadata)
 * [`ignoreType` metadata](#ignoretype-metadata)
 * [`noAttrDetail` option](#noattrdetail-option)
@@ -23,6 +24,7 @@
 * [Custom notifications without payload](#custom-notifications-without-payload)
 * [MQTT notifications](#mqtt-notifications)
 * [Notify only attributes that change](#notify-only-attributes-that-change)
+* [Covered subscriptions](#covered-subscriptions)
 * [`timeout` subscriptions option](#timeout-subscriptions-option)
 * [`lastFailureReason` and `lastSuccessCode` subscriptions fields](#lastfailurereason-and-lastsuccesscode-subscriptions-fields)
 * [`failsCounter` and `maxFailsLimit` subscriptions fields](#failscounter-and-maxfailslimit-subscriptions-fields)
@@ -361,6 +363,25 @@ The particular validations that Orion implements on NGSIv2 subscription payloads
 
 [Top](#top)
 
+## `alterationType` attribute
+
+Appart from the attributes described in the "Builtin Attributes" section in the NGSIv2 specification,
+Orion implements the `alterationType` attribute.
+
+This attribute can be used only in notifications (in queries such `GET /v2/entities?attrs=alterationType`
+is ignored) and can take the following values:
+
+* `entityCreate` if the update that triggers the notification is a entity creation operation
+* `entityUpdate` if the update that triggers the notification was an update but it wasn't an actual change
+* `entityChange` if the update that triggers the notification was an update with an actual change
+* `entityDelete` if the update that triggers the notification was a entity delete operation
+
+The type of this attribute is `Text`
+
+This builtin attribute is related with the [subscriptions based in alteration type](subscriptions_alttype.md) feature.
+
+[Top](#top)
+
 ## `actionType` metadata
 
 From NGSIv2 specification section "Builtin metadata", regarding `actionType` metadata:
@@ -489,6 +510,73 @@ if `onlyChangedAttrs` is `true` and the triggering update only modified A then o
 
 [Top](#top)
 
+## Covered subscriptions
+
+The `attrs` field within `notification` specifies the sub-set of entity attributes to be included in the
+notification when subscription is triggered. By default Orion only notifies attributes that exist
+in the entity. For instance, if subscription is this way:
+
+```
+"notification": {
+  ...
+  "attrs": [
+    "temperature",
+    "humidity",
+    "brightness"
+  ]
+}
+```
+
+but the entity only has `temperature` and `humidity` attributes, then `brightness` attribute is not included
+in notifications.
+
+This default behaviour can be changed using the `covered` field set to `true` this way:
+
+```
+"notification": {
+  ...
+  "attrs": [
+    "temperature",
+    "humidity",
+    "brightness"
+  ],
+  "covered": true
+}
+```
+
+in which case all attributes are included in the notification, no matter if they exist or not in the
+entity. For these attributes that don't exist (`brightness` in this example) the `null`
+value (of type `"None"`) is used.
+
+We use the term "covered" in the sense the notification "covers" completely all the attributes
+in the `notification.attrs` field. It can be useful for those notification endpoints that are
+not flexible enough for a variable set of attributes and needs always the same set of incoming attributes
+in every received notification.
+
+Note that covered subscriptions need an explicit list of `attrs` in `notification`. Thus, the following
+case is not valid:
+
+```
+"notification": {
+  ...
+  "attrs": [],
+  "covered": true
+}
+```
+
+And if you try to create/update a subscription with that you will get a 400 Bad Request error like this:
+
+```
+{
+    "description": "covered true cannot be used if notification attributes list is empty",
+    "error": "BadRequest"
+}
+```
+
+
+[Top](#top)
+
+
 ## `timeout` subscriptions option
 
 Apart from the subscription fields described in NGSIv2 specification for `GET /v2/subscriptions` and

doc/manuals/user/subscriptions_alttype.md

@@ -35,3 +35,6 @@ update takes place. The elements in the `alterationTypes` array are interpreted
 
 Default `alterationTypes` (i.e. the one for subscription not explicitly specifying it)
 is `["entityCreate", "entityChange"]`.
+
+The particular alteration type can be got in notifications using the
+[`alterationType` builtin attribute](ngsiv2_implementation_nodes.md#alterationtype-attribute).