From 335b815fe98242031d3ba38f0d7e332970a754a5 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 18 Oct 2024 12:16:16 -0400 Subject: [PATCH 1/8] Clarification re repeated addContextListener and addIntentListener calls --- CHANGELOG.md | 1 + docs/api/ref/Channel.md | 2 ++ docs/api/ref/DesktopAgent.md | 5 +++++ docs/api/spec.md | 2 ++ src/api/Channel.ts | 3 +++ src/api/DesktopAgent.ts | 4 ++++ src/api/Errors.ts | 2 ++ 7 files changed, 19 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbceeed8c..335687505 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a `userChannelChanged` event ([#1207](https://github.com/finos/FDC3/pull/1207)) * Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#1305](https://github.com/finos/FDC3/pull/1305)) * Added support for broadcast actions to the `fdc3.action` context type, allowing an Action to represent the broadcast of a specified context to an app or user channel. ([#1368](https://github.com/finos/FDC3/pull/1368)) +* Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). ### Changed diff --git a/docs/api/ref/Channel.md b/docs/api/ref/Channel.md index 4f949f09d..c02c80714 100644 --- a/docs/api/ref/Channel.md +++ b/docs/api/ref/Channel.md @@ -174,6 +174,8 @@ If, when this function is called, the channel already contains context that woul Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. +Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current channel. + **Examples:** Add a listener for any context that is broadcast on the channel: diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 9525418b7..49c37aa00 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -132,6 +132,8 @@ Context may also be received via this listener if the application was launched v Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the Desktop Agent implementation. +Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differes from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more detials. + **Examples:** @@ -264,6 +266,8 @@ The [`PrivateChannel`](PrivateChannel) type is provided to support synchronizati Optional metadata about each intent & context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. + Adding multiple intent listeners on the same type MUST be rejected with the [`ResolverError.IntentListenerConflict`](Errors#resolveerror), unless the previous listener was removed first though [`listener.unsubscribe`](Types#unsubscribe) + **Examples:** @@ -339,6 +343,7 @@ var listener = await _desktopAgent.AddIntentListener("StartChat", (con - [`Listener`](Types#listener) - [`Context`](Types#context) - [`IntentHandler`](Types#intenthandler) +- [`ResolveError`](Errors#resolveerror) ### `broadcast` diff --git a/docs/api/spec.md b/docs/api/spec.md index dde1210ba..9b27ee137 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -525,6 +525,8 @@ When an instance of an application is launched, it is expected to add an [`Inten Intent handlers SHOULD be registered via [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) within 15 seconds of the application launch (the minimum timeout Desktop Agents are required to provide) in order to be widely compatible with Desktop Agent implementations. Individual Desktop Agent implementations MAY support longer timeouts or configuration to control or extend timeouts. +Single listener can be added for the specific intent at a time. Therefore, if the application attempts to call [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) passing the same `intent` the second time, before unsubscribing to the previously added listener, Desktop Agent MUST reject it with `ResolverError.IntentListenerConflict` error. + ### Originating App Metadata Optional metadata about each intent & context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation to registered intent handlers. As this metadata is optional, apps making use of it MUST handle cases where it is not provided. diff --git a/src/api/Channel.ts b/src/api/Channel.ts index 9eca774b5..b0ee14cc4 100644 --- a/src/api/Channel.ts +++ b/src/api/Channel.ts @@ -70,6 +70,9 @@ export interface Channel { * If, when this function is called, the channel already contains context that would be passed to the listener it is NOT called or passed this context automatically (this behavior differs from that of the [`fdc3.addContextListener`](DesktopAgent#addcontextlistener) function). Apps wishing to access to the current context of the channel should instead call the `getCurrentContext(contextType)` function. * * Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. + * + * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all contextHandlers when a relevant context type is broadcast on the current channel. + * */ addContextListener(contextType: string | null, handler: ContextHandler): Promise; diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index b31289d74..3a60d614e 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -305,6 +305,8 @@ export interface DesktopAgent { * The `PrivateChannel` type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent. * * Optional metadata about the raised intent, including the app that originated the message, SHOULD be provided by the desktop agent implementation. + * + * Adding multiple intent listeners on the same type MUST be rejected with the `ResolverError.IntentListenerConflict`, unless the previous listener was removed first though `listener.unsubscribe` * * ```javascript * //Handle a raised intent @@ -359,6 +361,8 @@ export interface DesktopAgent { * Context may also be received via this listener if the application was launched via a call to `fdc3.open`, where context was passed as an argument. In order to receive this, applications SHOULD add their context listener as quickly as possible after launch, or an error MAY be returned to the caller and the context may not be delivered. The exact timeout used is set by the Desktop Agent implementation, but MUST be at least 15 seconds. * * Optional metadata about the context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation. + * + * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all contextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differes from `fdc3.addIntentListener`API call; refer to the relevant documentation for more detials. * * ```javascript * // any context diff --git a/src/api/Errors.ts b/src/api/Errors.ts index 2b10d5944..8299ae36c 100644 --- a/src/api/Errors.ts +++ b/src/api/Errors.ts @@ -37,6 +37,8 @@ export enum ResolveError { IntentDeliveryFailed = 'IntentDeliveryFailed', /** Returned if a call to one of the `raiseIntent` functions is made with an invalid context argument. Contexts should be Objects with at least a `type` field that has a `string` value.*/ MalformedContext = 'MalformedContext', + /** Returned if `fdc3.addIntentListener` is called for the intent repeatedly without unsubscribing, i.e. a listener was previously added for specified intent. */ + IntentListenerConflict = 'IntentListenerConflict', /** @experimental Returned if the specified Desktop Agent is not found, via a connected Desktop Agent Bridge.*/ DesktopAgentNotFound = 'DesktopAgentNotFound', } From 32c9e6196d03645309ee1dd6591c508bb6b1c9de Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 18 Oct 2024 12:19:33 -0400 Subject: [PATCH 2/8] Adding to CHANGELOG --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 335687505..63d652787 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a `userChannelChanged` event ([#1207](https://github.com/finos/FDC3/pull/1207)) * Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#1305](https://github.com/finos/FDC3/pull/1305)) * Added support for broadcast actions to the `fdc3.action` context type, allowing an Action to represent the broadcast of a specified context to an app or user channel. ([#1368](https://github.com/finos/FDC3/pull/1368)) -* Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). +* Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). ([#1394](https://github.com/finos/FDC3/pull/1394)) ### Changed From 3acaa23fed8bf3048b95826d03c1e214e4f62c05 Mon Sep 17 00:00:00 2001 From: kemerava <52539182+kemerava@users.noreply.github.com> Date: Fri, 25 Oct 2024 11:29:56 -0400 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Kris West --- docs/api/ref/DesktopAgent.md | 4 ++-- docs/api/spec.md | 2 +- src/api/Channel.ts | 2 +- src/api/DesktopAgent.ts | 2 +- src/api/Errors.ts | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 49c37aa00..3c4c64d10 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -132,7 +132,7 @@ Context may also be received via this listener if the application was launched v Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the Desktop Agent implementation. -Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differes from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more detials. +Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differs from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more details. **Examples:** @@ -266,7 +266,7 @@ The [`PrivateChannel`](PrivateChannel) type is provided to support synchronizati Optional metadata about each intent & context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. - Adding multiple intent listeners on the same type MUST be rejected with the [`ResolverError.IntentListenerConflict`](Errors#resolveerror), unless the previous listener was removed first though [`listener.unsubscribe`](Types#unsubscribe) + Adding multiple intent listeners on the same type MUST be rejected with the [`ResolveError.IntentListenerConflict`](Errors#resolveerror), unless the previous listener was removed first though [`listener.unsubscribe`](Types#unsubscribe) **Examples:** diff --git a/docs/api/spec.md b/docs/api/spec.md index 9b27ee137..b469c1226 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -525,7 +525,7 @@ When an instance of an application is launched, it is expected to add an [`Inten Intent handlers SHOULD be registered via [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) within 15 seconds of the application launch (the minimum timeout Desktop Agents are required to provide) in order to be widely compatible with Desktop Agent implementations. Individual Desktop Agent implementations MAY support longer timeouts or configuration to control or extend timeouts. -Single listener can be added for the specific intent at a time. Therefore, if the application attempts to call [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) passing the same `intent` the second time, before unsubscribing to the previously added listener, Desktop Agent MUST reject it with `ResolverError.IntentListenerConflict` error. +A single handler can be added for each specific intent. If the application attempts to call [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) passing the same `intent` a second time, before unsubscribing to the previously added listener, the Desktop Agent MUST reject it with an `Error` Object with the message given by [`ResolveError.IntentListenerConflict`](ref/Errors#resolveerror). ### Originating App Metadata diff --git a/src/api/Channel.ts b/src/api/Channel.ts index b0ee14cc4..e429425f7 100644 --- a/src/api/Channel.ts +++ b/src/api/Channel.ts @@ -71,7 +71,7 @@ export interface Channel { * * Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. * - * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all contextHandlers when a relevant context type is broadcast on the current channel. + * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all context handlers when a relevant context type is broadcast on the current channel. * */ addContextListener(contextType: string | null, handler: ContextHandler): Promise; diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 3a60d614e..c3322463f 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -306,7 +306,7 @@ export interface DesktopAgent { * * Optional metadata about the raised intent, including the app that originated the message, SHOULD be provided by the desktop agent implementation. * - * Adding multiple intent listeners on the same type MUST be rejected with the `ResolverError.IntentListenerConflict`, unless the previous listener was removed first though `listener.unsubscribe` + * Adding multiple intent listeners on the same type MUST be rejected with the `ResolveError.IntentListenerConflict`, unless the previous listener was removed first though `listener.unsubscribe` * * ```javascript * //Handle a raised intent diff --git a/src/api/Errors.ts b/src/api/Errors.ts index 8299ae36c..32980c451 100644 --- a/src/api/Errors.ts +++ b/src/api/Errors.ts @@ -37,7 +37,7 @@ export enum ResolveError { IntentDeliveryFailed = 'IntentDeliveryFailed', /** Returned if a call to one of the `raiseIntent` functions is made with an invalid context argument. Contexts should be Objects with at least a `type` field that has a `string` value.*/ MalformedContext = 'MalformedContext', - /** Returned if `fdc3.addIntentListener` is called for the intent repeatedly without unsubscribing, i.e. a listener was previously added for specified intent. */ + /** Returned if `fdc3.addIntentListener` is called for a specified intent that the application has already added a listener for and has not subsequently removed it. */ IntentListenerConflict = 'IntentListenerConflict', /** @experimental Returned if the specified Desktop Agent is not found, via a connected Desktop Agent Bridge.*/ DesktopAgentNotFound = 'DesktopAgentNotFound', From d071ff559370693bc903093f19410bfefea527e6 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 25 Oct 2024 13:43:30 -0400 Subject: [PATCH 4/8] Changing "SHOULD" to "MUST" --- docs/api/ref/DesktopAgent.md | 4 ++-- src/api/DesktopAgent.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 3c4c64d10..c639b5c37 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -132,7 +132,7 @@ Context may also be received via this listener if the application was launched v Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the Desktop Agent implementation. -Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differs from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more details. +Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) MUST be allowed, and MUST trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differs from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more details. **Examples:** @@ -532,7 +532,7 @@ Task> FindInstances(IAppIdentifier app); Find all the available instances for a particular application. -If the application is not known to the agent, the returned promise should be rejected with the `ResolverError.NoAppsFound` error message. However, if the application is known but there are no instances of the specified app the returned promise should resolve to an empty array. +If the application is not known to the agent, the returned promise should be rejected with the `ResolveError.NoAppsFound` error message. However, if the application is known but there are no instances of the specified app the returned promise should resolve to an empty array. If the request fails for another reason, the promise MUST be rejected with an `Error` Object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration, or (if connected to a Desktop Agent Bridge) the [`BridgingError`](Errors#bridgingerror) enumeration. diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index c3322463f..b473777d4 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -362,7 +362,7 @@ export interface DesktopAgent { * * Optional metadata about the context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation. * - * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all contextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differes from `fdc3.addIntentListener`API call; refer to the relevant documentation for more detials. + * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) MUST be allowed, and MUST trigger all contextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differes from `fdc3.addIntentListener`API call; refer to the relevant documentation for more detials. * * ```javascript * // any context From 13f8e8c601bbda6ed40ebc445ba2af02943b0a21 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 25 Oct 2024 13:46:18 -0400 Subject: [PATCH 5/8] Changing SHOULD to MUST for Channel files --- docs/api/ref/Channel.md | 2 +- src/api/Channel.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/ref/Channel.md b/docs/api/ref/Channel.md index c02c80714..454703ee6 100644 --- a/docs/api/ref/Channel.md +++ b/docs/api/ref/Channel.md @@ -174,7 +174,7 @@ If, when this function is called, the channel already contains context that woul Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. -Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) SHOULD be allowed, and SHOULD trigger all ContextHandlers when a relevant context type is broadcast on the current channel. +Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) MUST be allowed, and MUST trigger all ContextHandlers when a relevant context type is broadcast on the current channel. **Examples:** diff --git a/src/api/Channel.ts b/src/api/Channel.ts index e429425f7..8a964d538 100644 --- a/src/api/Channel.ts +++ b/src/api/Channel.ts @@ -71,7 +71,7 @@ export interface Channel { * * Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation. * - * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) SHOULD be allowed, and SHOULD trigger all context handlers when a relevant context type is broadcast on the current channel. + * Adding multiple context listeners on the same or overlapping types (i.e. named type and null type) MUST be allowed, and MUST trigger all context handlers when a relevant context type is broadcast on the current channel. * */ addContextListener(contextType: string | null, handler: ContextHandler): Promise; From f963e8ee5d7453bce5e3fed4530d7dbc44262be6 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 25 Oct 2024 14:14:59 -0400 Subject: [PATCH 6/8] Test definitions added --- toolbox/fdc3-conformance/App-Channel-Tests.md | 17 ++++++++++++++++- toolbox/fdc3-conformance/User-Channel-Tests.md | 14 ++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/toolbox/fdc3-conformance/App-Channel-Tests.md b/toolbox/fdc3-conformance/App-Channel-Tests.md index 597d0bc28..4e977bbdf 100644 --- a/toolbox/fdc3-conformance/App-Channel-Tests.md +++ b/toolbox/fdc3-conformance/App-Channel-Tests.md @@ -28,7 +28,7 @@ | App | Step | Details | |-----|--------------------|-----------------------------------------------------------------| | A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | -| A | 2.Add Context Listener |Add an _typed_ context listener for `fdc3.instrument`, using:
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `await testChannel.addContextListener("fdc3.instrument", handler)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `testChannel.addContextListener("fdc3.instrument", handler)` +| A | 2.Add Context Listener |Add a _typed_ context listener for `fdc3.instrument`, using:
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `await testChannel.addContextListener("fdc3.instrument", handler)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `testChannel.addContextListener("fdc3.instrument", handler)` | B | 3.Retrieve `Channel` |Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| | B | 4.Broadcast | B broadcasts both an `fdc3.instrument` context and an `fdc3.contact` context, using:
`testChannel.broadcast()`
`testChannel.broadcast()`| | A | 5.Receive Context | An fdc3.instrument context is received by the handler added in step 2.
Ensure that the fdc3.instrument received by A is identical to that sent by B
Ensure that the fdc3.contact context is NOT received. | @@ -52,3 +52,18 @@ - `ACContextHistoryTyped`: Perform above test. - `ACContextHistoryMultiple`: **B** Broadcasts multiple history items of both types. Ensure that only the last version of each type is received by **A**. - `ACContextHistoryLast`: In step 5. **A** retrieves the _untyped_ current context of the channel via `const currentContext = await testChannel.getCurrentContext()`. Ensure that A receives only the very last broadcast context item _of any type_. + + +## Multipe listeners On The Same Or Overlapping Ccontext types + +| App | Step | Details | +|-----|--------------------|----------------------------------------------------------------------------| +| A | 1.Retrieve `Channel` |Retrieve a `Channel` object representing an 'App' channel called `test-channel` using:
`const testChannel = await fdc3.getOrCreateChannel("test-channel")` | +| A | 2.Add Context Listener |Add an _untyped_ context listener to the channel, using:
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `await testChannel.addContextListener(null, handler1)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `testChannel.addContextListener(null, handler1)` | +| A | 3.Add Context Listener |Add a _typed_ context listener for `fdc3.instrument` with a different handler, using:
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `await testChannel.addContextListener("fdc3.instrument", handler2)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `testChannel.addContextListener("fdc3.instrument", handler2)`| +| B | 4.Retrieve `Channel` | Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)| +| B | 5.Broadcast | Broadcast an `fdc3.instrument` Context to the channel with:
`testChannel.broadcast()`| +| A | 6.Receive Context | The handlers added in step 2 and 3 will receive the instrument context. Ensure that the instrument received by A is identical to that sent by B. | + +- ACMultipleOverlappingListeners1: Perform above test +- ACMultipleOverlappingListeners2: Perform above test, but instead of _untyped_ context listener, in step 2, use `fdc3.instrument` (handler should remain different) \ No newline at end of file diff --git a/toolbox/fdc3-conformance/User-Channel-Tests.md b/toolbox/fdc3-conformance/User-Channel-Tests.md index 923a5332c..eba6bbbce 100644 --- a/toolbox/fdc3-conformance/User-Channel-Tests.md +++ b/toolbox/fdc3-conformance/User-Channel-Tests.md @@ -49,3 +49,17 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog - `UCFilteredUsageUnsubscribe`: Perform above test, except that after joining, **A** then `unsubscribe()`s from the channel using the `listener.unsubscribe` function. Check that **A** does NOT receive anything. - `UCFilteredUsageLeave`: Perform above test, except that immediately after joining, **A** _leaves the channel_, and so receives nothing. - `UCFilteredUsageNoJoin`: Perform the above test, but skip step 2 so that **A** does NOT join a channel. Confirm that the _current channel_ for **A** is NOT set before continuing with the rest of the test. **A** should receive nothing. + + +## Broadcast With Multiple Listeners On The Same or Overlapping Types + +| App | Step | Details | +|-----|--------------------|-------------------------------------------------------------------------------------------------------------| +| A | 1.addContextListeners | A sets up two Context Listeners. One _untyped_ and one for `fdc3.contact` by calling: `addContextListener (null, handler)`
`addContextListener ("fdc3.contact", handler)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) A `Listener` object is returned for each.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) A promise resolving a `Listener` object is returned for each.
Check that this has an `unsubscribe` method for each. | +| A | 2.joinUserChannel |A joins the first available user channel using:
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `getSystemChannels()` Check channels are returned.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| +| B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | +| B | 4.Broadcast |`fdc3.broadcast()` . | +| A | 5.Receive Context | A's `fdc3.contact` object matches the one broadcast by B, both handlers from step 1 are triggered, and broadcast arrives on the correct listener. | + +- UCMultipleOverlappingListeners1: Perform above test +- UCMultipleOverlappingListeners2: Perform above test, but instead of _untyped_ context listener, in step 2, use `fdc3.instrument` (handler should remain different) \ No newline at end of file From befc2909e82be62424561edd79bc8933308bf9f2 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 25 Oct 2024 14:18:34 -0400 Subject: [PATCH 7/8] Adding separate handlers --- toolbox/fdc3-conformance/User-Channel-Tests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/toolbox/fdc3-conformance/User-Channel-Tests.md b/toolbox/fdc3-conformance/User-Channel-Tests.md index eba6bbbce..d2640ede9 100644 --- a/toolbox/fdc3-conformance/User-Channel-Tests.md +++ b/toolbox/fdc3-conformance/User-Channel-Tests.md @@ -55,7 +55,7 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog | App | Step | Details | |-----|--------------------|-------------------------------------------------------------------------------------------------------------| -| A | 1.addContextListeners | A sets up two Context Listeners. One _untyped_ and one for `fdc3.contact` by calling: `addContextListener (null, handler)`
`addContextListener ("fdc3.contact", handler)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) A `Listener` object is returned for each.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) A promise resolving a `Listener` object is returned for each.
Check that this has an `unsubscribe` method for each. | +| A | 1.addContextListeners | A sets up two Context Listeners. One _untyped_ and one for `fdc3.contact` by calling: `addContextListener (null, handler1)`
`addContextListener ("fdc3.contact", handler2)`
![1.2](https://img.shields.io/badge/FDC3-1.2-green) A `Listener` object is returned for each.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) A promise resolving a `Listener` object is returned for each.
Check that this has an `unsubscribe` method for each. | | A | 2.joinUserChannel |A joins the first available user channel using:
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `getSystemChannels()` Check channels are returned.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| | B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | | B | 4.Broadcast |`fdc3.broadcast()` . | From b20a831e747f32bd49a6d8d3f03c6911c255a479 Mon Sep 17 00:00:00 2001 From: kemerava Date: Fri, 25 Oct 2024 15:04:07 -0400 Subject: [PATCH 8/8] Adding the new error type to the schema --- schemas/api/api.schema.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/schemas/api/api.schema.json b/schemas/api/api.schema.json index 581762274..5e07ecd27 100644 --- a/schemas/api/api.schema.json +++ b/schemas/api/api.schema.json @@ -314,7 +314,7 @@ "type": "string" }, "ResolveError": { - "description": "Constants representing the errors that can be encountered when calling the `findIntent`, `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).", + "description": "Constants representing the errors that can be encountered when calling the `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).", "title": "ResolveError", "enum": [ "DesktopAgentNotFound", @@ -325,7 +325,8 @@ "ResolverUnavailable", "TargetAppUnavailable", "TargetInstanceUnavailable", - "UserCancelledResolution" + "UserCancelledResolution", + "IntentListenerConflict" ], "type": "string" },