Oracle® Fusion Middleware User's Guide for Oracle B2B 11g Release 1 (11.1.1.5.0) E10229-06 |
|
![]() Previous |
![]() Next |
This chapter describes how to create and use Java callouts, which transform the formats of messages exchanged between the host and remote trading partners. 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 trading partner application does not use the same message format as the remote trading partner. For example, a remote trading partner sends a RosettaNet XML-formatted purchase order request to a host trading partner, as shown in Figure 13-1.
Figure 13-1 A Purchase Order Example: Using Callouts for Differently Formatted XML Messages
In this example, the host application of the host trading partner is an Oracle E-Business Suite application that does not use RosettaNet 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 RosettaNet XML-formatted purchase order request into an Oracle E-Business Suite XML format understood by the Oracle E-Business Suite application. The Oracle E-Business Suite application, in turn, responds to the request message with a purchase order acceptance message in Oracle E-Business Suite XML format.
The other callout, callout_outbound
, for example, transforms the Oracle E-Business Suite XML format back into a RosettaNet XML-formatted message for the remote trading partner.
These two callouts are then associated with the two agreements created for this exchange, as follows:
Include callout_outbound
in the agreement for the outbound message, that is, the agreement for the initiating purchase order request.
Include callout_inbound
in the agreement for the inbound message, that is, the agreement for the responding purchase order acceptance.
Because a document definition is a component of an agreement, a callout is associated with a specific document definition.
This purchase order example depicts a simple association of one callout to one agreement. In reality, however, the same callout can be included in many different agreements by changing the value of one or more callout parameters. See Figure 13-3 for where you add parameters and see Table 13-2 for a list of parameter attributes.
Another type of callout is the transport callout, which is associated with a channel. For the inbound message, B2B invokes the transport callout immediately after it receives a message from the transport. For the outbound message, B2B invokes the transport callout immediately before it sends a message to the transport. Transport callouts can be selected in the channel configuration, as shown in Figure 13-2, and can be used with any protocol.
You can use transport callouts to extract custom headers for inbound and outbound messages using the MLLP protocol. Example 13-1 shows how to set and get the CUSTOM_HEADER
property in the callout.
Example 13-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 Section 5.5.1.4, "Using a Transport Callout to Extract Custom Headers," for more information.
Transport callouts are created like other callouts, from the Callout tab, as described in Section 13.2, "Creating a Callout." Although a transport callout is not added to an agreement, all transport callouts appear in the Callouts list on the Agreement tab; 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 Callouts list on the Agreement tab.
If the callout JAR file provided with Oracle B2B is not sufficient for your needs, you can create your own callout JAR file outside of Oracle B2B, following the standards described in the Oracle Fusion Middleware B2B Callout Java API Reference. Use the Configuration tab of the Administration link to specify the directory location of this external JAR file. It is recommended that you create an external JAR file for your callouts; do not bundle your callouts with b2b.jar.
Note: MySampleCallout is a restricted keyword and should not be used. It is already packaged into b2b.jar. |
To create a callout, provide callout details—the implementation class name and library name—and callout parameters, as shown in Figure 13-3.
You can create multiple callouts with the same name if you assign them different implementation names. You cannot delete a callout that is included in an agreement.
Table 13-1 lists the callout details that you provide.
Table 13-1 Callout Details
Field | Description |
---|---|
Enter the class file name without Note: Oracle B2B includes a predefined class file named XSLTCalloutImpl that you can use for XML-to-XML transformations. |
|
Enter the JAR file name that has the callout implementation classes. Note: If you specify one or more of your own callout JAR files, you must specify the directory location. Use the Configuration tab from the Administration link. The directory location for the default The callout library must be manually migrated from one environment to another. The B2B export/import feature does not migrate the callout library JAR. See Section 16.1, "Setting Configuration Parameters," for information on specifying the callout directory for your own callout JAR files. ![]() Description of the illustration bb_calloutdir1.gif |
|
Description |
Enter a description. |
Timeout (seconds) |
Enter the time limit in which to process the callout. |
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 agreements that use that callout.
Table 13-2 lists the optional callout parameter attributes.
Table 13-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 agreement. See Section 13.3, "Including a Callout in an Agreement," for more information. If you change a callout after it is deployed with an agreement, a server restart is required.
To create a callout:
Click Administration, and then Callout.
In the Callout section, click Add.
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 13-1.
(Optional) Click Add in the Parameters section.
Enter a parameter name and attributes, as described in Table 13-2.
Click Save.
You can edit the details, parameters, or parameter values at any time, but not the callout name.
After you create a callout, it is available to include in an agreement, as shown in Figure 13-4.
Figure 13-4 Specifying a Callout in an Agreement
To include a callout in an agreement:
Click Partners.
Click an agreement name.
Select a callout.
Click Save.
To update the value of a callout parameter for a specific agreement:
Click Partners.
Click an agreement name.
Select a callout.
Click Callout Details.
Enter a value for the parameter name, as shown in Figure 13-5.
Click OK.
Example 13-2 shows how an incoming XML document is transformed to another XML document. The directory structure is oracle.tip
.
callout.
In this example, note that setting the output CalloutMessage in the output list is required (output.add(cmOut)
).
Example 13-3 shows how to create a synchronous callback callout for use with Transport Synch Callback. See Section 5.5.3, "Using Transport Sync Callback" for more information.
Example 13-2 Code Example of an XML-to-XML Transformation
import java.io.*; import java.net.*; import java.util.*; import oracle.xml.parser.v2.*; import oracle.tip.b2b.callout.Callout; import oracle.tip.b2b.callout.CalloutMessage; import oracle.tip.b2b.callout.CalloutContext; import oracle.tip.b2b.callout.exception.*; /** * This sample callout transforms the incoming XML document * to another XML document. It also shows how to generate * Functional Ack and Error message. */ public class XSLTCalloutImpl implements Callout { public void execute(CalloutContext context, List input, List output) throws CalloutDomainException, CalloutSystemException { try { // (1) Retrieve the callout properties from CalloutContext String xsltFile = context.getStringProperty("xsltFile"); // (2) Get the input callout message CalloutMessage cmIn = (CalloutMessage)input.get(0); // (3) Process the message // instantiate a stylesheet URL xslURL = new URL("file://" + xsltFile); XSLProcessor processor = new XSLProcessor(); XSLStylesheet xsl = processor.newXSLStylesheet(xslURL); // parser input XML content DOMParser parser = new DOMParser(); parser.setPreserveWhitespace(true); parser.parse(new StringReader(cmIn.getBodyAsString())); XMLDocument xml = parser.getDocument(); processor.showWarnings(true); processor.setErrorStream(System.err); // Transform the document StringWriter strWriter = new StringWriter(); processor.processXSL(xsl, xml, new PrintWriter(strWriter)); // (4) Create a output callout message // create a callout output message CalloutMessage cmOut = new CalloutMessage(strWriter.getBuffer().toString()); strWriter.close(); // create Functional Ack callout message // this is an optional step CalloutMessage fa = new CalloutMessage(/*set FA payload here*/); fa.setParameter("functional_ack", "true"); //setting your own doctype and revision //set the doc type name and revision as defined in b2b ui fa.setParameter("doctype_name", "fa"); fa.setParameter("doctype_revision", "1.0"); // create Error callout message // this is an optional step CalloutMessage err = new CalloutMessage(/* set the payload that causes this error */); err.setParameter("error_message", "true"); err.setParameter("error_desc", "set the error desc"); output.add(cmOut); output.add(fa); output.add(err); //(5) Throw an exception, if any } catch (Exception e) { throw new CalloutDomainException(e); } } }
Example 13-3 Code Example of a Sync Callback Callout
import java.io.FileInputStream; import java.util.List; import java.util.Properties; import oracle.tip.b2b.callout.Callout; import oracle.tip.b2b.callout.CalloutContext; import oracle.tip.b2b.callout.CalloutMessage; import oracle.tip.b2b.callout.exception.CalloutDomainException; import oracle.tip.b2b.callout.exception.CalloutSystemException; import oracle.tip.b2b.domain.B2BParameters; import oracle.tip.b2b.system.B2BRuntimeException; import oracle.tip.b2b.system.ErrorKeys; public class SyncSampleCallout implements Callout { public void execute(CalloutContext calloutContext, List input, List output) throws CalloutDomainException, CalloutSystemException { try { CalloutMessage message = new CalloutMessage(); Properties properties = new Properties(); properties.put("FROM_PARTY", "MarketInc"); properties.put(B2BParameters.TO_PARTY, "OracleServices"); properties.put(B2BParameters.DOCTYPE_NAME, "271"); properties.put(B2BParameters.DOCTYPE_REVISION, "4010X092A1"); message.setParameters(properties); FileInputStream inStream = new FileInputStream("/tmp/271.dat"); byte[] content = new byte[inStream.available()]; inStream.read(content); inStream.close(); message.setBody(content); output.add(message); } catch(Exception e) { new B2BRuntimeException(ErrorKeys.B2B_RUNTIME_ERROR, e); } } }