This chapter describes how to create and use Java callouts in Oracle SOA Suite for healthcare integration. Java callouts transform the formats of messages exchanged between the host and remote endpoints. You can use callouts to invoke an XSLT style sheet and any Java program in general.
This chapter contains the following topics:
Callouts are used in environments in which a host endpoint does not use the same message format as the remote trading partner. In addition, callouts are used to customize header information in messages.
If the callout JAR file provided with Oracle SOA Suite for healthcare integration is not sufficient for your needs, you can create your own callout JAR file outside of Oracle SOA Suite for healthcare integration, following the standards described in the Oracle Fusion Middleware B2B Callout Java API Reference. You can specify the directory location of this external JAR file in the Callout Directory field that you can access from the Runtime link under Settings in the Administration tab of the Oracle SOA Suite for healthcare integration user interface as shown in Figure 5-1. It is recommended that you create an external JAR file for your callouts; do not bundle your callouts with b2b.jar
.
Figure 5-1 Specifying the Callout Directory
Note:
MySampleCallout is a restricted keyword and should not be used. It is already packaged into b2b.jar
.
Oracle SOA Suite for healthcare integration provides two types of callouts:
A transport callout is associated with an endpoint. For the inbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately after it receives a message from the remote endpoint. For the outbound message, Oracle SOA Suite for healthcare integration invokes the transport callout immediately before it sends a message to the remote endpoint. Transport callouts can be selected in the endpoint configuration, as shown in Figure 5-2, and can be used with any supported protocol such as generic TCP and MLLP 1.0.
You can use transport callouts to extract transport custom headers for inbound messages and set transport headers for outbound messages. Example 5-1 shows how to set and get the CUSTOM_HEADER
property in the callout.
Example 5-1 Setting and Getting the CUSTOM_HEADER Property
import java.util.*;
import oracle.tip.b2b.callout.*;
import oracle.tip.b2b.callout.exception.*;
public class SampleCallout implements Callout {
public void execute(CalloutContext context,List input,List output)
throws CalloutDomainException, CalloutSystemException {
try {
CalloutMessage cmIn = (CalloutMessage)input.get(0);
String s =cmIn.getBodyAsString();
//for getting the CUSTOM_HEADER
Properties params = (Properties)cmIn.getParameters();
String customHeader = (String)params.get("CUSTOM_HEADER");
//for setting the CUSTOM_HEADER
CalloutMessage cmOut = new CalloutMessage(s);
cmOut.setParameter("CUSTOM_HEADER", "your_value");
output.add(cmOut);
} catch (Exception e) {
throw new CalloutDomainException(e);
}
}
}
See "Using a Transport Callout to Extract Custom Headers" in Oracle Fusion Middleware User's Guide for Oracle B2B for more information.
Transport callouts are created from the Configuration tab under Designer, as described in Section 5.3, "Creating a Callout." All transport callouts appear both in the Transport Callout list and in the Document Callout list in an endpoint page; therefore, it is available for selection. To avoid confusion, when you create a transport callout, provide a name that indicates its type so that you do not select it from the Document Callout list.
Document callouts are used to enable communication between endpoints that do not use the same message format. For example, a remote endpoint sends a HL7 2.3.1 XML-formatted message to a host endpoint. The host endpoint uses HL7 2.5 XML-formatted messages.
To enable communication between these two different formats, you create two callouts, as follows:
One callout, callout_inbound
, for example, transforms the remote message into a format understood by the host endpoint. The host endpoint, in turn, responds to the request message with a order acceptance message in HL7 2.5 XML format.
The other callout, callout_outbound
, for example, transforms the HL7 2.5 XML format back into an HL7 2.3.1 XML-formatted message for the remote endpoint.
These two callouts are then associated with the two endpoints, as follows:
Associate callout_outbound
in the endpoint for the outbound message, which is, the endpoint for the initiating message request.
Associate callout_inbound
in the endpoint for the inbound message, which is, the endpoint for the responding message acceptance.
Because a document definition is a component of an endpoint, a callout is associated with a specific document definition.
This example depicts a simple association of one callout to one endpoint. In reality, however, the same callout can be included in many different endpoints by changing the value of one or more callout parameters. See Figure 5-4 for where you add parameters and see Table 5-2 for a list of parameter attributes.
To create a callout, provide callout details—the library name and the implementation class name—and callout parameters, as shown in Figure 5-4.
Note:
To create a callout from an external callout library JAR file, see Section 5.1.1, "Creating a Callout Library JAR File."
Log on to the Oracle SOA Suite for healthcare integration user interface.
Click the Designer tab, Configuration, and then Callout.
Click the Create icon (the plus sign) to display the Create Callout dialog box.
Enter a name for the callout.
(You may want to indicate if you are creating a transport callout in the name.)
Enter callout details, as described in Table 5-1.
Click OK.
Table 5-1 lists the callout details that you provide.
Note:
You cannot delete a callout that is included in an endpoint.
After creating the callout, you can configure it by specifying the timeout value and optional parameters as shown in Figure 5-4.
Callout parameters are similar in concept to global variables to which you can assign local values that are applicable only to a specific callout use. Or, you can create a callout parameter and assign it a default value that is applicable to all callout uses. Changes to callout parameters for an existing callout affect all endpoints that use that callout.
Table 5-2 lists the optional callout parameter attributes.
Table 5-2 Callout Parameter Attributes
Field | Description |
---|---|
Name |
Enter a parameter name. |
Type |
Select from Integer, Float, String, Boolean, or Date types. The format for the Date type is MM/DD/YYYY. Note: Changing a type can invalidate the parameter default value. |
Value |
Enter a value. If Encrypted is set to True, then this value is encrypted. |
Mandatory |
Select True or False. |
Encrypted |
Select True or False. |
Description |
Enter an optional description. |
After you create a callout, it is available to include in an endpoint. See Section 5.4, "Including a Callout in an Endpoint," for more information. If you change a callout after it is deployed with an endpoint, a server restart is required.
After you create a callout, it is available to include in an endpoint.
To include a callout in an endpoint:
From the Configuration tab, double-click an endpoint to open it.
Depending on the type of message (inbound or outbound), select the callout name from the Document Callout list under the Send or Receive section. as shown in Figure 5-5.
Figure 5-5 Associating a Callout with an Endpoint
Click Apply.