Interop

4.7.1

The Interop API enables applications to:

  • offer functionality to other applications (JavaScript and native executables) by registering Interop methods
  • discover applications which offer methods
  • invoke (call) methods on the user’s desktop and across the network
  • stream and subscribe for real-time data using the Streaming API.

We call applications which offer methods and streams Interop servers, and applications which consume them - Interop clients, and collectively - Interop instances.

Interop instances

Any running instance of an Interop application is identified by its Interop instance, which is a set of known key/value pairs uniquely identifying an application:

Environment and region are used to qualify an instance. Usually region is a geographical location and environment refers to the deployment model (development or production).

Key Example (Value) Description
application Client Portfolio Application name
region TICK42 e.g. EMEA, NA, APAC
environment TRAINING e.g. DEV, SIT, UAT, PROD
service null Optional namespace with a region and environment
machine Lambda User machine name
PID 2864 Process ID
user JSmith Currently logged on user

See also the Interop documentation for more details.

object

methodregister
(name: string | MethodDefinition, handler: (args: object, caller: Instance) => void | object) => Promise<void>

Description

Registers a new Interop method.

Parameters

Name
Type
Required
Description

name

string | MethodDefinition

yes

A unique string or a MethodDefinition for the method to be registered.

handler

(args: object, caller: Instance) => void | object

yes

The JavaScript function that will be called when the method is invoked.

Returns

Promise<void>

Example

glue.interop.register(
  {
    name: "Sum", // required - method name
    accepts: "int a, int b", // optional - parameters signature
    returns: "int answer" // optional - result signature
  },
  args => {
    // required - handler function
    return { answer: args.a + args.b };
  }
);
(name: string | MethodDefinition, handler: (args: object, caller: Instance, successCallback: (args?: object) => void, errorCallback: (error?: string | object) => void) => void) => Promise<void>

Description

Registers a new async Interop method. Async methods can delay returning the result from the method invocation.

Parameters

Name
Type
Required
Description

name

string | MethodDefinition

yes

A unique string or a MethodDefinition for the method to be registered.

handler

(args: object, caller: Instance, successCallback: (args?: object) => void, errorCallback: (error?: string | object) => void) => void

yes

The JavaScript function that will be called when the method is invoked. Accepts two extra arguments - a success and an error callbacks. To return a result, you must call the success callback, or the error callback for errors.

Returns

Promise<void>

methodunregister
(definition: string | MethodDefinition) => void

Description

Unregisters an Interop method.

Parameters

Name
Type
Required
Description

definition

string | MethodDefinition

yes

The unique name or the MethodDefinition of the method to be unregistered.

Returns

void

methodinvoke
(method: string | MethodDefinition, argumentObj: object, target: InstanceTarget, options: InvokeOptions, success: InvokeSuccessHandler<any>, error: InvokeErrorHandler) => Promise<InvocationResult<any>>

Description

Invokes an Interop method with some arguments on target servers.

Parameters

Name
Type
Required
Description

method

string | MethodDefinition

yes

The unique name or the MethodDefinition of the method to be invoked.

argumentObj

object

no

A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop method.

target

no

Specifies which servers to target. Can be one of: “best”, “all”, Instance, Instance[].

options

no

An optional [InvokeOptions] object specifying the timeouts to discover a method and to wait for a method reply.

success

no

An InvokeSuccessHandler handler to be called if the invocation succeeds.

error

no

An InvokeErrorHandler handler to be called in case of error.

Returns

Promise<InvocationResult<any>>

Example

glue.interop
  .invoke("Sum", { a: 37, b: 5 }) // everything else is optional
  .then(successResult => {
    console.log(`37 + 5 = ${successResult.returned.answer}`);
  })
  .catch(err => {
    console.error(`Failed to execute Sum ${err.message}`);
  });
(methodDefinition: string | MethodDefinition, options: StreamOptions, successCallback: (args?: object) => void, errorCallback: (error?: string | object) => void) => Promise<Stream>

Description

Creates a new Interop stream.

