Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

What is a Parser?

A parser breaks data into smaller elements, according to a set of rules that describe its structure. If the syntax of a data source has been described by grammar rules, a parser can use the grammar to parse the data source; that is, to break data elements such as address into smaller elements, such as house number,street number,city, pincode etc. The output of the parser is a parse tree. The parse tree expresses the hierarchical structure of the input data.

What is a DOM Parser?

 DOM(Document Object Model) is a platform- and language-neutral interface, that provides a standard model of how   

 the objects in an XML object are put together, and a standard interface for accessing and  

 manipulating these objects and their inter-relationships.

 Why DOM parser?

  • converts XML into a tree of objects
  • We can access any node within tree randomly
  • Can insert/delete nodes within XML document
  • implements W3C standards for accessing XML

How will a simple xml structure be converted into a tree?

lets take a example XML structure as shown below





                           <img src=“image.bmp”>




             <p> DOM Parser</p>



The corrosponding tree will be as shown below 


 I would also like to state that DOM is an object model that specifies interfaces and not a data structure. The diagram is showing parent / child relationship are logical relatioships defined by programming interfaces and not representation of any particular internal data structures.

What is the role of DocumentBuilderFactory within java mapping program?

JAXP (Java API for XML Processing) is a Java interface that provides a standard approach to Parsing XML documents. With JAXP, we will use the DocumentBuilderFactory to create DocumentBuilder class. The class DocumentBuilderFactory is responsible for creating new DOM parsers.

Why java mapping at all?

To solve critical mapping problems. We cannot solve all complicated mapping problems with graphical mapping alone.

What is the structure of a java mapping program within SAP XI?

This is the general structure of a java mapping program that is accepted by SAP XI. We need to follow this structure in any java mapping program.

stage:java mapping program structure  

Now here is a sample problem for java mapping

We have a source XML message like this one below

<?xml version="1.0" encoding="UTF-8"?>

<ns0:mt_emp xmlns:ns0="urn:javamappingf2f">



















The source XML contains names of employees firstname, lastname and the country they belong to. In target message we require only the full names of those employees who are from the country "India". So the target structure becomes

<?xml version="1.0" encoding="UTF-8"?>

<ns0:mt_emp xmlns:ns0="urn:javamappingf2f">


<fullname>www zzz</fullname>

<fullname>RRR KKK</fullname>



 The full names are obtained by concatenation of first name and last name of employees from India separated by a space. This can be achieved by graphical mapping too, but for sake of simplicity, I chose this case for java mapping. This would be easily understood by beginners.

Steps for java mapping

1.Install j2sdk 1.4.2 for PI 7.0

2. Install JRE 1.4 or higher. I used JRE 1.6

3. Install eclipse latest version.

4. Create a java project within eclipse as you can see below.

5. As shown in above diagram we need to configure the compilation environment. The steps are                                                                                                                                                         
a. Right click on project name and choose build path then configure build path

 b. Now choose Add external jar file option. This option helps us to add aii_map_api.jar file required for java mapping. (We can get this file in some file folder within sap xi server itself.)

c. Now click OK and save the settings.

6. Now we need to write the code as provided in the link below.

 stage:link to java mapping program

Explanation of the program

In the program first I have searched for all nodes with the node name "name". I have put them in a list of nodes from left to right order. Then within a for loop I am traversing the children of each of the nodes in the node list one by one. Once I find a node with name "country" then I am checking whether its children is the text node with value "India" or not. In case I find the node has the value "India" I access the values of first child node of the two previous siblings of the node "country". The two previous siblings (as you can see from the diagram of the DOM tree below) are the nodes firstname and lastname. I concatenate the values of the child nodes of the previous two siblings and create a new node called fullname and append the new node as rightmost child of the node "employee". I repeat the above steps unless I have checked all nodes with name "name". In my example of the source XML I have appended only two nodes with name "fullname" since only two employees are from "India". Now I am again traversing the children of node employee from right to left. I am removing all nodes with name "name". Finally I am creating the target XML structure from source XML structure.  I have mentioned utility of each step in the code also.   

