(JP) Add doc about subscription alterationType feature (telefonicaid#…

…4084)

doc/manuals.jp/admin/database_model.md

@@ -245,6 +245,7 @@ Orion Context Broker は、データベース内で次のサブセクション
     ことがない場合は存在しません
 -   **maxFailsLimit**: 接続試行の最大制限を指定するために使用されるオプションのフィールド。これにより、失敗した通知の数に達すると、サブスクリプションは自動的に非アクティブ状態に移行します
 -   **failsCounter**: サブスクリプションに関連付けられた連続して失敗した通知の数。これは、通知の試行が失敗するたびに1つずつ増加します。通知の試行が成功すると、0にリセットされます
+-   **altTypes**: サブスクリプションに関連付けられた変更タイプ (alteration types) のリストを含む配列。フィールドが含まれていない場合は、デフォルトが想定されます ([このドキュメント](../user/subscriptions_alttype.md)を確認してください)
 
 サンプルドキュメント :
 

doc/manuals.jp/devel/subscriptionCache.md

@@ -50,32 +50,33 @@ Broker が起動すると、サブスクリプション・キャッシュには
 (subCache.h ファイルのコード参照を確認してください):
 
 ```
-  std::vector<EntityInfo*>    entityIdInfos;
-  std::vector<std::string>    attributes;
-  std::vector<std::string>    metadata;
-  std::vector<std::string>    notifyConditionV;
-  char*                       tenant;
-  char*                       servicePath;
-  char*                       subscriptionId;
-  int64_t                     failsCounter;
-  int64_t                     maxFailsLimit;
-  int64_t                     throttling;
-  int64_t                     expirationTime;
-  int64_t                     lastNotificationTime;
-  std::string                 status;
-  double                      statusLastChange;
-  int64_t                     count;
-  RenderFormat                renderFormat;
-  SubscriptionExpression      expression;
-  bool                        blacklist;
-  bool                        onlyChanged;
-  ngsiv2::HttpInfo            httpInfo;
-  ngsiv2::MqttInfo            mqttInfo;
-  int64_t                     lastFailure;  // timestamp of last notification failure
-  int64_t                     lastSuccess;  // timestamp of last successful notification
-  std::string                 lastFailureReason;
-  int64_t                     lastSuccessCode;
-  struct CachedSubscription*  next;         // The cache is a linked list of CachedSubscription ...
+  std::vector<EntityInfo*>         entityIdInfos;
+  std::vector<std::string>         attributes;
+  std::vector<std::string>         metadata;
+  std::vector<std::string>         notifyConditionV;
+  std::vector<ngsiv2::SubAltType>  subAltTypeV;
+  char*                            tenant;
+  char*                            servicePath;
+  char*                            subscriptionId;
+  int64_t                          failsCounter;
+  int64_t                          maxFailsLimit;
+  int64_t                          throttling;
+  int64_t                          expirationTime;
+  int64_t                          lastNotificationTime;
+  std::string                      status;
+  double                           statusLastChange;
+  int64_t                          count;
+  RenderFormat                     renderFormat;
+  SubscriptionExpression           expression;
+  bool                             blacklist;
+  bool                             onlyChanged;
+  ngsiv2::HttpInfo                 httpInfo;
+  ngsiv2::MqttInfo                 mqttInfo;
+  int64_t                          lastFailure;  // timestamp of last notification failure
+  int64_t                          lastSuccess;  // timestamp of last successful notification
+  std::string                      lastFailureReason;
+  int64_t                          lastSuccessCode;
+  struct CachedSubscription*       next;        // The cache is a linked list of CachedSubscription ...
 ```
 
 <a name="special-subscription-fields"></a>

doc/manuals.jp/user/README.md

@@ -22,7 +22,8 @@
   * [Context broker のフェデレーション](federation.md) (Context broker federation)
   * [禁止されている文字](forbidden_characters.md) (Forbidden characters)
   * [ペイロードでの正規表現の使用](regex_in_payload.md) (Using regular expressions in payloads)
-  * [Onseshot サブスクリプション](oneshot_subscription.md)
+  * [Oneshot サブスクリプション](oneshot_subscription.md)
+  * [変更タイプ (alteration type) に基づくサブスクリプション](subscriptions_alttype.md)
   * [セキュリティの考慮事項](security.md) (Security considerations)
   * [Docker](docker.md)
   * [NGSIv2 実装ノート](ngsiv2_implementation_notes.md) (NGSIv2 Implementation Notes)

