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

Jump to bottom

updated spec with more detailed explanation of the 'default' channel #168

Merged
merged 1 commit into from
Feb 27, 2020
Merged

updated spec with more detailed explanation of the 'default' channel #168

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.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/api/api-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,10 +150,36 @@ The 'system' channels include a 'default' channel which serves as the backwards
### Joining Channels
Apps can join channels. An app can only be joined to one channel at a time. When an app joins a channel it will automatically recieve the current context for that channel, except if the channel joined is the 'default'.

When an app is joined to a channel, calls to fdc3.broadcast and listeners added through fdc3.addContextListener will be routed to that channel. If an app is not explicitly joined to a channel, it is on the 'default' channel. It is up to the desktop agent to determine the behavior of the 'default' channel, and if context is automaticaly broadcast over it or not.
When an app is joined to a channel, calls to fdc3.broadcast and listeners added through fdc3.addContextListener will be routed to that channel. If an app is not explicitly joined to a channel, it is on the 'default' channel.
The `default` channel has special behavior that makes it different from other channels. See a detailed description [below](#default-channel-behavior).
Copy link
Contributor

Choose a reason for hiding this comment

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

The special behaviour of the default channel should also be documented clearly in the API documentation, not only in the spec, as people are more likely to read the docs than the whole spec.

The spec doesn't clarify if the default channel is returned by getSystemChannels?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Agreed about updates to the API docs - will do.

Re: getSystemChannels - there is definitely a gap here. There are arguments either way - would be great to get the opinions of others who have already built or are using channel linking today.


It is possible that a call to join a channel could be rejected. If for example, the desktop agent wanted to implement controls around what data apps can access.

### *default* Channel Behavior
Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. Always, there SHOULD be a clear UX indicator of what channel an app is joined to.

The one exception is the `default` channel. Because apps are automatically added to the `default` channel, the message routing behavior is different in order to prevent poor user experiences from unexpected context behavior. The behavior for the `default` channel is:

- All broadcasts (`fdc3.broadcast` when the app is on default, or `default.broadcast`) update the `default` context
- `fdc3.addContextListener` will NOT receive context events when the app is joined to the `default` channel
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't mind this, but it is kind of unexpected behaviour, so we should be really clear that this is the case, and discuss it with the API working group.

It is also different from how broadcast and addContextListener worked in version 1.0, so we should clarify that this is a breaking change, and consider making the version 2.0.0 instead of 1.1.0 to indicate this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Definitely this is significant and needs to be vetted by the WG. I'm OK with adding language calling out that this may be a breaking change for some (or event many) 1.0 implementations. However, I don't believe that this is a breaking change for the spec requiring a 2.x designation - since the 1.0 spec intentionally leaves this behavior open-ended.

Copy link

Choose a reason for hiding this comment

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

Consider an simple application on 1.0 without any UI/frame/functionality for channels and all it does it fdc3.broadcast and fdc3.addContextListener.
Can it move to 1.1 without changing code and work as expected? Based on the above, the app would stop receiving any context but it can still send context on default channel. Is that correct? That seems confusing.

I think the difference in behavior of fdc3.addContextListener and fdc3.broadcast around default channel is confuisng.

Copy link

Choose a reason for hiding this comment

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

All my apps have just following two calls in their code base:
fdc3.broadcast and fdc3.addContextListener. They know nothing about being in a channel or not (which I think is very important).
I have a frame around that does channel management.
My apps can be in that custom frame (where they get channels) or in regular DesktopAgent/Windows frame (where there is no channels).

If I am understanding it correctly, basically any platform that doesn't implement Channels API, is useless for interop purposes because they can send stuff but not receive.

Copy link

Choose a reason for hiding this comment

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

I think this line in particular needs clarification or rewording, mostly because the phrase "when the app is joined" itself is ambiguous. This can be interpreted as:

  • Context listeners will not receive a context updated event at the moment the channel is joined
  • Context listeners will not receive context updated events while the channel is joined

- Explicit listening on the `default` channel through `default.addContextListener` and calling `default.getCurrentContext` will return context updates for the channel.

#### Examples

An app gets the current context of the `default` as a fallback if no other context is set.

```js
let dChan = await fdc3.getOrCreateChannel("default");
let ctx = await dChan.getCurrentContext("fdc3.instrument");
```

An wants to respond to all context changes, whether on a joined channel or the `default` channel.

```js
let dChan = await fdc3.getOrCreateChannel("default");
let listener = dChan.addContextListener(contextListener);
```

### Direct Listening and Broadcast on Channels
While joining channels automates a lot of the channel behavior for an app, it has the limitation in that an app can belong to only one channel at a time. Listening and Broadcasting to channels using the _Channel.addBroadcastListener_ and the _Channel.broadcast_ APIs provides an app with fine-grained controls for specific channels. This is especially useful for working with dynamic _App Channels_.

Expand Down