I would also like to explain utility of two functions

a.   public void execute(InputStream in, OutputStream out)  throws StreamTransformationException
This method contains an for the source XML  and for the target XML as parameters. The target XML must be written in the passed out.
 b.    public void setParameter(Map arg0)

A java.util.Map is passed values of the message header like sender service, sender namespace etc.  When the specific message arrives, the Integration Engine will create an object of the Mapping class followed by call to the setParameter() method to pass the header values. Then it calls the execute method to implement the actual mapping logic. To this method it passes the actual inbound message as the parameter. Within the execute method, we need to use statements to manipulate the given xml message and to build the target message. The main function is utilized only for testing in eclipse.  Within this program the parser creates a DOM tree as shown below. This is according to source XML message shown above in this post.


In the above figure there are total 22 nodes. I have shown only the nodes in left sub tree. Within the program I have traversed the nodes first from left to right while insertion of new nodes fullname. Again later I traversed the nodes from right to left to remove the unnecessary nodes.
7. Here are the steps to deploy this java mapping program within SAP XI 7.0 .
        a. Right click on source file name within eclipse.
        b. Choose export as jar file.
        c. Next screen choose option as shown below

        d. Click finish.
8. Now within integration repository (IR) import the jar file within imported archive as shown below. Here both java source program and class file will be imported. Save and activate the imported archive.

Give the imported archive a name (such as IA_DOMPARSER). After import the imported archive should look as shown below

9. Within IR create source message structure as shown below

And the target message as shown below

Now we need  a mapping as shown below. Ensure that the class file is imported within the mapping properly.


1. When you try to test the java mapping you might get an error mesage saying "linkage error". When you go through the trace you may find the message "java.lang.NoClassDefFoundError: Illegal name". This happens because the java version in which you are running the mapping program, is higher than supported by SAP XI. Please check out the java version used in XI . You need to reset the compilation enviornment as shown in step 5 of my article with the java version of SAP-XI.

2. If your source message occupies huge memory then it is better to use SAX parser instead of DOM. The DOM parser stores the entire source XML structure in main memory thus the server requires huge memory to run the program.


This article explains the process of java mapping in a very simple manner. I went through many blogs about java mapping but I found for a newcomer those blogs are not quite adequate since not all steps has been explained in detail. So here I tried to provide all steps required for java mapping.   



Company: Wipro Technologies     
Created on:    23.11.2010
Author(s) Bio
Name: Anupam Ghosh

Educational qualification: MTECH in IT

Present role: SAP XI consultant



Related Content

Java mapping simplified.

comment from from Wiki page author -
Incase you are having problems with version of eclipse install the following softwares java2sdkse v 1.4.2_15, java2 runtime enviornment V 1.4.2_15 and eclipse SDK 3.4.2-win32. This setting is perfect for PI 7.0. One more mapping progam you can consult is available in this following link . If you want to know in details about node functions please refer to the following link

1 Comment

  1. Dear Readers and forum members,

      I would like to add one point about installation here. Incase you are having problems with version of eclipse install the following softwares java2sdkse v 1.4.2_15, java2 runtime enviornment V 1.4.2_15 and eclipse SDK 3.4.2-win32.  This setting is perfect for PI 7.0. One more mapping progam you can consult is available in this following link . If you want to know in details about node functions please refer to the following link  .  If you need access to aii_map_api.jar then please look for it in folder /usr/sap/<SID>/DVEBMGS<nr>/j2ee/cluster/server0/apps/ in PI 7.0 server.

    The article shows example to do java mapping for PI 7.0 . In case you want to know how to do a java mapping for higher versions please refer to this thread

    The external jar files required for java mapping in PI7.1 or higher is different one it is known as . Please kindly refer to this link for where to find required jar files to compile a  java mapping code  in your local system.

    Check out this one too