docs.intersystems.com
Home

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


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.
To browse all of the First Looks, including others that can be performed on a free cloud instance or web instance, see InterSystems First Looks.
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 and BusinessOperation 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.
Before You Begin
To create this example, you’ll need an instance of InterSystems IRIS and a system with the Java runtime environment (JRE) and a Java IDE of your choice. Select the InterSystems IRIS instance to use for this procedure in one of these ways:
You can configure your IDE to connect to your InterSystems IRIS instance whether it is local, on the network, in the cloud, or on the web. For instructions, see InterSystems IRIS Connection Information and the appropriate section for your IDE in InterSystems IRIS Basics: Connecting an IDE.
You also need to clone or download the FirstLook-JavaHosts sample code from github: https://github.com/intersystems/FirstLook-JavaHosts, and build the JAR files from the included sources. These JAR files must be accessible to InterSystems IRIS.
Follow the instructions in the README to build the JAR files.
Finally, use the Management Portal to create an interoperability-enabled namespace, if your instance does not include one, and ensure that there is no running production in the namespace. Instructions for this step are provided in Creating an Interoperability Namespace in First Look: Connecting Systems Using Interoperability Productions. The URL to open the Management Portal in your browser depends on the type of instance you selected; for information about determining the correct URL, see InterSystems IRIS Connection Information in InterSystems IRIS Basics: Connecting an IDE.
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 in the Additional Settings group 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 java.io.FileOutputStream, java.io.PrintWriter, 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 your 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.
    7. A form is displayed that informs you that you have “Successfully generated class 'JBH.JavaHosts.JavaHostsService'”. Select OK and it returns you to the generate business host form with the fields with their current values.
  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.
    5. A form is displayed that informs you that you have “Successfully generated class 'JBH.JavaHosts.JavaHostsOperation'”. Select OK and it returns you to the generate business host form with the fields with their current values.
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. Select the Enable Now check box.
    3. Select OK and then OK to the Production Updating message.
  2. 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 Enable Now check box clear. You will enable the service in the next step.
    3. Select OK and then OK to the Production Updating message.
  3. 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 and then OK to the Production Updating message.
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 the following. If there are no messages displayed, select Go To Message Viewer.
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:


Send us comments on this page
View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-05-21 11:15:01