Connecting with External Language Servers

When you register the PEX component written in an external language, you specify an external language server that the production uses to communicate with the remote class. This external language server is commonly referred to as a gateway.

In most languages, the built-in external language server for your PEX language contains all you need to run a PEX production; you do not need to create a custom server. However, if you are using Java, the external language server must include a special utility jar file on its classpath. So your default or custom Java server must include install-dir/dev/java/lib/1.8/intersystems-utils-version.jar on its classpath, where install-dir is the directory where your InterSystems product is installed. If you are manually entering the location of this file, you can use the keyword $$IRISHOME to identify the installation directory.

Sharing a Connection

In some cases, you might want a PEX adapter to use the connection of its associated PEX business service or business operation rather than using a separate external language server connection. When each PEX component uses a separate connection, objects passed between the components must be serialized into JSON strings, preventing you from directly passing an object between the components. By sharing a connection, your adapter and business host can pass an object directly and get the same object back. To share a connection, the PEX adapter and its associated PEX business host must be written in the same external language.

To indicate that the PEX adapter should share a connection with its business service or business operation, use the Management Portal to select the business host’s Alternative Adapter Connection > Use Host Connection setting. Once this setting has been enabled, the PEX framework ignores the external language server setting that was specified when the PEX adapter was registered.

The following examples demonstrate the advantages of using a shared connection between an adapter and its associated business host.

Business Service and Inbound Adapter

When an inbound adapter shares a connection with the business service, the business service receives the same object that was sent by the inbound adapter. For example:

// Code from the inbound adapter:
public void OnTask() throws Exception {
  SimpleObject request = new SimpleObject("message #1");
  String response = (String) BusinessHost.ProcessInput(request);
}

// Code from the business service:
public Object OnProcessInput(Object messageInput) throws Exception {
  SimpleObject obj = (SimpleObject)messageInput;
  System.out.print("\r\n[Java] Object received: " + obj.value);
  return "...Service received " + obj.value;
}

In contrast, the following code shows how you would have to handle an object sent to the business service from the inbound adapter if they do not share a connection.

// Code from the inbound adapter:
public void OnTask() throws Exception {
  SimpleObject request = new SimpleObject("message #1");
  String response = (String) BusinessHost.ProcessInput(request);
}

// Code from the business service:
public Object OnProcessInput(Object messageInput) throws Exception {
  com.intersystems.jdbc.IRISObject obj = (com.intersystems.jdbc.IRISObject)messageInput;
  System.out.print("\r\n[Java] Object received: " + obj.get("value"));
  return "...Service received" + obj.get("value");
}

Business Operation and Outbound Adapter

When an outbound adapter shares a connection with the business operation, the adapter receives the same object that was sent by the business operation. For example:

// Code from the business operation:
public Object OnMessage(Object request) throws Exception {
  SimpleObject myObj = new SimpleObject("my string");
  Adapter.invoke("passObj", myObj);
  return null;
}

// Code from the associated adapter:
public Object passObj(SimpleObject obj) {
  System.out.print("\r\n[Java]Object received: " + obj.value);
  return null;
}

In contrast, the following code shows how you would have to handle an object sent to the adapter from the business operation if they do not share a connection.

// Code from the business operation:
public Object OnMessage(Object request) throws Exception {
  SimpleObject myObj = new SimpleObject("my string");
  Adapter.invoke("passObj", myObj);
  return null;
}

// Code from the associated adapter:
public Object passObj(com.intersystems.jdbc.IRISObject obj) {
  System.out.print("\r\n[Java]Object received: " + obj.get(“value”));
  return null;
}

PEX API Reference

Registering a PEX Component