Skip to content

Commit

Permalink
Merge pull request #1403 from finos/fdc3-for-web-deprecate-methods.ts…
Browse files Browse the repository at this point in the history 
…-fns

Deprecating functions in Methods.ts
  • Loading branch information
@kriswest
kriswest authored Oct 31, 2024
2 parents 001b6cc + 33e8532 commit 15e9214
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 25 deletions.
27 changes: 2 additions & 25 deletions docs/api/supported-platforms.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,19 +82,15 @@ Hence, FDC3 apps SHOULD obtain access to a `DesktopAgent` object (`fdc3`) by imp

In prior versions of FDC3 (<= 2.1) Apps were required to use the 'Desktop Agent Preload' interface, i.e. they relied on the existence of the `window.fdc3` object, which meant that apps running in a standard web browser had to import libraries specific to the Desktop Agent implementation in use. From FDC3 2.2 onwards the 'Desktop Agent Proxy' interface is available, which allows apps in a standard web browser to connect to any Desktop Agent that implements that interface.

Hence, from FDC3 2.2 onwards apps SHOULD call the `getAgent()` to retrieve a `DesktopAgent` API interface.
Hence, from FDC3 2.2 onwards apps SHOULD call `getAgent()` to retrieve a `DesktopAgent` API interface.

:::

As web applications can navigate to or be navigated by users to different URLs and become different applications, validation of apps identity is often necessary. The web application's current URL is passed to web browser-based Desktop Agents to allow them to establish the app's identity - usually connecting it with an App Directory record already known to the Desktop Agent. For more details on identity validation see the Identity Validation section of the [Web Connection Protocol (WCP)](specs/webConnectionProtocol).

### Usage

Once you've retrieved a `DesktopAgent` interface, there are two main ways FDC3 can be used from web applications:

#### 1. Direct Usage

Simply use the interface you've retrieved and address the API directly:
Once you've retrieved a `DesktopAgent` interface you may use its functions to communicate with the Desktop Agent and through it, other applications:

```js
import { DesktopAgent, getAgent } from "@finos/fdc3";
Expand All @@ -110,25 +106,6 @@ const desktopAgent: DesktopAgent = await getAgent();
await sendData(desktopAgent);
```

#### 2. ES6-style Function Wrappers

The npm package provides a wrapper around FDC3, allowing you to use it with ES6 import syntax:

```javascript
import { raiseIntent } from "@finos/fdc3";

await raiseIntent("ViewAnalysis", {
type: "fdc3.instrument",
id: { ticker: "AAPL" }
});
```

:::tip

Please note that the wrapper functions will not work with the `dontSetWindowFdc3` parameter to `getAgent()` set to `true` as they rely on finding the `DesktopAgent` reference at `window.fdc3`.

:::

## Native

