Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue 469: notification changed to event. #472

Merged
merged 1 commit into from
Jan 17, 2023
+42 −42
Merged

Issue 469: notification changed to event. #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions spec/VISSv2_Core.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ <h2>Definitions</h2>
<dd>The message being returned by the server to the client when no error is encountered. These are specific per request type</dd>
<dt><dfn data-dfn-type="dfn" id="dfn-error-message">error message</dfn></dt>
<dd>The message being returned by the server to the client when an error is encountered. It can be a synchronous response message,
or an asynchrounous notification message.</dd>
or an asynchrounous event message.</dd>
<dt><dfn data-dfn-type="dfn" id="dfn-data-point">data point</dfn></dt>
<dd>A structure containing one or more value, timestamp tuplets.</dd>
<dt><dfn data-dfn-type="dfn" id="dfn-value">value</dfn></dt>
Expand Down Expand Up @@ -379,22 +379,22 @@ <h2>Update</h2>
<section id="subscribe">
<h2>Subscribe</h2>
<p>Purpose: Get asynchronous messages containing the value(s) addressed by the path.
The triggering rules for issuing the notification messages are set by the filter data.</p>
The triggering rules for issuing the event messages are set by the filter data.</p>
<p>The client MAY have to obtain an authorization token before being able to subscribe to the vehicle signal(s).
The server MUST issue a notification if a trigger rule is fulfilled.
The server MUST issue an event message if a trigger rule is fulfilled.
If the server is able to satisfy the request it MUST return a <a>success response</a>.
If the server is unable to fulfil the request, then the server MUST return an <a href="#error-message">error response</a>.
If an error occurs during the subscription period, the server SHOULD return an <a href="#error-message">error notification</a>.</p>
If an error occurs during the subscription period, the server SHOULD return an <a href="#error-message">error event</a>.</p>
<p>Arguments, of which path and filter are mandatory:
<ul>
<li><a>path</a> The path as defined in VSS to one or more nodes in the VSS tree.</li>
<li><a>filter</a> The rule set describing triggering criterias for issuance of asynchronous notification messages.</li>
<li><a>filter</a> The rule set describing triggering criterias for issuance of asynchronous event messages.</li>
<li><a>authorization</a> The authorization token.</li>
</ul>
</p>
<p>Success response:
<ul>
<li><a>subscriptionId</a> A handle identifying notification messages associated with the subscription.</li>
<li><a>subscriptionId</a> A handle identifying event messages associated with the subscription.</li>
<li><a>timestamp</a> The start time for the subscription period.</li>
</ul>
</p>
Expand All @@ -403,7 +403,7 @@ <h2>Subscribe</h2>
<h2>Unsubscribe</h2>
<p>Purpose: Termination of the subscription period started by a previous subscribe request.</p>
<p>If the server is able to satisfy the request it MUST return a <a>success response</a>,
and it MUST stop issuing notifications associated to the subscription handle.
and it MUST stop issuing event messages associated to the subscription handle.
If the server is unable to fulfil the request, then the server MUST return an <a href="#error-message">error response</a>.</p>
<p>Arguments, of which subscriptionId is mandatory:
<ul>
Expand All @@ -419,9 +419,9 @@ <h2>Unsubscribe</h2>
</section>
<section id="subscription">
<h2>Subscription</h2>
<p>Purpose: Asynchronous client notification according to the subscribe request trigger rules.</p>
<p>The server MUST issue a notification message when a triggering rule associated with the subscription is met.
If the server cannot fulfill the triggering rules it MUST issue an error notification and terminate the subscription.
<p>Purpose: Asynchronous client event message according to the subscribe request trigger rules.</p>
<p>The server MUST issue an event message when a triggering rule associated with the subscription is met.
If the server cannot fulfill the triggering rules it MUST issue an error event message and terminate the subscription.
</p>
<p>Arguments:
<ul>
Expand All @@ -440,8 +440,8 @@ <h2>Subscription</h2>
<section id="error-message">
<h2>Error Message</h2>
<p>The server MUST inform a client about errors ocurring in interactions between the two, whether it is in a synchronous
error response, or an asynchronous error notification as a result of a previous subscribe. The error message has three arguments,
of which subscriptionId is mandatory only for error notifications.
error response, or an asynchronous error event message as a result of a previous subscribe. The error message has three arguments,
of which subscriptionId is mandatory only for error event messages.
</p>
<p>Arguments:
<ul>
Expand Down Expand Up @@ -622,7 +622,7 @@ <h2>Paths Filter Operation</h2>
A path in the filter value may contain the wildcard character (*) as a representative for a single path segment.<br>
Every path element in an value array must address at least one node in the tree, or else an error response is returned.<br>
Different elements of the value array may address the same node,
in which case it is the responsibility of the server to resolve this to a singleton in the notifications.<br>
in which case it is the responsibility of the server to resolve this to a singleton in the event messages.<br>
Examples can be found in the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-transport/#https-search-read">search read on HTTPS</a> and
<a data-link-type="dfn" href="https://www.w3.org/TR/viss2-transport/#wss-search-read">search read on WebSocket</a> in [[viss2-transport]] specification.
</p>
Expand Down Expand Up @@ -667,7 +667,7 @@ <h2>Range Filter Operation</h2>
<h2>Single Boundary Range</h2>
<p>
One logical "boundary operator" evaluates the current signal value in relation to the boundary.
If evaluated to true, the server issues a notification message containing the signal value to the subscribing client.
If evaluated to true, the server issues an event message containing the signal value to the subscribing client.
The boundary operator MUST be one of the values shown in the footer (**).<br>
Examples<br>
{"boundary-op":"gt", "boundary": "5"} // x > 5<br>
Expand All @@ -679,7 +679,7 @@ <h2>Multi Boundary Range</h2>
<p>
Two boundaries with respective boundary operators are evaluated relative to the current signal value.
The logical outcome of the two evaluations are applied as input to a logical AND/OR operation.
If evaluated to true, the server issues a notification message containing the signal value to the subscribing client.
If evaluated to true, the server issues an event message containing the signal value to the subscribing client.
Besides the mandatory "boundary-op", and "boundary" key-value pairs in each JSON object,
the first object may contain a "combination-op" key value pair, which then MUST have either the value "AND", or the value "OR".
If omitted, the result of the two boundary evaluations is per default applied to an AND operation.
Expand Down Expand Up @@ -892,18 +892,18 @@ <h2>Response syntax</h2>
</p>
</section>

