Java Mapping

Purpose

You can implement mapping programs in Java. To process XML documents, use Java API for XML Processing (JAXP), for example. The JAXP supports the Document Object Model (DOM) and the Simple API for XML (SAX). This gives you great flexibility for mapping definitions with Java.

Implementation Considerations

Java mapping programs are not permitted to be stateful. You are therefore not permitted to perform actions such as writing data to a database table during a Java mapping. The Integration Server cannot track such side effects. Therefore, if an attempt is made to resend a message that has not been received by the receiver, the data may inadvertently be written to the database twice in a Java mapping.

If you use JRE classes in your Java mapping programs then the same program restrictions apply as for Enterprise Java Beans (EJBs). For a detailed description of these restrictions, see the relevant EJB specification. It is important that you also refer to the information under Scope of Functions in Runtime Environment (Java Mappings).

Features

The runtime environment for Java mappings has an mapping API. To use Java mapping, you must define a Java class that implements the Java interface com.sap.aii.mapping.api.StreamTransformation. This interface has two methods:

...

● public void execute(java.io.InputStream in, java.io.OutputStream out)

At runtime, the Integration Engine calls this method to execute a mapping. This method contains an input stream for the source document and an output stream for the target document as parameters. These streams are usually XML documents. You can import the substructures to be converted from the input stream and output the converted target document in the output stream.

● public void setParameter(java.util.Map param)

The Integration Engine transfers parameters to the mapping program with this method. It evaluates these parameters at runtime in the method execute(). This enables you to control the process flow of the mapping.

The transferred object that implements the Java interface java.util.Map contains seven key/value pairs as parameters. These correspond to corresponding fields in the message header. Apart from the MAPPING_TRACE constant, the value objects are of type java.lang.String. The key objects are defined in the class com.sap.aii.mapping.api.StreamTransformationConstants:

String Mapping Runtime Constants

Constant	Meaning	Relevant for PCK
MESSAGE_CLASS	Classification of message. Possible values ● ApplicationMessage: Asynchronous or synchronous request message ● ApplicationResponse: Response to a request message ● SystemAck, ApplicationAck, SystemError, ApplicationError: ● Acknowledgment Messages	Yes
VERSION_MAJOR	XI message protocol version. Example: For the XI 3.0 message protocol VERSION_MAJOR = 3 and VERSION_MINOR = 0.	No The PCK only supports message protocol XI 3.0.
VERSION_MINOR		No
PROCESSING_MODE	The mode of a message can be synchronous or asynchronous. Correspondingly, these constants can have the value synchronous or asynchronous.	Yes
MESSAGE_ID	The message ID. It can change during communication: ● Response messages get a new message ID. ● If new messages result from a message (the message is copied at multiple receivers), the new messages get new message IDs.	Yes
REF_TO_MESSAGE_ID	The ID of a referenced message that belongs semantically to this message. For example, a response message uses this field to note which request message it belongs to.	Yes
CONVERSATION_ID	This field is not mandatory in the message. It enables an ID to be used to group messages that belong together. This field is not intended to be used for message serialization and has nothing to do with the serialization context (ABAP proxy runtime, Java proxy runtime).	Yes
TIME_SENT	Time stamp specifying when the message was sent by the sender. The format of the time stamp is as follows: YYYY-MM-DDTHH:MM:SSZ The letter ‘T’ separates the date from the time, which is generally specified in UTC. If it is a local time, the closing ‘Z’ is omitted.	Yes
INTERFACE	Sender interface name. As of SAP XI 3.0, use this constant instead of the constant SENDER_NAME used previously.	Yes
INTERFACE_NAMESPACE	Sender interface namespace. As of SAP XI 3.0, use this constant instead of the constant SENDER_NAMESPACE used previously.	Yes
SENDER_PARTY	Communication party that sent the message.	Yes See also: Communication Party
SENDER_PARTY_AGENCY	Issuing agency for the message sender.	Yes
SENDER_PARTY_SCHEME	Identification scheme used by the sender.	Yes
SENDER_SERVICE	Service on the sender side that sent the message. For example, the name of a business system. As of SAP XI 3.0, use this constant instead of the constant SENDER_SYSTEM used previously.	Yes See also: Service
RECEIVER_NAME	Receiver interface name.	Yes
RECEIVER_NAMESPACE	Receiver interface namespace.	Yes
RECEIVER_PARTY	Communication party to receive the message.	Yes See also: Communication Party
RECEIVER_PARTY_AGENCY	Issuing agency for the message receiver.	Yes
RECEIVER_PARTY_SCHEME	Identification scheme used by the receiver.	Yes
RECEIVER_SERVICE	Service on the receiver side that receives the message. For example, the name of a business system. As of SAP XI 3.0, use this constant instead of the constant RECEIVER_SYSTEM used previously.	Yes See also: Service
MAPPING_TRACE	Returns a MappingTrace object that you can use to write messages in the monitoring.	No

Constraints

Note the following points when using static variables in Java mappings:

...

● Mappings can be executed in parallel. Therefore, several instances of a mapping may access a static field for read or write purposes at the same time.

● If mapping programs are executed more than once, the content of the static field may be lost. The reasons for this are as follows:

○ The content of a static field is lost if the Java class in question is reloaded. This happens after a cache refresh, for example.

○ If the mapping runtime consists of a cluster, the mapping classes on each node of the cluster are loaded separately. Each node has its own static fields.

Static fields can be used for constants and as a buffer, taking the above-mentioned points into consideration.

Example

The following example shows how the MAPPING_TRACE and RECEIVER_NAME parameters are set and evaluated in a Java mapping program:

import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;
import java.util.HashMap;
import com.sap.aii.mapping.api. AbstractTrace;
import com.sap.aii.mapping.api.StreamTransformation;
import com.sap.aii.mapping.api.StreamTransformationConstants;

public class JavaMapping implements StreamTransformation {

private Map param = null;
private AbstractTrace trace = null;

public void setParameter (Map param) {
this.param = param;
if (param == null) {
this.param = new HashMap();
}
}

public void execute(InputStream in, OutputStream out) {

try {

trace = (AbstractTrace)param.get(
StreamTransformationConstants.MAPPING_TRACE );
trace.addInfo(‘...’);

// ...

String receiverName = (String)param.get(

StreamTransformationConstants.RECEIVER_NAME);

// ...

}

}

}

See also: Special Access to Mapping Runtime Constants.