The FDC3 Standard currently only defines language specific API bindings for JavaScript/TypeScript and .NET, but is intended to be implemented in other languages (which can make use of the [Desktop Agent Communication Protocol (DACP)](../specs/desktopAgentCommunicationProtocol) as a wire protocol, but need to define a suitable connection protocol, which includes a defined communication channel to do so).
Expand Down
89 changes: 89 additions & 0 deletions src/api/Methods.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@ const UnavailableError = new Error('FDC3 DesktopAgent not available at `window.f
const TimeoutError = new Error('Timed out waiting for `fdc3Ready` event.');
const UnexpectedError = new Error('`fdc3Ready` event fired, but `window.fdc3` not set to DesktopAgent.');

/**
* @deprecated This function depends on window.fdc3 (which may not be set for web-based desktop agents)
* and does not wait on the fdc3Ready event, so it may return errors on container-based desktop agents.
* Use `const fdc3 = getAgent()` to retrieve (and wait for) a reference to the FDC3 API instead.
*/
function rejectIfNoGlobal(f: () => Promise<any>) {
return window.fdc3 ? f() : Promise.reject(UnavailableError);
}
Expand All @@ -51,6 +56,10 @@ function rejectIfNoGlobal(f: () => Promise<any>) {
*
* @param waitForMs The number of milliseconds to wait for the FDC3 API to be
* ready. Defaults to 5 seconds.
*
* @deprecated This function depends on window.fdc3 (which may not be set for
* web-based desktop agents). Use `const fdc3 = getAgent()` to retrieve (and
* wait for) a reference to the FDC3 API instead.
*/
export const fdc3Ready = async (waitForMs = DEFAULT_TIMEOUT): Promise<void> => {
return new Promise((resolve, reject) => {
Expand All @@ -77,6 +86,10 @@ function isString(app: AppIdentifier | string | undefined): app is string {
return !!app && typeof app === 'string';
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function open(app: AppIdentifier | string, context?: Context): Promise<AppIdentifier> {
if (isString(app)) {
return rejectIfNoGlobal(() => window.fdc3.open(app, context));
Expand All @@ -85,18 +98,34 @@ export function open(app: AppIdentifier | string, context?: Context): Promise<Ap
}
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function findIntent(intent: Intent, context?: Context, resultType?: string): Promise<AppIntent> {
return rejectIfNoGlobal(() => window.fdc3.findIntent(intent, context, resultType));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function findIntentsByContext(context: Context, resultType?: string): Promise<AppIntent[]> {
return rejectIfNoGlobal(() => window.fdc3.findIntentsByContext(context, resultType));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function broadcast(context: Context): Promise<void> {
return rejectIfNoGlobal(() => window.fdc3.broadcast(context));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function raiseIntent(intent: Intent, context: Context, app?: AppIdentifier | string): Promise<IntentResolution> {
if (isString(app)) {
return rejectIfNoGlobal(() => window.fdc3.raiseIntent(intent, context, app));
Expand All @@ -105,6 +134,10 @@ export function raiseIntent(intent: Intent, context: Context, app?: AppIdentifie
}
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function raiseIntentForContext(context: Context, app?: AppIdentifier | string): Promise<IntentResolution> {
if (isString(app)) {
return rejectIfNoGlobal(() => window.fdc3.raiseIntentForContext(context, app));
Expand All @@ -113,10 +146,18 @@ export function raiseIntentForContext(context: Context, app?: AppIdentifier | st
}
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function addIntentListener(intent: Intent, handler: IntentHandler): Promise<Listener> {
return rejectIfNoGlobal(() => window.fdc3.addIntentListener(intent, handler));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function addContextListener(
contextTypeOrHandler: ContextType | null | ContextHandler,
handler?: ContextHandler
Expand All @@ -129,10 +170,18 @@ export function addContextListener(
}
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function addEventListener(eventType: FDC3EventType, handler: EventHandler): Promise<Listener> {
return rejectIfNoGlobal(() => window.fdc3.addEventListener(eventType, handler));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getUserChannels(): Promise<Channel[]> {
return rejectIfNoGlobal(() => {
//fallback to getSystemChannels for FDC3 <2.0 implementations
Expand All @@ -144,11 +193,19 @@ export function getUserChannels(): Promise<Channel[]> {
});
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getSystemChannels(): Promise<Channel[]> {
//fallforward to getUserChannels for FDC3 2.0+ implementations
return getUserChannels();
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function joinUserChannel(channelId: string): Promise<void> {
return rejectIfNoGlobal(() => {
//fallback to joinChannel for FDC3 <2.0 implementations
Expand All @@ -160,35 +217,67 @@ export function joinUserChannel(channelId: string): Promise<void> {
});
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function joinChannel(channelId: string): Promise<void> {
//fallforward to joinUserChannel for FDC3 2.0+ implementations
return joinUserChannel(channelId);
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getOrCreateChannel(channelId: string): Promise<Channel> {
return rejectIfNoGlobal(() => window.fdc3.getOrCreateChannel(channelId));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getCurrentChannel(): Promise<Channel | null> {
return rejectIfNoGlobal(() => window.fdc3.getCurrentChannel());
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function leaveCurrentChannel(): Promise<void> {
return rejectIfNoGlobal(() => window.fdc3.leaveCurrentChannel());
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function createPrivateChannel(): Promise<PrivateChannel> {
return rejectIfNoGlobal(() => window.fdc3.createPrivateChannel());
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getInfo(): Promise<ImplementationMetadata> {
return rejectIfNoGlobal(() => window.fdc3.getInfo());
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function getAppMetadata(app: AppIdentifier): Promise<AppMetadata> {
return rejectIfNoGlobal(() => window.fdc3.getAppMetadata(app));
}

/**
* @deprecated Importing individual FDC3 API calls is deprecated. Use `getAgent` to retrieve
* an FDC3 API reference and use the functions that it provides instead.
*/
export function findInstances(app: AppIdentifier): Promise<AppIdentifier[]> {
return rejectIfNoGlobal(() => window.fdc3.findInstances(app));
}
Expand Down

0 comments on commit 15e9214

Please sign in to comment.