SAP XI XSLT/Java

Use

You can also implement XSLT and Java mappings yourself and save them as archives in the Integration Repository. This enables you to reuse mapping programs that already exist. Mapping programs from imported archives are executed on the J2EE Engine of the Integration Server.

You can also import archives in the PCK. PCK users can replace the terms Integration Repository, Integration Directory, and Integration Builder with PCK in the descriptions below.

Prerequisites

You have already implemented an XSLT or Java mapping and packed it in a Jar or Zip file. The file name (including path) of the archive must not be longer than 180 characters.

In the case of Java archives, it is very important that the archive contains the compiled classes (*class). Java source files are ignored by the Integration Builder and the mapping runtime.

Features

For details about the options that you have in XSLT and Java, see the XSLT Mapping and Java Mapping sections. It is also possible to call other mapping programs from a mapping program (see: References Between Mapping Programs).

Displaying and Changing Imported Mapping Programs in the Integration Builder

Function	Use
Display Program (corresponds to double-clicking the XSLT program)	Displays the selected XSLT program
Change Program	Changes the selected XSLT program. In an Integration Builder editor you can either change lines or import another XSLT program. You must edit Java mappings externally and then import them again.
Open in Client Browser	Displays the selected program in the client browser. To display the selected mapping file, start the Integration Builder from the default browser on the PC for class- or xsl-files.

When displaying imported mapping programs, the viewer shows the code used to display the characters of a file:

· In the case of XML files (XML, XSD, XSL), the Integration Builder can determine the code exactly, as it is specified in the header of the XML document.

· For all other files the Integration Builder uses a default code: Latin-1 (ISO-8859-1) for files with the suffix .properties and UTF-8 for all others. To change the code, use the list box in the header area of the viewer. The options are the standard codes of Java and Windows operating systems (XP or NT "Cp1252"). You can also enter other codes supported by the operating system.

Activities

Importing XSLT and Java Archives

...

1. Create a mapping object of type Imported Archive on the design maintenance screen of the Integration Builder (see also: Creating an Object in the Integration Directory or Creating an Object in the PCK).

2. To import the archive, choose Import Archive. Once you have activated the archive other users can export it again.

3. Save the archive.

Result

You have saved the mapping programs in the Integration Repository. To be able to select these mapping programs for a scenario at configuration time, you must assign them to an interface pair by using an interface mapping.

Interface mapping is not possible in the PCK.

XSLT Mapping

Use

Interface descriptions are in the form of XML documents. XSL Transformation (XSLT) is a member of the XML family of languages. It describes how an XML structure is transformed into another XML structure.

Features

XPath and

You can define mappings using XSLT together with XPath. XPath is also a specification of the XML family. Using XPath you can address any node in an XML document. XSLT implements XPath expressions to select substructures of an XML document. Using templates in XSLT you can define the mapping rules for the selected substructures.

You can use the XSLT tags and to include predefined templates for substructures in a complete mapping definition. In this way, you can reuse mappings for data types.

Runtime Constants

In the same way as in Java mappings, the mapping runtime in XSLT programs also returns parameters that you can use to evaluate information in the XSLT program that is not known until runtime:

Mapping Runtime Constants

Constant	Meaning	Relevant for PCK
$MessageClass	Classification of message. Possible values: · ApplicationMessage: Asynchronous or synchronous request message · ApplicationResponse: Response to request message · SystemAck, ApplicationAck, SystemError, ApplicationError: Acknowledgment messages	Yes
$VersionMajor	XI message protocol version. Example: For the XI 3.0 message protocol VERSION_MAJOR = 3 and VERSION_MINOR = 0.	No The PCK only uses message protocol XI 3.0.
$VersionMinor		No
$ProcessingMode	The mode of a message can be synchronous or asynchronous. Correspondingly, these constants can have the value synchronous or asynchronous.	Yes
$MessageId	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
$RefToMessageId	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
$ConversationId	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
$TimeSent	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	Name of the sender interface. As of SAP XI 3.0, use this constant instead of the constant SENDER_NAME used previously.	Yes
$InterfaceNamespace	Namespace of the sender interface. As of SAP XI 3.0, use this constant instead of the constant SENDER_NAMESPACE used previously.	Yes
$SenderParty	Communication party that sent the message.	Yes See also: Communication party
$SenderPartyAgency	Issuing agency for the message sender.	Yes
$SenderPartyScheme	Identification scheme used by the sender.	Yes
$SenderService	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
$ReceiverName	Name of the receiver interface.	Yes
$ReceiverNamespace	Namespace of the receiver interface.	Yes
$ReceiverParty	Communication party to receive the message.	Yes See also: Communication party
$ReceiverPartyAgency	Issuing agency for the message receiver.	Yes
$ReceiverPartyScheme	Identification scheme used by the receiver.	Yes
$ReceiverService	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
$MappingTrace	Returns a MappingTrace object that you can use to write messages in the monitoring.	No