doc/manuals.jp/user/ngsiv2_implementation_notes.md

@@ -19,6 +19,7 @@
 * [通知スロットリング](#notification-throttling)
 * [異なる属性型間の順序付け](#ordering-between-different-attribute-value-types)
 * [Oneshot サブスクリプション](#oneshot-subscriptions)
+* [変更タイプ (alteration type) に基づくサブスクリプション](#subscriptions-based-in-alteration-type)
 * [ペイロードなしのカスタム通知](#custom-notifications-without-payload)
 * [MQTT 通知](#mqtt-notifications)
 * [変更された属性のみを通知](#notify-only-attributes-that-change)
@@ -420,6 +421,17 @@ Orionは、NGSIv2 仕様のサブスクリプション用に定義された `sta
 
 [トップ](#top)
 
+<a name="subscriptions-based-in-alteration-type"></a>
+## 変更タイプ (alteration type) に基づくサブスクリプション
+
+NGSIv2 の仕様に従ってサブスクリプションの `conditions` フィールドで許可されるサブフィールドとは別に、
+Orionは `alterationTypes` フィールドをサポートして、サブスクリプションがトリガーされる変更
+(エンティティの作成、エンティティの変更など) を指定します。
+
+詳細については、[この特定のドキュメント](subscriptions_alttype.md)をご覧ください。
+
+[トップ](#top)
+
 <a name="custom-notifications-without-payload"></a>
 ## ペイロードなしのカスタム通知
 
@@ -578,6 +590,10 @@ NGSIv2 仕様に含まれるものに対する追加の URI パラメータ・
 * `PUT /v2/entities/E/attrs/A/value?options=forcedUpdate`
 * `PATCH /v2/entities/E/attrs?options=forcedUpdate`
 
+同じ効果については、`entityChange` [変更タイプ](subscriptions_alttype.md) (alteration type)
+も確認してください。ただし、更新リクエストに `forcedUpdate` オプションが含まれているかどうかに
+関係なく、サブスクリプションに適用されます。
+
 [Top](#top)
 
 <a name="registrations"></a>

doc/manuals.jp/user/subscriptions_alttype.md

@@ -0,0 +1,37 @@
+# 変更タイプ (alteration type) に基づくサブスクリプション
+
+デフォルトでは、エンティティの作成または実際の更新操作中にトリガーされた条件 (サブスクリプションの
+`subject` フィールドと `conditions` フィールドで表現されます。たとえば、対象となるエンティティ、
+チェックする属性のリスト、フィルター式など) が発生すると、サブスクリプションがトリガーされます
+(つまり、サブスクリプションに関連付けられた通知が送信されます)。
+
+ただし、このデフォルトの動作を変更して、たとえば、エンティティが作成されたとき、またはエンティティ
+が削除されたときにのみ通知を送信できるようにすることができますが、エンティティが更新されたときは
+送信できません。
+
+特に、`conditions` のサブフィールドとして `alterationTypes` フィールドが使用されます。
+このフィールドの値は、サブスクリプションがトリガーされる変更タイプのリストを要素が指定する配列です。
+現時点では、次の変更タイプがサポートされています:
+
+* `entityUpdate`: サブスクリプションの対象となるエンティティが更新されるたびに通知が送信されます
+  (エンティティが実際に変更されたかどうかは関係ありません)
+* `entityChange`: サブスクリプションの対象となるエンティティが更新され、実際に変更されるたびに通知が
+  送信されます (または、実際の更新ではないが、更新要求で [`forcedUpdate` オプション](ngsiv2_implementation_notes.md#forcedupdate-option)
+  が使用されている場合)
+* `entityCreate`: サブスクリプションの対象となるエンティティが作成されるたびに通知が送信されます
+* `entityDelete`: サブスクリプションの対象となるエンティティが削除されるたびに通知が送信されます
+
+たとえば:
+
+```
+  "conditions": {
+    "alterationTypes": [ "entityCreate", "entityDelete" ],
+    ...
+  }
+```
+
+エンティティの作成または削除が行われたときにサブスクリプションがトリガーされますが、更新が
+行われたときはトリガーされません。`alterationTypes` 配列の要素は、OR の意味で解釈されます。
+
+デフォルトの `alterationTypes` (つまり、サブスクリプションが明示的に指定していないもの) は
+`["entityCreate", "entityChange"]` です。