Make optional: fdc3.joinChannel and fdc3.leaveChannel

[kriswest]

Output from the Channels, Feeds & Transactions discussion group: #420

The fdc3.joinChannel and fdc3.leaveChannel functions provide programmatic access to joining and leaving channels. Once joined to a channel, the top-level fdc3.broadcast function will broadcast to that channel and fdc3.addContextListener function will receive those broadcasts. However, it is intended that the desktop agent provide UI to enable joining and leaving (system) channels, making these functions redundant and occasionally giving rise to requests for additional functions needed to use these alongside the built-in UIs (e.g. #313). Further, the spec doesn't currently limit which channels can be joined - allowing the unintended joining of 'App channels' and problems with a lack of display metadata for them (e.g. #243).

Consider deprecating these functions and removing them from the API in favour of the requirement that the desktop agent provide UI for joining channels.

[kriswest]

I would consider making these functions (fdc3.joinChannel and fdc3.leaveChannel) optional, rather than deprecating them. If the desktop agent doesn't provide UI (e.g. to a native application with its own titlebar) then an alternative means of joining a channel is required.

Further, if we accept #242 these functions will change - or #242 can be simplified if we decide to deprecate the functions (#242 would simply become a spec addition saying that you can support multiple channels if you want to, there are no API additions for this).

[kriswest]

Recommendation from discussion group:

• Take the soft option and make the joinChannel, leaveCurrentChannel, getSystemChannels can all be made optional (not required for compliance with specification
• Differentiate these in the documentation better (e.g. break them out in the Nav)
• Improve the documentation of addContentListener to mention joining the channel
• Rename joinChannel -> joinUserChannel and deprecate joinChannel
• Consider how to do feature detection, options:
  • just check for the function? (normal for Javascript)
  • return an exception from the function (normal for Java/.Net)
  • update the ImplementationMetadata object to have fields to support this
  • Implement an isFeatureSupported function as Plexus does: https://github.com/finos/plexus-interop/blob/a40456ec649c6f25be6aae5b82daef75657875c7/web/packages/common-api-impl/src/api/client-api.ts#L56

[Qiana-Citi]

@kriswest I agree that in many cases it’s users who join/leave channels, so fdc3.joinChannel/fdc3.leaveChannel is usually used together with UI functions. But I cannot ignore the fact that in some of our real use-cases, fdc3.joinChannel/fdc3.leaveChannel is used for pure cross-app communication without any UI interoperations. In such cases, apps need some app channels to share info between each other for app feature purpose rather than user interaction purpose. So from my perspective, it’s better not to force to bound channel to UI and leave the possibility to use channel programmatically.

However, it is intended that the desktop agent provide UI to enable joining and leaving (system) channels, making these functions redundant and occasionally giving rise to requests for additional functions needed to use these alongside the built-in UIs (e.g. #313).

[kriswest]

@Qiana-Citi for pure cross-app communication without any UI interactions you should use app channels, rather than the (perhaps poorly named) 'System channels'. These are interacted with through the Channel API directly rather than through the top=level desktop agent window.fdc3.

E.g.

  const myChannel = await fdc3.getOrCreateChannel("myChannel");
  const myChannel.addContextListener(null, context => {});
  myChannel.broadcast(myContextObject);

See https://fdc3.finos.org/docs/api/spec#direct-listening-and-broadcast-on-channels for more details.

This issue is not proposing to remove AppChannels - only that the joinChannel and leaveCurrentChannel functions should become optional (so not needed for a Desktop Agent to be compliant with the FDC3 spec) - although we should also establish how an app could test for whether they are supported.