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

Allow only one subscription per affordance #356

Merged
merged 9 commits into from
Dec 13, 2021
+70 −12
Merged

Allow only one subscription per affordance #356

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
dff743a
Merge branch 'main' of https://github.com/w3c/wot-scripting-api into …
relu91 Dec 2, 2021
b2d91c8
Merge branch 'main' of https://github.com/w3c/wot-scripting-api into …
relu91 Dec 13, 2021
0751f85
fix: allow just one subscription per event affordance
relu91 Dec 2, 2021
8975def
fix: consumed thing reference in subscribeEvent
relu91 Dec 2, 2021
7ccd10d
feat: allow just one subscription in observeProperty method
relu91 Dec 2, 2021
a1ec4aa
fix: consumed thing reference in subscribeEvent
relu91 Dec 2, 2021
54f0b30
feat: add activeSubscriptions and activeObservations to ConsumedThing…
relu91 Dec 2, 2021
fbb32e1
chore: correctly cite Set
relu91 Dec 13, 2021
667e9c9
chore: fix two minor typos
relu91 Dec 13, 2021
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
82 changes: 70 additions & 12 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
]
},
],
xref: ["web-platform", "streams", "wot-architecture", "wot-thing-description", "wot-binding-templates", "html", "infra"],
xref: ["web-platform", "streams", "wot-architecture", "wot-thing-description", "wot-binding-templates", "html", "infra", "ecmascript"],
localBiblio: {
"WOT-ARCHITECTURE" : {
href:"https://www.w3.org/TR/2020/WD-wot-architecture11-20201124/",
Expand Down Expand Up @@ -460,7 +460,7 @@
-->
</section>

<section>
<section data-cite="webidl">
<h2>The <dfn>ThingDescription</dfn> type</h2>
<pre class="idl">
typedef object ThingDescription;
Expand Down Expand Up @@ -525,7 +525,7 @@ <h2>The <dfn>ThingDescription</dfn> type</h2>
</div>
</section>
</section>
<section data-dfn-for="WOT">
<section data-dfn-for="WOT" data-cite="webidl">
<h2>The <dfn>WOT</dfn> namespace</dfn></h2>
<p>
Defines the <dfn>WoT API object</dfn> as a singleton and contains the API
Expand Down Expand Up @@ -719,7 +719,7 @@ <h3>Validating an ExposedThingInit</h3>
</section>
</section> <!-- WoT -->

<section> <h2>Handling interaction data</h2>
<section data-cite="webidl"> <h2>Handling interaction data</h2>
<p>
As specified in the [[[WOT-TD]]] specification, <a>WoT interactions</a> extend <a>DataSchema</a>
and include a number of possible <a>Form</a>s, out of which one is selected
Expand Down Expand Up @@ -1222,7 +1222,7 @@ <h2>The <dfn>InteractionOutput</dfn> interface</h2>

</section> <!-- Handling interaction data -->

<section data-dfn-for="ConsumedThing">
<section data-cite="webidl" data-dfn-for="ConsumedThing">
<h2>The <dfn>ConsumedThing</dfn> interface</h2>
<p>
Represents a client API to operate a <a>Thing</a>. Belongs to the
Expand Down Expand Up @@ -1292,7 +1292,7 @@ <h2>The <dfn>ConsumedThing</dfn> interface</h2>
Meanwhile, use the <code>writeMultipleProperties()</code> method instead.
</p>
<section>
<h4>Internal slots for ConsumedThing</h4>
<h4>Internal slots for {{ConsumedThing}}</h4>
<p>
A {{ConsumedThing}} object has the following <a>internal slots</a>:
</p>
Expand All @@ -1310,6 +1310,16 @@ <h4>Internal slots for ConsumedThing</h4>
<td>`null`</td>
<td>The <a>Thing Description</a> of the {{ConsumedThing}}.</td>
</tr>
<tr>
<td><dfn>[[\activeSubscriptions]]</dfn></td>
<td>`{}`</td>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was a good idea to have an internal slot as a set, as it is usable with all policies (replace existing, reject if existing, add, ...).

<td>A {{Set}} containing the names of active {{Subscription}}'s for an <a>Event</a></td>
</tr>
<tr>
<td><dfn>[[\activeObservations]]</dfn></td>
<td>`{}`</td>
<td>A {{Set}} containing the names of active {{Subscription}}'s for an <a>Property</a></td>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess it should read
a set of active Observations but then internal linking is no longer working.... maybe we can refer to it by id

</tr>
</tbody>
</table>
</section>
Expand Down Expand Up @@ -1677,8 +1687,16 @@ <h3>The <dfn>observeProperty()</dfn> method</h3>
Takes as arguments |propertyName:string|, |listener:InteractionListener| and
optionally |onerror:ErrorListener| and |options:InteractionOptions|.
It returns a {{Promise}} that resolves on success and rejects on failure.
<p class="ednote">
This algorithm allows for only one active {{Subscription}} per <a>Property</a>. If a new
{{Subscription}} is made while an existing {{Subscription}} is active the runtime
will throw an {{NotAllowedError}}.
</p>
The method MUST run the following steps:
<ol>
<li>
Let |thing| be the reference of this {{ConsumedThing}} object.
</li>
<li>
Return a {{Promise}} |promise:Promise| and execute the next steps [=in parallel=].
</li>
Expand All @@ -1693,6 +1711,10 @@ <h3>The <dfn>observeProperty()</dfn> method</h3>
If |onerror| is not `null` and is not a {{Function}}, reject |promise|
with a {{TypeError}} and abort these steps.
</li>
<li>
if |thing| [[\activeObservations]] contains |propertyName|, reject |promise| with
a {{NotAllowedError}} and abort these steps.
</li>
<li>
Let |subscription| be a new {{Subscription}} object with its <a>internal slots</a>
set as follows:
Expand All @@ -1707,6 +1729,9 @@ <h3>The <dfn>observeProperty()</dfn> method</h3>
Let |subscription|'s [[\interaction]] be the value of [[\td]]'s
|properties|'s |propertyName|.
</li>
<li>
Let |subscription|'s [[\thing]] be the value of |thing|.
</li>
<li>
Let |subscription|'s [[\form]] be the <a>Form</a> associated with
|formIndex| in [[\interaction]]'s |forms| array if |option|'s
Expand Down Expand Up @@ -1734,7 +1759,7 @@ <h3>The <dfn>observeProperty()</dfn> method</h3>
the <a>Protocol Bindings</a> and abort these steps.
</li>
<li>
Otherwise resolve |promise|.
Otherwise add |propertyName| to |thing|'s' [[\activeObservations]] set and resolve |promise|.
</li>
<li>
Whenever the underlying platform detects a notification for this
Expand Down Expand Up @@ -1836,8 +1861,16 @@ <h3>The <dfn>subscribeEvent()</dfn> method</h3>
Takes as arguments |eventName:string|, |listener:WoTListener| and
optionally |onerror:ErrorListener| and |options:InteractionOptions|.
It returns a {{Promise}} to signal success or failure.
<p class="ednote">
This algorithm allows for only one active {{Subscription}} per <a>Event</a>. If a new
{{Subscription}} is made while an existing {{Subscription}} is active the runtime
will throw an {{NotAllowedError}}.
</p>
The method MUST run the following steps:
<ol>
<li>
Let |thing| be the reference of this {{ConsumedThing}} object.
</li>
<li>
Return a {{Promise}} |promise:Promise| and execute the next steps [=in parallel=].
</li>
Expand All @@ -1852,6 +1885,10 @@ <h3>The <dfn>subscribeEvent()</dfn> method</h3>
If |onerror| is not `null` and is not a {{Function}}, reject |promise|
with a {{TypeError}} and abort these steps.
</li>
<li>
if |thing| [[\activeSubscriptions]] contains |eventName|, reject |promise| with
a {{NotAllowedError}} and abort these steps.
</li>
<li>
Let |subscription| be a new {{Subscription}} object with its <a>internal slots</a>
set as follows:
Expand All @@ -1866,6 +1903,9 @@ <h3>The <dfn>subscribeEvent()</dfn> method</h3>
Let |subscription|'s [[\interaction]] be the value of [[\td]]'s
|events|'s |eventName|.
</li>
<li>
Let |subscription|'s [[\thing]] be the value of |thing|.
</li>
<li>
Let |subscription|'s [[\form]] be the <a>Form</a> associated with
|formIndex| in [[\interaction]]'s |forms| array if |option|'s
Expand Down Expand Up @@ -1894,7 +1934,7 @@ <h3>The <dfn>subscribeEvent()</dfn> method</h3>
the <a>Protocol Bindings</a> and abort these steps.
</li>
<li>
Otherwise resolve |promise|.
Otherwise add |eventName| to |thing|'s [[\activeSubscriptions]] set and resolve |promise|.
</li>
<li>
Whenever the underlying platform detects a notification for this
Expand Down Expand Up @@ -2053,6 +2093,11 @@ <h3>The <dfn>Subscription</dfn> interface</h3>
<td>`null`</td>
<td>The <a>Form</a> associated with the subscription.</td>
</tr>
<tr>
<td><dfn>[[\thing]]</dfn></td>
<td>`null`</td>
<td>The <a>ConsumedThing</a> associated with the subscription.</td>
</tr>
</tbody>
</table>
</section>
Expand Down Expand Up @@ -2103,8 +2148,21 @@ <h4>The <dfn>stop()</dfn> method</h4>
the <a>Protocol Bindings</a> and abort these steps.
</li>
<li>
Otherwise set <a href="#dom-subscription-active">active</a> to
`false` and resolve |promise|.
Otherwise:
<ul>
<li>
set <a href="#dom-subscription-active">active</a> to `false`.
</li>
<li>
if [[\type]] is `"event"`, remove [[\name]] from [[\thing]]'s [[\activeSubscriptions]] .
</li>
<li>
if [[\type]] is `"property"`, remove [[\name]] from [[\thing]]'s [[\activeObservations]] .
</li>
<li>
resolve |promise|.
</li>
</ul>
</li>
<li>
If the underlying platform receives further notifications for this
Expand Down Expand Up @@ -2309,7 +2367,7 @@ <h2>ConsumedThing Examples</h2>
</section> <!-- Examples -->
</section> <!-- ConsumedThing -->

<section data-dfn-for="ExposedThing">
<section data-cite="webidl" data-dfn-for="ExposedThing">
<h2>The <dfn>ExposedThing</dfn> interface</h2>
<p>
The {{ExposedThing}} interface is the server API to operate the <a>Thing</a> that allows defining request handlers, <a>Property</a>, <a>Action</a>, and <a>Event</a> interactions.
Expand Down Expand Up @@ -3609,7 +3667,7 @@ <h2>ExposedThing Examples</h2>
</section> <!-- ExposedThing Examples -->
</section> <!-- ExposedThing -->

<section data-dfn-for="ThingDiscovery">
<section data-cite="webidl" data-dfn-for="ThingDiscovery">
<h2>The <dfn>ThingDiscovery</dfn> interface</h2>
<p>
Discovery is a distributed application that requires provisioning and support from participating network nodes (clients, servers, directory services). This API models the client side of typical discovery schemes supported by various IoT deployments.
Expand Down