<section id="subscription-notification-triggering">
<h2>Subscription Notification Triggering</h2>
<section id="subscription-event-triggering">
<h2>Subscription Event Triggering</h2>
<p>
A subscription request must always contain a filter operation that describes the trigger event that leads to
that the server dispatches an asynchronous notification message.
that the server dispatches an asynchronous event message.
For the filter types "range" or "change", the triggering is dependent on the signal value.
When the request addresses multiple signals, the triggering condition shall only be evaluated on one of the signals,
which is the first signal in the value array of paths.
The first path in the array must therefore not contain wildcards to address multiple signals.
In this case one of the path addresses in the wildcard expression must be selected as the first array element,
which can then be followed by the wildcard expression.
The duplicate reference to one signal that this leads to shall be resolved by the server to a singleton in the notifications.
The duplicate reference to one signal that this leads to shall be resolved by the server to a singleton in the event messages.
</p>
</section>
</section>
Expand Down
46 changes: 23 additions & 23 deletions spec/VISSv2_Transport.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -663,7 +663,7 @@ <h2>Session Life Time Management</h2>

<p>If more than one WebSocket connection is established between a client application and the server then each connection
<em class="rfc2119" title="MUST">MUST</em> be managed independently. For example, subscriptions created using a particular
WebSocket connection shall only trigger notifications via that connection and the client
WebSocket connection shall only trigger event messages via that connection and the client
<em class="rfc2119" title="MUST">MUST</em> use that WebSocket connection to unsubscribe.
</p>