If you want to access one of the constants in the XSLT program, you first have to declare the constant as a parameter, for example:

Java Enhancements

Moreover, using an XSLT definition you can call external Java methods to convert XML structures. This procedure gives you more flexibility when defining mappings. For more information about XSLT mapping with Java enhancement, see further documentation.

For more information about XSL/XSLT and XPath, see the Web page of the W3 Consortium.

Example

The function for booking a flight contains a parameter for the flight class. The outbound interface represents flight classes as symbolic values; in the inbound interface, flight classes have numerical values. The XSLT section converts the symbolic representation of the source system into the numerical representation of the target system.

The XPath expression match=“//hh:class“ selects the node in the outbound interface. The XSLT statement <xsl:choose> then defines the mapping rule for how the Integration Engine converts the symbolic values in the source system into the numerical values in the target system.

SAP XSLT Mapping with Java Enhancement

Use

The XSLT specification proposes an enhancement mechanism that enables the system to call external routines from XSLT for transforming XML structures. Java is a programming language that is supported by some Java XSLT processors as an enhancement language.

Using the XSLT mapping with Java enhancement, you can implement mappings quicker and more flexibly.

The working draft of the specification for XSL Transformations (XSLT) version 2.0 (version from December 20, 2001), does not define the features of the enhancement mechanism of the XSL transformation. There are also no accompanying standards that standardize the enhancement mechanism with Java. For this reason, XSLT processors available on the open market vary considerably in this respect.

Below is a description of one of the ways that the SAP J2EE Engine supports the XML Toolkit 2.0.

Activities

To implement an XSLT mapping with Java enhancement, proceed as follows:

...

1. Implement a Java class that contains the static methods of transforming XML documents or structures. Within this Java class you can also write messages to a trace that is visible in the message monitoring using the MappingTrace object.

The PCK does not support the MappingTrace object.

2. Include the method calls in the XSLT mapping program (see below).

3. Import the XSLT mapping program and the Java class as an archive to the Integration Repository. You can also use two different archives. The archive with the Java class must be in the same or an underlying software component version of the XSLT mapping program (see also: XSLT and Java Mapping).

The following example illustrates the procedure using a simple XSLT mapping for a message.

Example

The following table shows the message instance that you want to transfer to the target message, using an XSLT mapping program with Java enhancement.

Source Instance	Target Instance
Robert White	Robert White

You must link the and <last-name> elements using a concat() Java method. You also want to write a message to the mapping trace in this method. Carry out the following steps in the XSLT mapping program in which you want to call this Java method:

...

1. Declare the Java class with a namespace definition as an attribute of the element. The namespace name can be any string you want; in the example it is called javamap (see below). The name of the namespace comprises the string java: as the prefix, and the complete name of the class. The complete name of a Java class comprises the name of the package and the class name. In the example this is com.company.group.MappingClass.

2. Use to define the parameters that you want to transfer in the method calls. In the example below, three parameters of the concat() method signature are defined correspondingly:

○ The first parameter takes the value of the element.

○ The last parameter takes the value of the element.

○ The parameter name inputparam is defined and enables you to transfer the constants of the StreamTransformationConstants class to the Java program.

In a Java mapping you have to implement the setParameter() method to enable the Integration Server to set the constants at runtime. For XSLT mappings with a Java enhancement it is sufficient to transfer the constants using the inputparam parameter. The mapping runtime sets the parameter. (see also: Java Mapping).

3. The method is called with the element . Specify the method with the corresponding parameters using the attribute select. The name for the namespace javamapreplaces the complete class name as a prefix.

SAP advises you to check the availability of methods before you call them. Test the XSL element using the attribute test, for example.

The XSLT program looks like this:

xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:javamap="java:com.company.group.MappingClass">

The concat() class method of the Java class com.company.group.MappingClass groups the values of the and elements of the source instance together in a string that represents the value of the element of the target instance. The method also has the inputparam parameter of the Map type for writing information to the trace. You use this to first fetch a MappingTrace object and then use its methods addInfo()or AddWarning() to transfer messages to the trace:

package com.company.group;

