Loading md/clause-16.md +116 −101 Original line number Diff line number Diff line Loading @@ -2,24 +2,25 @@ ## 16.1 Introduction Clause+++root describes all operations related to snapshots. Snapshots allow creating a consistent (within the limits of the possibly distributed NGSI-LD system) view of the Entities selected by the queries. It allows consuming these Entities, but also using provision operations for making available predicted and simulated information, e.g. as needed for digital twins. Implementing the [Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. Clause+++root describes all operations related to [Snapshots]{.HTML-Keyboard}. [Snapshots]{.HTML-Keyboard} allow creating a consistent (within the limits of the possibly distributed NGSI-LD system) view of the Entities selected by the queries. It allows consuming these Entities, but also using provision operations for making available predicted and simulated information, e.g. as needed for digital twins. Implementing the [Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. ## 16.2 Create Snapshot ### 16.2.1 Description This operation allows creating a new snapshot. This operation allows for the creation of a new [Snapshot]{.HTML-Keyboard}. ### 16.2.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can create a new snapshot to have a more consistent basis for queries on the persisted Entity information as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can create a new [Snapshot]{.HTML-Keyboard} to have a more consistent basis for queries on the persisted Entity information as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -35,7 +36,7 @@ Figure: Create Snapshot use case ### 16.2.3 Input data - A JSON-LD document conforming to the Snapshot data type as mandated by - A JSON-LD document conforming to the _Snapshot_ data type as mandated by clause+++clause-5+++root.2.6.5.4. ### 16.2.4 Behaviour Loading @@ -43,24 +44,25 @@ Figure: Create Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD endpoint already knows about this Snapshot, as there is an existing Snapshot whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - If the NGSI-LD endpoint already knows about this [Snapshot]{.HTML-Keyboard}, as there is an existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} document does not include a [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. - If the Snapshot document does not include a _`snapshotPriority`_, the _`snapshotPriority`_ shall be set to 5. - The request returns, confirming the creation of the snapshot to the requesting [Context Consumer]{.HTML-Keyboard}, providing the Snapshot identifier. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - If the [Snapshot]{.HTML-Keyboard} document does not include a _`snapshotPriority`_, the _`snapshotPriority`_ shall be set to 5. - The request returns, confirming the creation of the [Snapshot]{.HTML-Keyboard} to the requesting [Context Consumer]{.HTML-Keyboard}, providing the [Snapshot]{.HTML-Keyboard} identifier. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - Implementations shall execute the Queries specified in the _`snapshotQueries`_ member, in each case following the behaviour described in Clause+++clause-10+++root.4.3.4. If the size of the respective results require Loading @@ -84,23 +86,25 @@ Figure: Create Snapshot use case result, to ["empty"]{.HTML-Code}, if at least one query or temporal query was executed successfully, but without yielding a result, and to ["failure"]{.HTML-Code} otherwise. - If the _`endpoint`_ member is present, a Snapshot notification is sent as described in Clause+++root.8. - If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} notification is sent as described in Clause+++root.8. ### 16.2.5 Output data A URI identifying the newly created Snapshot. A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.3 Clone Snapshot ### 16.3.1 Description This operation allows cloning a snapshot stored in an NGSI-LD system. This operation allows cloning a [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system. ### 16.3.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can clone an existing snapshot stored in an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can clone an existing [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -116,8 +120,8 @@ Figure: Clone Snapshot use case ### 16.3.3 Input data - A URI identifying the Snapshot to be cloned. - A JSON-LD document conforming to the Snapshot data type as mandated by - A URI identifying the [Snapshot]{.HTML-Keyboard} to be cloned. - A JSON-LD document conforming to the _Snapshot_ data type as mandated by Clause+++clause-5+++root.2.6.5.4, but without _`snapshotQueriesDetails`_ and _`snapshotQueriesTemporalDetails`_ elements. Loading @@ -126,47 +130,50 @@ Figure: Clone Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier of the Snapshot to be cloned is not found, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - If the Snapshot document includes a Snapshot identifier and there is an existing Snapshot whose id (URI) is equivalent, an error of type - If the identifier of the [Snapshot]{.HTML-Keyboard} to be cloned is not found, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} document includes a [Snapshot]{.HTML-Keyboard} identifier and there is an existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - If the [Snapshot]{.HTML-Keyboard} document does not include a [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps of the clone are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member of the clone is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. - The request returns, confirming the creation of the cloned Snapshot to the requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - All Entity and Temporal Evolution of Entity data that is part of the Snapshot to be cloned is copied to the clone Snapshot. - The request returns, confirming the creation of the cloned [Snapshot]{.HTML-Keyboard} to the requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - All Entity and Temporal Evolution of Entity data that is part of the [Snapshot]{.HTML-Keyboard} to be cloned is copied to the clone [Snapshot]{.HTML-Keyboard}. - After all information has been stored, the _`snapshotStatus`_ member is set to ["success"]{.HTML-Code}, if cloning was successful, and to ["failure"]{.HTML-Code} otherwise. - If the _`endpoint`_ member is present, a Snapshot notification is sent as described in Clause+++root.8. - If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} notification is sent as described in Clause+++root.8. ### 16.3.5 Output data A URI identifying the newly created Snapshot. A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.4 Retrieve Snapshot status ### 16.4.1 Description This operation allows retrieving the status of a Snapshot stored in an NGSI-LD system. This operation allows retrieving the status of a [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system. ### 16.4.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a Snapshot from an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a [Snapshot]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -182,32 +189,34 @@ Figure: Retrieve Snapshot Status use case ### 16.4.3 Input data Snapshot Id (URI) of the Snapshot whose status is to be retrieved. [Snapshot]{.HTML-Keyboard} Id (URI) of the [Snapshot]{.HTML-Keyboard} whose status is to be retrieved. ### 16.4.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier provided does not correspond to any existing Snapshot in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise, implementations shall retrieve the Snapshot status and return it to the caller. - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier provided does not correspond to any existing [Snapshot]{.HTML-Keyboard} in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise, implementations shall retrieve the [Snapshot]{.HTML-Keyboard} status and return it to the caller. ### 16.4.5 Output data A JSON-LD object representing the Snapshot status as mandated by Clause+++clause-5+++root.2.6.5.4. A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated by Clause+++clause-5+++root.2.6.5.4. ## 16.5 Update Snapshot status ### 16.5.1 Description This operation allows updating an existing Snapshot. This operation allows updating an existing [Snapshot]{.HTML-Keyboard}. ### 16.5.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can update an existing Snapshot within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can update an existing [Snapshot]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -223,15 +232,16 @@ Figure: Update Snapshot Status use case ### 16.5.3 Input data - Snapshot Id (URI), the target Snapshot. - A JSON-LD document representing a Snapshot Fragment - [Snapshot]{.HTML-Keyboard} Id (URI), the target [Snapshot]{.HTML-Keyboard}. - A JSON-LD document representing a [Snapshot]{.HTML-Keyboard} Fragment ### 16.5.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD System does not know about the target Snapshot, because there is no existing Snapshot whose id (URI) is equivalent, an error of type - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD System does not know about the target [Snapshot]{.HTML-Keyboard}, because there is no existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Execute the behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD validation. Loading @@ -241,24 +251,24 @@ Figure: Update Snapshot Status use case [BadRequestData]{.HTML-Error} shall be raised. - Term to URI expansion of Attribute names shall be observed as mandated by Clause+++clause-8+++root.2.4. - Then, implementations shall modify the target Snapshot as mandated by Clause+++clause-8+++root.4.2. - Then, implementations shall modify the target [Snapshot]{.HTML-Keyboard} as mandated by Clause+++clause-8+++root.4.2. ### 16.5.5 Output data A JSON-LD object representing the Snapshot status as mandated by Clause+++clause-5+++root.2.6.5.4. A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated by Clause+++clause-5+++root.2.6.5.4. ## 16.6 Delete Snapshot ### 16.6.1 Description This operation allows deleting an existing Snapshot. This operation allows deleting an existing [Snapshot]{.HTML-Keyboard}. ### 16.6.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can delete a Snapshot within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can delete a [Snapshot]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -274,16 +284,17 @@ Figure: Delete Snapshot use case ### 16.6.3 Input data - A Snapshot identifier (URI), the target Snapshot. - A [Snapshot]{.HTML-Keyboard} identifier (URI), the target [Snapshot]{.HTML-Keyboard}. ### 16.6.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the Snapshot id provided does not correspond to any existing Snapshot in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise implementations shall delete the Snapshot. - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} id provided does not correspond to any existing [Snapshot]{.HTML-Keyboard} in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise implementations shall delete the [Snapshot]{.HTML-Keyboard}. ### 16.6.5 Output data Loading @@ -293,12 +304,12 @@ None. ### 16.7.1 Description This operation allows purging selected Snapshots. This operation allows purging selected [Snapshots]{.HTML-Keyboard}. ### 16.7.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can purge Snapshots within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can purge [Snapshots]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -314,8 +325,8 @@ Figure: Purge Snapshots use case ### 16.7.3 Input data - An NGSI-LD Query to select fitting Snapshots to be purged based on members of the Snapshot data type (see table 5.2.6.5.4-1), as per - An NGSI-LD Query to select fitting [Snapshots]{.HTML-Keyboard} to be purged based on members of the _Snapshot_ data type (see table 5.2.6.5.4-1), as per Clause+++clause-7+++root.2.3. ### 16.7.4 Behaviour Loading @@ -323,7 +334,8 @@ Figure: Purge Snapshots use case - If the NGSI-LD Query is not present or it is not a valid as per Clause+++clause-7+++root.2.3, restricted to members of the Snapshot data type, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - Implementations shall purge the Snapshots fitting the NGSI-LD Query. - Implementations shall purge the [Snapshots]{.HTML-Keyboard} fitting the NGSI-LD Query. ### 16.7.5 Output data Loading @@ -331,21 +343,24 @@ None. ## 16.8 Snapshot status notification behaviour A Snapshot status notification allows the subscriber, typically the creator of the Snapshot, to be notified when the Snapshot is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour: A [Snapshot]{.HTML-Keyboard} status notification allows the subscriber, typically the creator of the [Snapshot]{.HTML-Keyboard}, to be notified when the [Snapshot]{.HTML-Keyboard} is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour: - SnapshotNotification (Clause+++clause-5+++root.2.6.9.3) messages can only be sent, if the _`endpoint`_ member is set. - SnapshotNotification messages are sent to the URI specified in the _`endpoint`_ member of the Snapshot status. - The information in the _`receiverInfo`_ member of the Snapshot status shall be added to the SnapshotNotification message in the way required for the binding protocol. - Snapshot Status Notifications shall be sent after all the specified Snapshot queries have been executed, the query results have been integrated and the Snapshot status has been updated accordingly. - Snapshot status Notifications shall also be sent after any Snapshot status update, e.g. informing about the actual updated _`expiresAt`_ timestamp. _`endpoint`_ member of the [Snapshot]{.HTML-Keyboard} status. - The information in the _`receiverInfo`_ member of the [Snapshot]{.HTML-Keyboard} status shall be added to the SnapshotNotification message in the way required for the binding protocol. - [Snapshot]{.HTML-Keyboard} Status Notifications shall be sent after all the specified [Snapshot]{.HTML-Keyboard} queries have been executed, the query results have been integrated and the [Snapshot]{.HTML-Keyboard} status has been updated accordingly. - [Snapshot]{.HTML-Keyboard} status Notifications shall also be sent after any [Snapshot]{.HTML-Keyboard} status update, e.g. informing about the actual updated _`expiresAt`_ timestamp. - The SnapshotNotification shall be as mandated by Clause+++clause-5+++root.2.6.9.3. md/clause-7.md +13 −12 Original line number Diff line number Diff line Loading @@ -105,10 +105,10 @@ to: describe them, defined when [Context Sources]{.HTML-Keyboard} are registered (target is the name of a [Context Source]{.HTML-Keyboard} Property member of the CSourceRegistration, see Table 5.2.9-1). - filter out [Snapshots]{.HTML-Keyboard} by the values of the Snapshot data type members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of the members defined for Snapshot in Table 5.2.43-1 are allowed values for [AttrName]{.HTML-Sample}. - filter out [Snapshots]{.HTML-Keyboard} by the values of the _Snapshot_ data type members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of the members defined for [Snapshot]{.HTML-Keyboard} in Table 5.2.43-1 are allowed values for [AttrName]{.HTML-Sample}. #### 7.2.3.2 Query Language Definition Loading Loading @@ -2107,11 +2107,12 @@ type [NoMultiTenantSupport]{.HTML-Error} Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables "freezing" the result by retrieving all results immediately and persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and analyse the Snapshot in a much more consistent way. making them incomparable. To get more consistent results, the [Snapshot]{.HTML-Keyboard} concept is introduced, which can be optionally implemented by Context Brokers. It enables "freezing" the result by retrieving all results immediately and persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and analyse the [Snapshot]{.HTML-Keyboard} in a much more consistent way. This is especially relevant for distributed cases, where information initially was distributed across multiple [Context Brokers]{.HTML-Keyboard} and [Context Loading Loading @@ -2142,9 +2143,9 @@ protocol binding specific. The [Snapshot]{.HTML-Keyboard} concept is orthogonal to the [Tenant]{.HTML-Keyboard} concept (see clause 7.8). [Snapshots]{.HTML-Keyboard} can also be created on [Tenants]{.HTML-Keyboard}. To execute an operation on a Snapshot created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API operation. [Snapshot]{.HTML-Keyboard} created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API operation. If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be Loading md/clause-8.md +3 −3 Original line number Diff line number Diff line Loading @@ -725,6 +725,6 @@ If the request limits the execution of the operation to the local scope, [Context Source Registrations]{.HTML-Keyboard} from the [Context Registry]{.HTML-Keyboard} will not be used. Operations on a Snapshot (see Clause+++clause-7+++7.9) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations. Operations on a [Snapshot]{.HTML-Keyboard} (see Clause+++clause-7+++7.9) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations. Loading
md/clause-16.md +116 −101 Original line number Diff line number Diff line Loading @@ -2,24 +2,25 @@ ## 16.1 Introduction Clause+++root describes all operations related to snapshots. Snapshots allow creating a consistent (within the limits of the possibly distributed NGSI-LD system) view of the Entities selected by the queries. It allows consuming these Entities, but also using provision operations for making available predicted and simulated information, e.g. as needed for digital twins. Implementing the [Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. Clause+++root describes all operations related to [Snapshots]{.HTML-Keyboard}. [Snapshots]{.HTML-Keyboard} allow creating a consistent (within the limits of the possibly distributed NGSI-LD system) view of the Entities selected by the queries. It allows consuming these Entities, but also using provision operations for making available predicted and simulated information, e.g. as needed for digital twins. Implementing the [Snapshot API]{.HTML-Keyboard} is optional for NGSI-LD systems. ## 16.2 Create Snapshot ### 16.2.1 Description This operation allows creating a new snapshot. This operation allows for the creation of a new [Snapshot]{.HTML-Keyboard}. ### 16.2.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can create a new snapshot to have a more consistent basis for queries on the persisted Entity information as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can create a new [Snapshot]{.HTML-Keyboard} to have a more consistent basis for queries on the persisted Entity information as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -35,7 +36,7 @@ Figure: Create Snapshot use case ### 16.2.3 Input data - A JSON-LD document conforming to the Snapshot data type as mandated by - A JSON-LD document conforming to the _Snapshot_ data type as mandated by clause+++clause-5+++root.2.6.5.4. ### 16.2.4 Behaviour Loading @@ -43,24 +44,25 @@ Figure: Create Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD endpoint already knows about this Snapshot, as there is an existing Snapshot whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - If the NGSI-LD endpoint already knows about this [Snapshot]{.HTML-Keyboard}, as there is an existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} document does not include a [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. - If the Snapshot document does not include a _`snapshotPriority`_, the _`snapshotPriority`_ shall be set to 5. - The request returns, confirming the creation of the snapshot to the requesting [Context Consumer]{.HTML-Keyboard}, providing the Snapshot identifier. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - If the [Snapshot]{.HTML-Keyboard} document does not include a _`snapshotPriority`_, the _`snapshotPriority`_ shall be set to 5. - The request returns, confirming the creation of the [Snapshot]{.HTML-Keyboard} to the requesting [Context Consumer]{.HTML-Keyboard}, providing the [Snapshot]{.HTML-Keyboard} identifier. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - Implementations shall execute the Queries specified in the _`snapshotQueries`_ member, in each case following the behaviour described in Clause+++clause-10+++root.4.3.4. If the size of the respective results require Loading @@ -84,23 +86,25 @@ Figure: Create Snapshot use case result, to ["empty"]{.HTML-Code}, if at least one query or temporal query was executed successfully, but without yielding a result, and to ["failure"]{.HTML-Code} otherwise. - If the _`endpoint`_ member is present, a Snapshot notification is sent as described in Clause+++root.8. - If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} notification is sent as described in Clause+++root.8. ### 16.2.5 Output data A URI identifying the newly created Snapshot. A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.3 Clone Snapshot ### 16.3.1 Description This operation allows cloning a snapshot stored in an NGSI-LD system. This operation allows cloning a [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system. ### 16.3.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can clone an existing snapshot stored in an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can clone an existing [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -116,8 +120,8 @@ Figure: Clone Snapshot use case ### 16.3.3 Input data - A URI identifying the Snapshot to be cloned. - A JSON-LD document conforming to the Snapshot data type as mandated by - A URI identifying the [Snapshot]{.HTML-Keyboard} to be cloned. - A JSON-LD document conforming to the _Snapshot_ data type as mandated by Clause+++clause-5+++root.2.6.5.4, but without _`snapshotQueriesDetails`_ and _`snapshotQueriesTemporalDetails`_ elements. Loading @@ -126,47 +130,50 @@ Figure: Clone Snapshot use case - If the data types, cardinalities and restrictions expressed by Clause+++clause-5+++root.2.6.5.4 are not met, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier of the Snapshot to be cloned is not found, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - If the Snapshot document includes a Snapshot identifier and there is an existing Snapshot whose id (URI) is equivalent, an error of type - If the identifier of the [Snapshot]{.HTML-Keyboard} to be cloned is not found, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} document includes a [Snapshot]{.HTML-Keyboard} identifier and there is an existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [AlreadyExists]{.HTML-Error} shall be raised. - If the Snapshot document does not include a Snapshot identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - If the [Snapshot]{.HTML-Keyboard} document does not include a [Snapshot]{.HTML-Keyboard} identifier, a new locally unique identifier (URI) shall be automatically generated by the implementation. - The _`createdAt`_ and _`modifiedAt`_ timestamps of the clone are set to the current time of the NGSI-LD system. - The _`snapshotStatus`_ member of the clone is set to _`preparation`_. - The _`expiresAt`_ member shall be set, taking into account the _`snapshotLifetime`_ requested, but applying the configured limit of the NGSI-LD system. - The request returns, confirming the creation of the cloned Snapshot to the requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - All Entity and Temporal Evolution of Entity data that is part of the Snapshot to be cloned is copied to the clone Snapshot. - The request returns, confirming the creation of the cloned [Snapshot]{.HTML-Keyboard} to the requesting [Context Consumer]{.HTML-Keyboard}. The status is accessible to the [Context Consumer]{.HTML-Keyboard} as described in Clause+++root.4. The following is executed in the background. - All Entity and Temporal Evolution of Entity data that is part of the [Snapshot]{.HTML-Keyboard} to be cloned is copied to the clone [Snapshot]{.HTML-Keyboard}. - After all information has been stored, the _`snapshotStatus`_ member is set to ["success"]{.HTML-Code}, if cloning was successful, and to ["failure"]{.HTML-Code} otherwise. - If the _`endpoint`_ member is present, a Snapshot notification is sent as described in Clause+++root.8. - If the _`endpoint`_ member is present, a [Snapshot]{.HTML-Keyboard} notification is sent as described in Clause+++root.8. ### 16.3.5 Output data A URI identifying the newly created Snapshot. A URI identifying the newly created [Snapshot]{.HTML-Keyboard}. ## 16.4 Retrieve Snapshot status ### 16.4.1 Description This operation allows retrieving the status of a Snapshot stored in an NGSI-LD system. This operation allows retrieving the status of a [Snapshot]{.HTML-Keyboard} stored in an NGSI-LD system. ### 16.4.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a Snapshot from an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can retrieve the status of a [Snapshot]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -182,32 +189,34 @@ Figure: Retrieve Snapshot Status use case ### 16.4.3 Input data Snapshot Id (URI) of the Snapshot whose status is to be retrieved. [Snapshot]{.HTML-Keyboard} Id (URI) of the [Snapshot]{.HTML-Keyboard} whose status is to be retrieved. ### 16.4.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier provided does not correspond to any existing Snapshot in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise, implementations shall retrieve the Snapshot status and return it to the caller. - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the identifier provided does not correspond to any existing [Snapshot]{.HTML-Keyboard} in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise, implementations shall retrieve the [Snapshot]{.HTML-Keyboard} status and return it to the caller. ### 16.4.5 Output data A JSON-LD object representing the Snapshot status as mandated by Clause+++clause-5+++root.2.6.5.4. A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated by Clause+++clause-5+++root.2.6.5.4. ## 16.5 Update Snapshot status ### 16.5.1 Description This operation allows updating an existing Snapshot. This operation allows updating an existing [Snapshot]{.HTML-Keyboard}. ### 16.5.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can update an existing Snapshot within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can update an existing [Snapshot]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -223,15 +232,16 @@ Figure: Update Snapshot Status use case ### 16.5.3 Input data - Snapshot Id (URI), the target Snapshot. - A JSON-LD document representing a Snapshot Fragment - [Snapshot]{.HTML-Keyboard} Id (URI), the target [Snapshot]{.HTML-Keyboard}. - A JSON-LD document representing a [Snapshot]{.HTML-Keyboard} Fragment ### 16.5.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD System does not know about the target Snapshot, because there is no existing Snapshot whose id (URI) is equivalent, an error of type - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the NGSI-LD System does not know about the target [Snapshot]{.HTML-Keyboard}, because there is no existing [Snapshot]{.HTML-Keyboard} whose id (URI) is equivalent, an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Execute the behaviour defined in Clause+++clause-8+++root.2.3 on JSON-LD validation. Loading @@ -241,24 +251,24 @@ Figure: Update Snapshot Status use case [BadRequestData]{.HTML-Error} shall be raised. - Term to URI expansion of Attribute names shall be observed as mandated by Clause+++clause-8+++root.2.4. - Then, implementations shall modify the target Snapshot as mandated by Clause+++clause-8+++root.4.2. - Then, implementations shall modify the target [Snapshot]{.HTML-Keyboard} as mandated by Clause+++clause-8+++root.4.2. ### 16.5.5 Output data A JSON-LD object representing the Snapshot status as mandated by Clause+++clause-5+++root.2.6.5.4. A JSON-LD object representing the [Snapshot]{.HTML-Keyboard} status as mandated by Clause+++clause-5+++root.2.6.5.4. ## 16.6 Delete Snapshot ### 16.6.1 Description This operation allows deleting an existing Snapshot. This operation allows deleting an existing [Snapshot]{.HTML-Keyboard}. ### 16.6.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can delete a Snapshot within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can delete a [Snapshot]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -274,16 +284,17 @@ Figure: Delete Snapshot use case ### 16.6.3 Input data - A Snapshot identifier (URI), the target Snapshot. - A [Snapshot]{.HTML-Keyboard} identifier (URI), the target [Snapshot]{.HTML-Keyboard}. ### 16.6.4 Behaviour - If the Snapshot Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the Snapshot id provided does not correspond to any existing Snapshot in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise implementations shall delete the Snapshot. - If the [Snapshot]{.HTML-Keyboard} Id is not present or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - If the [Snapshot]{.HTML-Keyboard} id provided does not correspond to any existing [Snapshot]{.HTML-Keyboard} in the system, then an error of type [ResourceNotFound]{.HTML-Error} shall be raised. - Otherwise implementations shall delete the [Snapshot]{.HTML-Keyboard}. ### 16.6.5 Output data Loading @@ -293,12 +304,12 @@ None. ### 16.7.1 Description This operation allows purging selected Snapshots. This operation allows purging selected [Snapshots]{.HTML-Keyboard}. ### 16.7.2 Use case diagram A [Context Consumer]{.HTML-Keyboard} can purge Snapshots within an NGSI-LD system as shown in Figure+++below. A [Context Consumer]{.HTML-Keyboard} can purge [Snapshots]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below. <!-- prettier-ignore-start --> Loading @@ -314,8 +325,8 @@ Figure: Purge Snapshots use case ### 16.7.3 Input data - An NGSI-LD Query to select fitting Snapshots to be purged based on members of the Snapshot data type (see table 5.2.6.5.4-1), as per - An NGSI-LD Query to select fitting [Snapshots]{.HTML-Keyboard} to be purged based on members of the _Snapshot_ data type (see table 5.2.6.5.4-1), as per Clause+++clause-7+++root.2.3. ### 16.7.4 Behaviour Loading @@ -323,7 +334,8 @@ Figure: Purge Snapshots use case - If the NGSI-LD Query is not present or it is not a valid as per Clause+++clause-7+++root.2.3, restricted to members of the Snapshot data type, then an error of type [BadRequestData]{.HTML-Error} shall be raised. - Implementations shall purge the Snapshots fitting the NGSI-LD Query. - Implementations shall purge the [Snapshots]{.HTML-Keyboard} fitting the NGSI-LD Query. ### 16.7.5 Output data Loading @@ -331,21 +343,24 @@ None. ## 16.8 Snapshot status notification behaviour A Snapshot status notification allows the subscriber, typically the creator of the Snapshot, to be notified when the Snapshot is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour: A [Snapshot]{.HTML-Keyboard} status notification allows the subscriber, typically the creator of the [Snapshot]{.HTML-Keyboard}, to be notified when the [Snapshot]{.HTML-Keyboard} is ready, or in case of any problems or updates. Implementations shall exhibit the following behaviour: - SnapshotNotification (Clause+++clause-5+++root.2.6.9.3) messages can only be sent, if the _`endpoint`_ member is set. - SnapshotNotification messages are sent to the URI specified in the _`endpoint`_ member of the Snapshot status. - The information in the _`receiverInfo`_ member of the Snapshot status shall be added to the SnapshotNotification message in the way required for the binding protocol. - Snapshot Status Notifications shall be sent after all the specified Snapshot queries have been executed, the query results have been integrated and the Snapshot status has been updated accordingly. - Snapshot status Notifications shall also be sent after any Snapshot status update, e.g. informing about the actual updated _`expiresAt`_ timestamp. _`endpoint`_ member of the [Snapshot]{.HTML-Keyboard} status. - The information in the _`receiverInfo`_ member of the [Snapshot]{.HTML-Keyboard} status shall be added to the SnapshotNotification message in the way required for the binding protocol. - [Snapshot]{.HTML-Keyboard} Status Notifications shall be sent after all the specified [Snapshot]{.HTML-Keyboard} queries have been executed, the query results have been integrated and the [Snapshot]{.HTML-Keyboard} status has been updated accordingly. - [Snapshot]{.HTML-Keyboard} status Notifications shall also be sent after any [Snapshot]{.HTML-Keyboard} status update, e.g. informing about the actual updated _`expiresAt`_ timestamp. - The SnapshotNotification shall be as mandated by Clause+++clause-5+++root.2.6.9.3.
md/clause-7.md +13 −12 Original line number Diff line number Diff line Loading @@ -105,10 +105,10 @@ to: describe them, defined when [Context Sources]{.HTML-Keyboard} are registered (target is the name of a [Context Source]{.HTML-Keyboard} Property member of the CSourceRegistration, see Table 5.2.9-1). - filter out [Snapshots]{.HTML-Keyboard} by the values of the Snapshot data type members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of the members defined for Snapshot in Table 5.2.43-1 are allowed values for [AttrName]{.HTML-Sample}. - filter out [Snapshots]{.HTML-Keyboard} by the values of the _Snapshot_ data type members, i.e. when filtering [Snapshots]{.HTML-Keyboard}, only the names of the members defined for [Snapshot]{.HTML-Keyboard} in Table 5.2.43-1 are allowed values for [AttrName]{.HTML-Sample}. #### 7.2.3.2 Query Language Definition Loading Loading @@ -2107,11 +2107,12 @@ type [NoMultiTenantSupport]{.HTML-Error} Context information can be dynamic, e.g. when a query result contains many Entities, and the user has to paginate through the result set, the values encountered later may be from a much later point in time than earlier results, making them incomparable. To get more consistent results, the Snapshot concept is introduced, which can be optionally implemented by Context Brokers. It enables "freezing" the result by retrieving all results immediately and persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and analyse the Snapshot in a much more consistent way. making them incomparable. To get more consistent results, the [Snapshot]{.HTML-Keyboard} concept is introduced, which can be optionally implemented by Context Brokers. It enables "freezing" the result by retrieving all results immediately and persisting them locally. [Context Consumers]{.HTML-Keyboard} can then query and analyse the [Snapshot]{.HTML-Keyboard} in a much more consistent way. This is especially relevant for distributed cases, where information initially was distributed across multiple [Context Brokers]{.HTML-Keyboard} and [Context Loading Loading @@ -2142,9 +2143,9 @@ protocol binding specific. The [Snapshot]{.HTML-Keyboard} concept is orthogonal to the [Tenant]{.HTML-Keyboard} concept (see clause 7.8). [Snapshots]{.HTML-Keyboard} can also be created on [Tenants]{.HTML-Keyboard}. To execute an operation on a Snapshot created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API operation. [Snapshot]{.HTML-Keyboard} created on a [Tenant]{.HTML-Keyboard}, both [Snapshot]{.HTML-Keyboard} and [Tenant]{.HTML-Keyboard} (see clause 7.8.2) have to be specified for an API operation. If an implementation determines that it is low on resources, it may delete one or more snapshots. For determining the order in which snapshots are to be Loading
md/clause-8.md +3 −3 Original line number Diff line number Diff line Loading @@ -725,6 +725,6 @@ If the request limits the execution of the operation to the local scope, [Context Source Registrations]{.HTML-Keyboard} from the [Context Registry]{.HTML-Keyboard} will not be used. Operations on a Snapshot (see Clause+++clause-7+++7.9) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations. Operations on a [Snapshot]{.HTML-Keyboard} (see Clause+++clause-7+++7.9) are always implicitly local scope, overriding setting a local scope to false, i.e. such a setting is to be ignored by implementations.