Parameters

Name
Type
Required
Description

methodDefinition

string | MethodDefinition

yes

A unique string or a MethodDefinition for the stream to be registered.

options

no

The StreamOptions object allows you to pass several optional callbacks which let your application handle subscriptions in a more detailed manner.

successCallback

(args?: object) => void

no

An optional handler to be called if the creation of the stream succeeds.

errorCallback

(error?: string | object) => void

no

An optional handler to be called in case of an error when creating a stream.

Returns

Promise<Stream>

Example

glue.interop
  .createStream({
    name: "MarketData.LastTrades",
    displayName: "Publishes last trades for a symbol",
    objectTypes: ["Symbol"],
    accepts: "String symbol",
    returns: "String symbol, Double lastTradePrice, Int lastTradeSize"
  })
  .then(stream =>
    setInterval(
      () =>
        stream.push({
          symbol: "GOOG",
          lastTradePrice: 700.91,
          lastTradeSize: 10500
        }),
      5000
    )
  )
  .catch(console.error);
methodsubscribe
(methodDefinition: string | MethodDefinition, parameters: SubscriptionParams) => Promise<Subscription>

Description

Subscribes to an Interop stream.

Parameters

Name
Type
Required
Description

methodDefinition

string | MethodDefinition

yes

The unique name or the MethodDefinition of the stream to subscribe to.

parameters

no

An optional SubscriptionParams object with parameters.

Returns

Promise<Subscription>

Example

glue.interop
  .subscribe("MarketData.LastTrades", {
    arguments: { symbol: "GOOG" },
    target: "all"
  })
  .then(subscription => {
    // use subscription
  })
  .catch(error => {
    // subscription rejected or failed
  });
methodservers
(filter: MethodFilter) => Instance[]

Description

Returns all Interop aware applications. Optionally, the list can be filtered to return only servers providing specific Interop method(s) by passing a methodFilter.

Parameters

Name
Type
Required
Description

filter

no

An object describing a filter matching one or more Interop methods.

Returns

Instance[]

methodmethods

Description

Returns all methods that match the passed filter. If no filter is specified, returns all methods.

Parameters

Name
Type
Required
Description

filter

no

An object describing a filter matching one or more Interop methods.

Returns

MethodDefinition[]

