First Look: Connecting Systems Using Java Business Hosts
InterSystems: The power behind what matters   

This First Look guide helps you develop interfaces in Java that connect systems together with an InterSystems IRIS™ interoperability production. An interoperability production is an interoperability framework for rapid connectivity and the development of new connectable applications. The production provides built-in connections to a wide variety of message formats and communications protocols. You can easily add other formats and protocols and use a graphic interface to define business logic and message transformations. Productions provide persistent storage of messages, which allow you to audit whether a message is successfully delivered. A production consists of business services, processes, and operations. Business services connect with external systems and receive messages from them. Business processes allow you to define business logic including routing and message transformation. Business operations connect with external systems and send the messages to them.
Solving the Problem of Connecting Systems
When connecting systems together, it can be challenging to get them to understand the other system’s messages and documents. For example, consider the following problem:
You can solve this problem using an InterSystems IRIS production. It provides the framework for defining an interface that accepts messages from the data collection system, transforming the message into one that can be understood by the repair system, and then sending it to the repair system. It also stores a record of the message path.
In this guide, you will learn how to connect two Java programs with a simple production. For demonstration purposes, this document uses very simple Java code. A Java program for the data collection system or the work order system would be more complex and require a DTD schema, but you would use the same procedure to connect them with InterSystems IRIS.
How Interoperability Productions Connect Systems
In its simplest form, a production consists of:
The following illustrates a simple production:
There are some business services and operations provided with InterSystems IRIS. If it has one that supports the message format that a system uses, you can avoid custom coding. But in many cases you will have to develop a custom business service and operation. You can develop these using the InterSystems IRIS ObjectScript or using Java.
Typically, the reason you choose to develop in Java is one of the following:
If you are developing a business service or operation in Java, you can use the Java Business Hosts feature to connect your Java code with the production. This allows you to do all of your business service and business operation coding in Java. The following illustration shows how the Java code connects to the InterSystems IRIS production:
You can use Java Business Hosts with the following kinds of messages:
To connect your Java code to the production, you have to implement the following classes and methods.
The Production object is provided as a parameter to the BusinessService OnInit method. It provides the following methods:
Trying Connecting Systems for Yourself
In this section, you will connect two Java hosts in a production. For demonstration purposes, these are very simple Java programs. Rather than getting messages from an external service, the business service just generates a random message. And the business operation writes the message to a log. Connecting to an external server requires more complex Java code, but you would follow the same process to connect the Java code to the production.
Getting Your System Ready
Before creating this example, you should do the following:
Creating the Credentials
The Java code needs credentials to have access to the production. For this example, you can use the same InterSystems IRIS account that you use to develop a production. For a live system, you would create an account that has the privileges needed to run the production, but not any extra privileges.
To create the credentials, in the Management Portal:
  1. Select an interoperability-enabled namespace.
  2. Specify an ID, such as JavaHostsCredentials, and a user name and password for an account on the InterSystems IRIS system. Then select Save.
Creating the Production and the Initiator and Generating the Business Hosts
In this step, you will create a new production, include the Java Business Host initiator, and generate the business hosts. In the Management Portal:
  1. Select Start New Production, give the production a name, such as JavaHostsProd, leave the other fields with the default values, and select OK twice. This creates a new production, adds the EnsLib.JavaGateway.Initiator component to it, and starts the production. If this step succeeds, the Java Business Hosts page will have a message indicating that the production is running and contains a Java Gateway Service. If you don’t get this message, you may have a problem with the environment variables or Java JDK installation.
  2. Configure the Java Gateway Initiator by selecting Interoperability > Configure > Production and then select the Initiator in the production diagram. You may need to set the following settings depending on your Java environment and environment variables:
    1. Java Home — Specifies the location of the JVM.
    2. Class Path — Specifies the jar files imported in the Java code. This sample only imports the,, and java.util.Random classes, which are included in the Java system jar files. It also uses the intersystems-gateway-3.0.0.jar file which is provided in the install-dir\dev\java\lib\JDK18 directory.
    3. JVM Args — Specifies any arguments you need to specify for you JVM.
    4. If you have specified values for any settings, select Apply.
  3. Return to the Java Business Hosts page by selecting Interoperability > Build > Java Business Hosts and generate the business service host by:
    1. Select Browse and select the jar file generated for the business service.
    2. Select the name of the Java class, such as JavaHosts.JavaHostsService, from the drop-down menu.
    3. Accept the default ObjectScript class name, such as JBH.JavaHosts.JavaHostsService.
    4. For this sample, accept the default Format of Incoming Data, Plain Text.
    5. Select the credentials that you created in the previous step from the drop-down menu.
    6. Select Generate.
  4. Then generate the business operation host by:
    1. Select Browse and select the jar file generated for the business operation.
    2. Select the name of the Java class, such as JavaHosts.JavaHostsOperation, from the drop-down menu.
    3. Accept the default ObjectScript class name, such as JBH.JavaHosts.JavaHostsOperation.
    4. Select Generate.
You have completed creating the production and generating the business hosts. In the next section, `you add the business hosts to the production and configure them.
Configuring the Production
In this step, you will add the business operation and business service to the production and configure them. In the Management Portal:
  1. Select the Operations plus sign to display the Business Operation Wizard.
    1. In the Operation Class drop-down menu, select the business operation, JBH.JavaHosts.JavaHostsOperation, that you generated using the Java Business Hosts page.
    2. Leave the Enabled check box clear.
    3. Select OK.
  2. Select the JBH.JavaHosts.JavaHostsOperation in the production diagram and then in the Settings tab:
    1. Expand Additional Settings and in the LogFile field, enter a file path for the log file, such as c:\practice\javhostslog.txt. Create the directory if it does not exist.
    2. Select the Enabled check box.
    3. Select Apply.
  3. Select the Services plus sign to display the Business Service Wizard.
    1. In the Service Class drop-down menu, select the business service, JBH.JavaHosts.JavaHostsService, that you generated using the Java Business Hosts page.
    2. Leave the Enabled check box clear. You will enable the service in the next step.
    3. Select OK.
  4. Select the JBH.JavaHosts.JavaHostsService service in the production diagram and then in the Settings tab:
    1. In the Target Config Names drop-down menu, select the JBH.JavaHosts.JavaHostsOperation operation.
    2. Optionally, specify an integer value for the Min and Max settings.
    3. Select the Enabled check box.
    4. Select Apply.
You’ve finished configuring the business hosts and the production. All the business hosts in the production diagram should be green and the production should be running. In the next section you will examine the messages.
Running the Production and Examining the Messages
Once you enabled the business service, the production started sending messages. To see the messages, select the Messages tab on the Production Configuration page. The messages are displayed as shown by:
To see the contents of a message, select Go To Message Viewer. Select Search in the message viewer, select a message, and select the Contents tab. The Message Viewer shows you the following:
The production continues to send messages. To stop the production:
Learn More About Java Business Hosts and Productions
Java Business Hosts provides an easy way to create business services and operations in Java. It uses the InterSystems IRIS Java Gateway to do this. Although it is more work to use the Java Gateway directly, it provides more options and capabilities than Java Business Hosts. For more information on Java Business Hosts and the Java Gateway,, see:
For more information about productions, see:

View this article as PDF
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-02-21 22:35:30