Workshop: PEX

This repository contains the materials and some examples you can use to learn the basic concepts of PEX (Production EXtension) in IRIS Interoperability.

You can find more in-depth information in https://learning.intersystems.com.

New to IRIS Interoperability framework? Have a look at IRIS Interoperability Intro Workshop.

What do you need to install?

• Git
• Docker (if you are using Windows, make sure you set your Docker installation to use “Linux containers”).
• Docker Compose
• Visual Studio Code + InterSystems ObjectScript VSCode Extension

Setup

Build the image we will use during the workshop:

$ git clone https://github.com/intersystems-ib/workshop-pex
$ cd workshop-pex
$ docker compose build

Examples

(a). FirstDemo interoperability Production

• Run the container we will use in the workshop:

docker compose up

• Open the Management Portal.
• Login using the default superuser/ SYS account.
• Click on Workshop.PEX.FirstDemo.Production to access the sample interoperability production we will use. You can access also through Interoperability > User > Configure > Production.

(b). Test MessageRouter + FirstOperation

• Click on FirstOperation Business Operation.
• Examine the Settings tab, pay attention to: Class Name and Remote Business Operation section. What is the Java Gateway server that is being used?
• Click on MessageRouter Business Process.
• In the Actions tab, click on Test. In the Request Type choose Ens.StringRequest and enter some text in the StringValue field. Send the test message.
• Inspect the resulting Visual Trace.
• Notice the message that receives each component and their contents.
• Message Router transforms a Ens.StringRequest to a EnsLib.PEX.Message. You can see the data transform here Workshop.PEX.FirstDemo.DT.StringRequest2PEX.
• FirstOperation is a very simple Business Operation that is implemented on Java. We will go through it in the next section.

(c). Understanding FirstOperation and Java Gateway

• In VS Code, open https://github.com/intersystems-ib/workshop-pex/blob/master/java/src/workshop/pex/FirstOperation.java. This is the actual FirstOperation implementation.
• Have a look at the methods and properties. Can you find where is handling the incoming FirstMessage request?
• Go through https://github.com/intersystems-ib/workshop-pex/blob/master/iris/Dockerfile. This Dockerfile is responsible for:
  1. Compiling Java source code & building JAR files (FirstDemo.jar).
  2. Registering an External Language Server PEXJavaServer in IRIS, which starts and manages the Java Gateway process
  3. Loading the ObjectScript classes and setting the production to auto-start.
• Notice that a dedicated jgw is no longer needed: the Java Gateway is handled by IRIS through an External Language Server (ELS). The IRIS image already includes a JDK 11 and the InterSystems Java libraries (/usr/irissys/dev/java/lib/1.8/, e.g. intersystems-utils-4.2.2.jar, which contains the PEX classes), so no builder stage or local jars are needed.
• Inspect https://github.com/intersystems-ib/workshop-pex/blob/master/docker-compose.yml and notice the only container we are using. In this scenario the gateway hostname is the same as IRIS’s hostname.

(d). Adding a Business Service and Business Process

• In VS Code, open https://github.com/intersystems-ib/workshop-pex/blob/master/java/src/workshop/pex/FirstService.java and https://github.com/intersystems-ib/workshop-pex/blob/master/java/src/workshop/pex/FirstProcess.java.
• Have a look at the methods and properties. What are doing those components?
• Can you find them in the running interoperability production?
• Try to understand what are doing FirstService and FirstProcess. Go through their implementation and Settings tab in the production, and finally enable them and check what happens.

(e). Make some changes

• Make some changes on FirstService.java, FirstProcess.java or FirstOperation.java (e.g. add some extra LOGINFO).
• Re-compile using docker-compose build and run again.
• Test your changes.

Explore more complex scenarios

Have a look at those great examples on using PEX with InterSystems IRIS:

• https://github.com/intersystems-community/irisdemo-demo-kafka