(callback: (method: MethodDefinition) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when a method is added for the first time by any application.

Parameters

Name
Type
Required
Description

callback

(method: MethodDefinition) => void

yes

A handler to be called when the event fires.

Returns

UnsubscribeFunction

(callback: (method: MethodDefinition) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when a method is removed from the last application offering it.

Parameters

Name
Type
Required
Description

callback

(method: MethodDefinition) => void

yes

A handler to be called when the event fires.

Returns

UnsubscribeFunction

(callback: (server: Instance) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an application offering methods is discovered.

Parameters

Name
Type
Required
Description

callback

(server: Instance) => void

yes

A handler to be called when the event fires.

Returns

UnsubscribeFunction

(callback: (server: Instance) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an app offering methods stops offering them or exits.

Parameters

Name
Type
Required
Description

callback

(server: Instance) => void

yes

A handler to be called when the event fires.

Returns

UnsubscribeFunction

(callback: (info: { server: Instance; method: MethodDefinition; }) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an application starts offering a method. This will be called every time a server starts offering the method, whereas methodAdded() will be called only the first time the method is registered.

Parameters

Name
Type
Required
Description

callback

(info: { server: Instance; method: MethodDefinition; }) => void

yes

Returns

UnsubscribeFunction

(callback: (info: { server: Instance; method: MethodDefinition; }) => void) => UnsubscribeFunction

Description

Subscribes for the event which fires when a server stops offering a method. This will be called every time a server stops offering the method, whereas methodRemoved() will be called only when the method is removed from the last application offering it.

Parameters

Name
Type
Required
Description

callback

(info: { server: Instance; method: MethodDefinition; }) => void

yes

A handler to be called when the event fires.

Returns

UnsubscribeFunction

Description

Returns all Interop methods registered by a server.

Parameters

Name
Type
Required
Description

server

yes

An Interop Instance identifying an application.

Returns

MethodDefinition[]

Properties

Instance of the current application.

object

Description

Extends InvocationResultCore. Results from a method invocation.

Properties

An array of invocation results.

any[]

An array of error objects.

T

Returned object.

Method definition of the method that was invoked.

Instance of the application that executed the method.

any

Arguments of the invocation.

string

Message from the application that executed the method.

number

Status sent by the application that executed the method.

object

Description

A subscription request object handled by the server that has created the stream. It can be accepted or rejected.

methodaccept
() => void

Description

Accepts the subscription request.

Returns

void

(branchKey: string) => void

Description

Accepts the request on a stream branch.

Parameters

Name
Type
Required
Description

branchKey

string

yes

Key of the branch on which to accept the request.

Returns

void

methodreject
(reason: string) => void

Description

Rejects the request.

Parameters

Name
Type
Required
Description

reason

string

no

Reason for rejecting the request.

Returns

void

Properties

Instance of the application that wants to subscribe to the stream.

object

Arguments passed with the subscription request.

object

Description

Optional handlers that can be supplied when creating streams.

Properties

(request: SubscriptionRequest) => void

Subscribes for subscription requests. These can be accepted, rejected or accepted on a custom branch. If this handler is attached, each request should be explicitly accepted.

(request: StreamSubscription) => void

Subscribes to the event which fires when a stream subscription is added.

(request: StreamSubscription) => void

Subscribes to the event which fires when a stream subscription is removed.

object

Description

Object describing an Interop stream.

methodpush
(data: object, branches: string | string[]) => void

Description

Push data to the stream. If a branches argument is passed, the data will be sent to the specified stream branch(es) only.

Parameters

Name
Type
Required
Description

data

object

yes

Data to push.

branches

string | string[]

no

To which branch(es) to push data.

Returns

void

methodbranches
() => StreamBranch[]

Description

Returns the list of available stream branches. If key is specified, returns the corresponding stream branch or null.

Returns

StreamBranch[]

methodbranches
() => StreamBranch[]

Parameters

Name
Type
Required
Description

key

string

yes

Returns

StreamBranch

methodbranches
() => StreamBranch[]

Parameters

Name
Type
Required
Description

key

string

no

Returns

StreamBranch | StreamBranch[]

Description

Returns a list of active subscriptions to the stream.

Returns

StreamSubscription[]

methodclose
() => void

Description

Closes the stream. This will close all subscriptions.

Returns

void

Properties

Stream definition object.

string

Name of the stream.

object

Description

A stream branch created by the application.

Description

All subscriptions to that branch.

Returns

StreamSubscription[]

methodclose
() => void

Description

Closes the stream branch.

Returns

void

methodpush
(data: object) => void

Description

Pushes data to this branch only.

Parameters

Name
Type
Required
Description

data

object

yes

Data to push.

Returns

void

Properties

string

Branch key.

object

Description

An object describing a subscription to an Interop stream.

methodclose
() => void

Description

Closes the subscription. This will not close the stream.

Returns

void

methodpush
(data: object) => void

Description

Pushes data to this subscription only.

Parameters

Name
Type
Required
Description

data

object

yes

Data to push.

Returns

void

Properties

any

Arguments used when the subscription was made.

string

The key of the stream branch to which the subscription was made.

Instance of the subscriber.

The stream to which the subscription was made.

object

Description

Stream subscription made by an application.

methodonData
(callback: (data: StreamData) => void) => void

Parameters

Name
Type
Required
Description

callback

(data: StreamData) => void

yes

Returns

void

methodonClosed
(callback: (info: OnClosedInfo) => void) => void

Parameters

Name
Type
Required
Description

callback

(info: OnClosedInfo) => void

yes

Returns

void

methodonFailed
(callback: (err: any) => void) => void

Parameters

Name
Type
Required
Description

callback

(err: any) => void

yes

Returns

void

(callback: (server: Instance, reconnect: boolean) => void) => void

Parameters

Name
Type
Required
Description

callback

(server: Instance, reconnect: boolean) => void

yes

Returns

void

methodclose
() => void

Description

Closes the subscription.

Returns

void

Properties

object

Arguments used to make the subscription.

Instances of the applications providing the stream, that we have subscribed to

Stream definition.

object

Description

Optional object with parameters passed to subscribe() when subscribing to a stream.

Properties

Specifies which servers to target. Can be one of: “best”, “all”, Instance, Instance[].

object

A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop stream.

number

Timeout to wait for a stream reply.

Default: 30000

number

Timeout to discover the stream, if not immediately available.

Default: 30000

(data: StreamData) => void

Subscribe for the event which fires when new data is received.

() => void

Subscribe for the event which fires when the subscription is closed.

(server: Instance, reconnect: boolean) => void

object

Description

Stream data received by the subscriber.

Properties

any

Data from the stream.

Instance of the application publishing the stream.

object

Arguments used when the subscription was made.

string

Message from the publisher of the stream.

boolean

If true, the data was sent to this application only.

object

Description

An object describing an Interop method registered by an application.

Properties

string

The name of the method. Must be unique.

string[]

The entities this method is meant to work with.

string

The actual name of the method, used in UI applications.

string

Signature describing the parameters that the method expects.

string

Signature describing the properties of the object the method returns.

string

Description of what the method does. Useful for documentation purposes and for UI clients.

number

Method version.

boolean

If true, the method is a stream.

() => Instance[]

Returns all servers that provide the method.

object

Description

An object describing a filter matching one or more Interop methods.

Properties

string

The name of the method. Must be unique.

string[]

The entities this method is meant to work with.

string

The actual name of the method, used in UI applications.

string

Signature describing the parameters that the method expects.

string

Signature describing the properties of the object the method returns.

string

Description of what the method does. Useful for documentation purposes and for UI clients.

object

Description

Each Interop application is identified by its Interop instance, which is a set of known key/value pairs.

Description

Returns all methods registered by that instance.

Returns

MethodDefinition[]

Description

Returns all streams registered by that instance.

Returns

MethodDefinition[]

Properties

string

Unique application name.

string

Application name

number

Process ID of the instance.

string

Name of the machine the instance is running on.

string

Name of the user who has started the instance.

string

Environment in which the application is running.

string

Region in which the application is running.

string

Service string of the application.

string

(Glue42 Desktop 3.0 only) Unique string identifying the application.

string

(Glue42 Desktop 3.0 only) Window ID of the instance. Only set if running in a Glue42 window.

string

(Glue42 Desktop 3.0 only) Gateway peer ID of the instance.

boolean

(Glue42 Desktop 3.0 only) A flag indicating whether the instance is running on a local machine or not. Taken into account when a Gateway mesh is present - local instances are preferred when invoking methods.

string

API version

object

Description

Method invocation options.

Properties

number

Timeout to discover the method, if not immediately available.

Default: 3000

number

Timeout to wait for a method reply.

Default: 10000

object

Description

Result from a method invocation.

Properties

T

Returned object.

Method definition of the method that was invoked.

Instance of the application that executed the method.

any

Arguments of the invocation.

string

Message from the application that executed the method.

number

Status sent by the application that executed the method.

object

Description

Addition information around subscription being closed

Properties

string

object

{
    info: MethodDefinition;
};

enumeration

Description

Which Interop server(s) to target when invoking Interop methods or subscribing to Interop streams.

  • "best"
  • "all"
  • "skipMine"
  • Instance
  • Instance[]

function

(result: InvocationResult) => void

Description

Handler to be called if the method invocation succeeds.

Parameters

Name
Type
Required
Description

result

yes

Result from the method invocation.

Returns

void

function

(error: { method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; }) => void

Description

Handler to be called in case of method invocation error.

Parameters

Name
Type
Required
Description

error

{ method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; }

yes

An error object.

Returns

void