Expand Down Expand Up @@ -1021,26 +1021,26 @@ <h2>Subscribe</h2>
<p>
The client may send a <a href="#dfn-subscriberequest" class="internalDFN" data-link-type="dfn">subscribeRequest</a> message
to request a subscription to one or more signals,
thereby requesting the server to repeatedly return subscription notification messages, as specified by
thereby requesting the server to repeatedly return subscription event messages, as specified by
the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#filter-request">filter request</a> described in the [[viss2-core]].
The server <em class="rfc2119" title="MAY">MAY</em> reduce the number of
<a href="#dfn-subscriptionnotification" class="internalDFN" data-link-type="dfn">subcriptionNotification</a>
<a href="#dfn-subscriptionevent" class="internalDFN" data-link-type="dfn">subcriptionEvent</a>
messages sent to the client in order to reduce processing demands.<br>
If the server is able to satisfy the request it SHALL return a
<a href="#dfn-subscribesuccessresponse" class="internalDFN" data-link-type="dfn">subscribeSuccessResponse</a> message.
If an error occurs e.g. because the client is not authorized to read the requested value, the server SHALL return a
<a href="#dfn-subscribeerrorresponse" class="internalDFN" data-link-type="dfn">subscribeErrorResponse</a> message.
If an error occurs during the subscription session, the server shall return an
<a href="#dfn-subscriptionerrornotification" class="internalDFN" data-link-type="dfn">subscriptionErrorNotification</a> message.<br>
<a href="#dfn-subscriptionerrorevent" class="internalDFN" data-link-type="dfn">subscriptionErrorEvent</a> message.<br>
The subscription variants are, as described in the [[viss2-core]] document:
<ul>
<li>timebased: notifications are issued at a regular time interval,</li>
<li>change: notifications are issued when the value has changed as specified,</li>
<li>range: notifications are issued when the value is in the specified range,</li>
<li>curvelog: notifications are issued when the buffer is full, and then processed according to the curve logging algorithm.</li>
<li>timebased: event messages are issued at a regular time interval,</li>
<li>change: event messages are issued when the value has changed as specified,</li>
<li>range: event messages are issued when the value is in the specified range,</li>
<li>curvelog: event messages are issued when the buffer is full, and then processed according to the curve logging algorithm.</li>
</ul>
If none of the above trigger condition variants is specified,
then a notification will be issued whenever the underlying vehicle system supplies a new data point to the server.
then an event message will be issued whenever the underlying vehicle system supplies a new data point to the server.
</p>
<table class="simple">
<thead>
Expand Down Expand Up @@ -1084,7 +1084,7 @@ <h2>Subscribe</h2>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="3"><dfn data-dfn-type="dfn" id="dfn-subscriptionnotification">subscriptionNotification</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><th rowspan="3"><dfn data-dfn-type="dfn" id="dfn-subscriptionevent">subscriptionEvent</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-subscriptionid">subscriptionId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-value">data</a></td><td>object/array</td><td>Yes</td></tr>
</tbody>
Expand All @@ -1095,7 +1095,7 @@ <h2>Subscribe</h2>
<tr><th>Object Name</th><th>Attribute</th><th>Type</th><th>Required</th></tr>
</thead>
<tbody>
<tr><th rowspan="4"><dfn data-dfn-type="dfn" id="dfn-subscriptionerrornotification">subscriptionErrorNotification</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><th rowspan="4"><dfn data-dfn-type="dfn" id="dfn-subscriptionerrorevent">subscriptionErrorEvent</dfn></th><td><a href="#dfn-action">action</a></td><td><a href="#action-def">Action</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-subscriptionid">subscriptionId</a></td><td>string</td><td>Yes</td></tr>
<tr><td><a href="#dfn-error">error</a></td><td><a href="#error-def">Error</a></td><td>Yes</td></tr>
<tr><td><a href="#dfn-ts">ts</a></td><td>string</td><td>Yes</td></tr>
Expand Down Expand Up @@ -1130,7 +1130,7 @@ <h2>Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Notification:
Event:
<pre><code>
{
"action": "subscription",
Expand All @@ -1141,7 +1141,7 @@ <h2>Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Error notification:
Error event:
<pre><code>
{
"action": "subscription",
Expand Down Expand Up @@ -1184,7 +1184,7 @@ <h2>Authorized Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Notification:
Event:
<pre><code>
{
"action": "subscription",
Expand All @@ -1202,7 +1202,7 @@ <h2>Authorized Subscribe</h2>
<h2>Curve Logging Subscribe</h2>
<p>
Curve logging data compression by eliminating data points that are within a set error margin is activated via a subscription request.
Notifications will be issued when the buffer becomes full, after insignificant data points have been eliminated,
Event messages will be issued when the buffer becomes full, after insignificant data points have been eliminated,
refer the <a data-link-type="dfn" href="https://www.w3.org/TR/viss2-core/#curvelog-filter-operation">Curve logging Filter Operation</a> chapter in the [[viss2-core]] documentation.
</p>
<p>
Expand All @@ -1225,7 +1225,7 @@ <h2>Curve Logging Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Notification:
Event:
<pre><code>
{
"action": "subscription",
Expand Down Expand Up @@ -1265,7 +1265,7 @@ <h2>Range Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Notification:
Event:
<pre><code>
{
"action": "subscription",
Expand Down Expand Up @@ -1304,7 +1304,7 @@ <h2>Change Subscribe</h2>
"ts": "2020-04-15T13:37:00Z"
}
</code></pre>
Notification:
Event:
<pre><code>
{
"action": "subscription",
Expand Down Expand Up @@ -1427,14 +1427,14 @@ <h2>Application Level Protocol</h2>
The broker will then forward this message to the cloud side client that earlier subscribed to this topic name,
which concludes the client-server based request-response as described in the [[viss2-core]] specification.<br>
In the case of subscription requests the vehicle client needs to save the subscriptionId found in the subscribe response,
together with the topic name associated to the subscribe request. When the vehicle server later issues notifications,
together with the topic name associated to the subscribe request. When the vehicle server later issues event messages,
the vehicle client must parse the subscriptionId from it, and retrieve the topic name associated to it.
The vehicle client shall delete the saved topic name and subscriptionId when it receives
an unsubscribe request in a message from the broker.<br>
In following requests from the cloud side client, the unique topic name may be reused from the previous request-response cycle,
or a new unique topic name may be generated. If a new topic name is generated, an unsubscribe should be issued on the old topic name.
The vehicle client can continue to use the topic name it subscribes to.<br>
The payload format of the responses/notifications SHALL follow the payload format that is specified
The payload format of the response/event messages SHALL follow the payload format that is specified
in the Websocket chapter of this specification.
The access control model is applicable also over this transport alternative.
The Access Token server should then implement its own version of the application level protocol described here,
Expand Down Expand Up @@ -1654,11 +1654,11 @@ <h2>Action Definitions</h2>
<dt><b>set</b></dt>
<dd>Enables the client to update one value.</dd>
<dt><b>subscribe</b></dt>
<dd>Enables the client to request notifications containing a JSON data structure with values for one or more vehicle signal.</dd>
<dd>Enables the client to request event messages containing a JSON data structure with values for one or more vehicle signal.</dd>
<dt><b>unsubscribe</b></dt>
<dd>Enables the client to request that it should no longer receive notifications based on that subscription.</dd>
<dd>Enables the client to request that it should no longer receive event messages based on that subscription.</dd>
<dt><b>subscription</b></dt>
<dd>Enables the server to send notifications to the client containing a JSON data structure with values for one or more vehicle signals.</dd>
<dd>Enables the server to send event messages to the client containing a JSON data structure with values for one or more vehicle signals.</dd>
</dl>
</section>

Expand Down