import java.util.Map;
import com.sap.aii.mapping.api.AbstractTrace;
import com.sap.aii.mapping.api.StreamTransformationConstants;

public class MappingClass {

private static AbstractTrace trace = null;

public static String concat(String first,
String last,
Map inputparam)
{
// write trace information
trace = (AbstractTrace)inputparam.get(
StreamTransformationConstants.MAPPING_TRACE );

trace.addInfo(“concat():
\nfirst-name = “ + first +
“\nlast-name = “ + last );

// return concatentation

return first + ' ' + last;
}

//...

}

SAP XSLT Mapping of Adapter-Specific Message Attributes

The message header of an XI message contains a header for adapter-specific message attributes that the sender adapter can use to write additional information to the message header. This enables sender adapters to write information that is not known until runtime to the message (see: Adapter-Specific Attributes in the Message Header).

To change the fields of this header in a mapping program, you usually use a Java mapping program (see also: Java Mapping of Adapter-Specific Attributes). Nevertheless, you can also use the relevant classes as a Java enhancement in an XSLT program.

In this example, the Java classes for a mapping of the message header for adapter-specific message attributes are used in an XSLT program to change the parameter Directory of the file adapter. The XSLT program is structured thus:

...

1. First, the required Java classes are declared as namespaces:

○ java.util.map to be able to access the constants of the mapping runtime. The header for the adapter-specific message attributes is saved as a Map with the name DynamicConfiguration.

○ com.sap.aii.mapping.api.DynamicConfiguration and com.sap.aii.mapping.api.DynamicConfigurationKey for the header mapping.

2. The parameter name inputparam is defined and enables you to transfer the constants of the StreamTransformationConstants class to the Java runtime.

3. To change the header for the dynamic configuration, the XSLT program gets the Map for the header, creates a key for the parameter Directory in the file adapter, gets the current value for this parameter by using the method get(), links this directory path with the XSLT method concat and replaces the value by using the method put().

XSLT Mapping Program with Java Enhancement

xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:map="java:java.util.Map"
xmlns:dyn="java:com.sap.aii.mapping.api.DynamicConfiguration"
xmlns:key="java:com.sap.aii.mapping.api.DynamicConfigurationKey">









select="map:get($inputparam, 'DynamicConfiguration')" />

select="key:create('http://sap.com/xi/XI/System/File', 'Directory')" />

select="dyn:get($dynamic-conf, $dynamic-key)" />

select="concat($dynamic-value, 'subfolder\')" />

select="dyn:put($dynamic-conf, $dynamic-key, $new-value)" />

Error Handling in XSLT

Use

In substantial XSLT programs it makes sense for the system to display an explanatory message when an error occurs. For this purpose there is the XSLT command . For example, the source document might contain a value that is not expected by the mapping program. In this case the system can display a message, and, if necessary, terminate processing of the mapping.

Alternatively, you can also call a Java method from your XSLT program, which writes information to the trace using the MappingTrace Object. For an example, see the XSLT mapping with Java enhancement section.

The PCK does not support the MappingTrace object.

Integration

Messages that are produced using the XSLT command or the MappingTrace object are visible in the trace function of the technical monitor (also see: Monitoring XML Messages).

Features

The XLST command has the following syntax:

<xsl:message terminate=“[yes|no]“>

The attribute Terminate determines whether processing of the XSLT program should be terminated (terminate=“yes”) or not (terminate=“no”). In both instances you can view the error message text by using the trace function for a message in monitoring (provided that you activated the trace function for the Integration Engine).

Example

The following example of a section of an XSLT program is taken from a mapping program with the name Person2Passenger.xsl. The XSLT commands in this section evaluate the current value of a tag from the source document and map the values as follows:

Source Document	Target Document
0	Mr.
1	Mrs.
(Other)	Mr. or Mrs.

The last instance is an exception for non-interpretable values. To retain this exception in the trace, a message is produced using :

Mr.
Mrs.

Mr. or Mrs.

Gender has neither value 0 nor 1!
"Mr. or Mrs." was chosen for title.

Since the target field can still be completed appropriately, processing is not terminated (terminate=“no“).

Trace Output

In the technical monitor, the section in the trace for the third instance looks as follows:

ENTER" func="CL_XMS_PLSRV_MAPPING~ENTER_PLSRV" />

XSLT transformation: xslt/wsxx/Person2Passenger completed. Gender has neither value 0 nor 1! "Mr. or Mrs." was chosen for title.

EXIT" func="CL_XMS_PLSRV_MAPPING~ENTER_PLSRV" />

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.