Skip to main content
Previous section

Java Business Hosts

Introduction to Java Business Hosts

Important:

In previous releases of InterSystems IRIS before the PEX framework was available, Java Business Hosts provided a way to create new business services and business operations using Java without need for any ObjectScript coding. This feature is now deprecated; use the PEX framework instead.

You can use Java Business Hosts with the following kinds of messages:

  • Plain text

  • XML

  • X12

  • EDIFACT

  • HL7(InterSystems IRIS for Health and HealthShare Health Connect only)

  • ASTM (InterSystems IRIS for Health and HealthShare Health Connect only)

To develop a production using Java Business Services and Operations, you do the following:

  • Write your Java code implementing the com.intersystems.gateway.bh.BusinessService and the com.intersystems.gateway.bh.BusinessOperation classes. These classes enable your Java code to send messages to a production and receive messages from a production.

  • Compile your Java classes into jar files.

  • Use the Java Business Host page in the Management Portal to add a EnsLib.JavaGateway.Initiator component to a production and then generate Java Business Services and Operations from your jar files.

  • Add the Java Business Services and Operations to the production using the Production Configuration page in the Management Portal.

  • Adjust any settings on your Java Business Services and Operations using the Product Configuration page.

  • Add any other Business Services, Business Processes, and Business Operations to your production. For example, you can add a router Business Process or a Data Transformation to your production.

  • Use the production infrastructure to manage and monitor your production. For example, you can examine messages and trace their path through the production.

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, see Using the Java Gateway.

Developing Java Business Services and Operations

This section describes how to implement the Java code for business services and business operations. To create a business service or business operation, you implement the following classes:

  • com.intersystems.gateway.bh.BusinessService

  • com.intersystems.gateway.bh.BusinessOperation

These classes are defined in the intersystems-gateway-3.0.0.jar file provided in the install-dir\dev\java\lib\JDK18 directory. In addition to the BusinessService and BusinessOperation classes, this jar file defines the com.intersystems.gateway.bh.Production, which provides access to the production and the Business Service.

For receiving messages from an external service, you implement a Java application that listens to messages and includes the Java class:

com.intersystems.gateway.bh.BusinessService

with the following methods:

  • OnInit: — this method is called when the production starts or the business service is enabled. It typically starts a listener that will receive messages. The listener receives the messages from the external service and then sends them to the business service in the production by calling the method Production.SendRequest(). The production is passed in as an argument to OnInit. Your code should save it so that it can call SendRequest in the listener.

  • OnTearDown: — this method is called when the production is stopped or the business service is disabled. It typically stops the listener.

To define settings in the Business Service, define a static string named SETTINGS, that has a string value of a comma separated list of settings name. For example, the following defines settings named MIN and MAX:

  public static final String SETTINGS = "Min,Max";
Copy code to clipboard

For sending messages from the production to an external service, you implement a Java application, which includes the Java class:

com.intersystems.gateway.bh.BusinessOperation

with the following methods:

  • OnInit — this method is called when the business operation starts. It typically initializes any structures needed by the OnMessage method. The production is passed in as an argument to OnInit.

  • OnMessage — this method is called when the business operation receives a message. It is responsible for sending the message to the external service.

  • OnTearDown — this method is called when the business operation ends. It typically releases any structures created by the OnInit method.

The production is provided as an argument to the BusinessService.and BusinessOperation OnInit method. It allows you to access settings on the Business Service and to set its status. The class com.intersystems.gateway.bh.Production has the following methods:

  • SendRequest — Sends a request message to the target configuration item of the Business Service. This method is only available to the BusinessService. It is not available in the BusinessOperation.

  • GetSetting — Gets the value for the specified Business Service or Business Operation setting.

  • SetStatus — Sets the status of the Business Service or Business Operation configuration item and changes the color of the item on the Production Configuration page.

  • LogMessage — Writes a message to the production log. You can use this to report errors or to help debug code.

For the reference documentation for these classes, see Javadocs Reference for Java Business Hosts Classes.

Generating and Configuring the Java Business Hosts

This section describes how to generate Java Business Hosts from jar files that contain one or more classes that implement com.intersystems.gateway.bh.BusinessService or com.intersystems.gateway.bh.BusinessOperation. To generate these hosts:

  1. Add the Java Business Hosts initiator to a new or existing production.

  2. If necessary, configure the settings on the initiator.

  3. Use the Java Business Hosts Management Portal page to select a jar file.

  4. Fill in the fields on the page.

  5. Generate the host.

Once you have generated the hosts, you can add them to the production containing the initiator using the Production Configuration page, specify the settings for each host, and enable the hosts to run your production.

If when you select the jar file on the Java Business Hosts page you get the The selected file does not contain any classes which can be imported as a java business host. Try selecting a different jar file. error, the problem may be one of the following:

  • Mismatch between the class name and the structure of the files in the jar archive. For example, if the class name is JavaHosts.JHBusinessService, but the jar file archive is organized so that the .class files are in the directory Output\JavaHosts\JHBusinessService, the extra level causes the initiator to not recognize the Java Business Hosts file.

  • Missing jar files that are referenced by the Business Host jar file. Any jar file referenced in the Business Host’s jar file must be specified in the initiator’s Class Path setting.