XI/PI: Java Mapping Demystified

When I decided to learn Java mapping, I searched SDN for blogs on Java mapping and found lot of blogs. Some of them were too technical and some of them given only coding and nothing else. As a developer, who did not have Java background, I found it very difficult to follow those blogs. So, I decided to come up with this blog post for beginners, which will give a basic understanding of how to write a Java mapping program.What is parsing?The literal meaning of parsing is “taking apart” or “breaking down” something into smaller segments. Technically when we say parsing of an XML document, we are breaking the XML file into individual elements and reading the data contained in the elements (body of the individual elements)Why do we need parsing in Java mapping:A typical Java mapping program takes the incoming XML message and transfers the data into target XML message structure. To do this the Java program first needs to read what is there in the incoming XML message. This is done by parsing or breaking down the XML document into individual elements.Java provides two ways of parsing the XML document

1. SAX ( Simple API for XML )2. DOM ( Document Object Model)

The subject of this blog is SAX so I am going to concentrate more on SAX parser.Few things you should know about the SAX parser:SAX parser is nothing but simple API for XML. In crude words set of classes used for reading the XML documentThe five methods shown below are used when parsing the XML documentsstartDocumentCalled when the Parser starts parsing the Current XML File.public void startDocument () throws SAXException {

...

...

}

endDocumentCalled when the Parser Completes parsing the Current XML File.public void endDocument () throws SAXException {

...

...

}

startElementCalled when the starting of the Element is reached. For Example if we have tag called <Title>...</Title>, then this method is called when <Title> tag is Encountered while

parsing the Current XML File. TheAttributeList Parameter has the list of all Attributes declared for the Current Element in the XML File.public void startElement (String name, AttributeList attrs) throws

SAXException {

...

...

}

endElementCalled when the Ending of the current Element is reached. For example in the above explanation, this method is called when </Title> tag is reachedpublic void endElement (String name) throws SAXException {

...

...

}

charactersWhile Parsing the XML file, if extra characters like space or enter characters are encountered then this method is called. If you don’t want to do anything special with these characters, then you can normally leave this method blank. So this method can be used to read the values or body of the elements.public void characters (char buf [], int offset, int len)

throws SAXException {

...

...

}

Lets take a simple example and understand how these methods work. The incoming message has below format<?xml version="1.0"?>

<doc>

<para>Hello, world!</para>

</doc>

An event-based interface will break the structure of this document down into a series of linear events, such as these:

When the java program takes this message as input, as soon as system reads the first line (i.e., <?xml version="1.0"?> the startDocument() method is called then system reads next element <doc>, now thestartElement() method is triggered, next the method is called again for <para> element. Now as the element <para> contains some body, characters method is called. After that system reads </para>, which is end of the element <para>. At this point system calls endElement() method. Again system callsendElement(), but this time for </doc> element. Finally endDocument() method is called when there are no elements left to read.start document

start element: doc

start element: para

characters: Hello, world!

end element: para

end element: doc

end document

The SAX parser is also called event driven parser because it invokes the methods ( startDocument(),startElement() etc., ) as it reads the XML document.

What you should know and do before creating java mapping programs:1. First download the recent JDK ( java development kit) from web2. With in jdk folder you have bin folder, which contains all the java executable files.3. In environment variables add the path c:program filesjavajdk1.4bin4. For CLASSPATH add c:program filesjavajdk1.4lib5. Most importantly you need to know some core java concepts ( let me tell you this is not difficult.

If I can do, you can as well do it)(The path might be different when you install the JDK in your PC. The path I have mentioned is what I have used.)After doing this download the aii.map.api.jar file and place it in bin folder. Add the path c:program filesjavajdk1.6binaii.map.api.jar to the CLASSPATH environment variable.The jar file aii.map.api.jar resides in the XI server. Ask you basis guy to provide you this jar file. The path for the jar file in Xi server is j2eeclusterserver0appssap.comcom.sap.xi.servicesThe first thing we need for creating any mapping program is to create two message interfaces. So let’s start and create the data types , message types and message interfaces. I am not going to explain here in detail how to create them as it is very simple and straightforward. Any user working in XI or got trained should be in a position to do that.The data type DT_OB_SAX_MAP contains two elements NUMBER1 and NUMBER2. The data type DI_IB_SAX_MAP has three elements ADD,MUL and SUB. The aim here is to take the two numbers and add , multiply and subtract them and pass the results to the respective elements in target message.Message type MT_OB_SAX_MAP

Message type MT_IB_SAX_MAP

Message type MI_OB_SAX_MAP

Message interface MI_IB_SAX_MAP

Before creating the interface mapping, we need to create the Java mapping program.We will first examine the source and target XML message structure.<?xml version="1.0" encoding="UTF-8"?>

<ns0:MT_OB_SAX_MAP xmlns:ns0="http://learningxi.com">

<NUMBER1>1</NUMBER1>

<NUMBER2>1</NUMBER2>

</ns0:MT_OB_SAX_MAP>

The message has three elements MT_OB_SAX_MAP, NUMBER1 and NUMBER2.<?xml version="1.0" encoding="UTF-8"?>

<ns0:MT_IB_SAX_MAP xmlns:ns0="http://learningxi.com">

<ADD>2</ADD>

<MUL>1</MUL>

<SUB>0</SUB>

</ns0:MT_IB_SAX_MAP>

As you see from the above XML structure, we have total four elements MT_IB_SAX_MAP, ADD, MUL and SUB. ADD element body is nothing but NUMBER1 + NUMBER2 MUL element body is NUMBER1 * NUMBER2 SUB element body is NUMBER1 – NUMBER2

Understand the java Mapping program:package jmapsax;

import java.io.FileInputStream;

import java.io.FileOutputStream;

import com.sap.aii.mapping.api.StreamTransformation;

import java.io.*;

import java.util.Map;

import javax.xml.parsers.*;

import org.xml.sax.*;

import org.xml.sax.helpers.*;

/*IMPORT statement imports the specified classes and its methods into the

program */

/*Every Java mapping program must implement the interface StreamTransformation

and its methods execute() and setParameter() and extend the class

DefaultHandler.*/

public class saxmapfinal1 extends DefaultHandler implements

StreamTransformation{

/*Below is the declaration for all the variables we are going to use in the

subsequent methods. */

private Map map;

private OutputStream out;

private boolean input1 = false;

private boolean input2 = false;

private int number1;

private int number2;

private int addvalue;

private int mulvalue;

private int subvalue;

String lineEnd = System.getProperty("line.separator");

/*setParamater() method is used to store the mapping object in the variable

"map" */

public void setParameter (Map param) {

map = param;

}public void execute (InputStream in, OutputStream out)

throws com.sap.aii.mapping.api.StreamTransformationException {

DefaultHandler handler = this;

SAXParserFactory factory = SAXParserFactory.newInstance();

try {

SAXParser saxParser = factory.newSAXParser();

this.out = out;

saxParser.parse(in, handler);

}

catch (Throwable t){

t.printStackTrace();

}

}/*As seen above execute() method has two parameters "in" of type InputStream

and "out" of type OutputStream. First we get a new instance of

SAXParserFactory and from this one we create a new Instance of SAXParser. To

the Parse Method of SaxParser, we pass two parameters, inputstream "in" and

the class variable "handler".*/

/*Method "write" is a user defined method, which is used to write the string

"s" to the outpurstream "out".*/

private void write (String s) throws SAXException{

try{

out.write(s.getBytes());

out.flush();

}

catch (IOException e){

throw new SAXException("I/O error", e);

}

}public void startDocument () throws SAXException{

write("");

write(lineEnd);

write("");

write(lineEnd);

}public void endDocument () throws SAXException {

write("");

try { out.flush();

}

catch (IOException e) {

throw new SAXException("I/O error", e);

}

}public void startElement (String namespaceURI, String sName,

String qName, Attributes attrs) throws SAXException {

String eName = sName;

if ("".equals(eName)) eName = qName;

if(eName.equals("NUMBER1")) input1 = true;

if(eName.equals("NUMBER2")) input2 = true;

}public void endElement (String namespaceURI, String sName, String qName)

throws SAXException {

String eName = sName;

if ("".equals(eName)) eName = qName;

if(eName.equals("NUMBER1")) input1 = false;

if(eName.equals("NUMBER2")) input2 = false;

}public void characters(char[] chars,int startIndex, int endIndex) throws

SAXException {

String dataString =

new String(chars, startIndex, endIndex).trim();

if (input1) {

try {

number1 = Integer.parseInt(dataString);

} catch(NumberFormatException nfe){

}

}

if (input2) {

number2 = Integer.parseInt(dataString);

}

if (input2 == true){

addvalue = number1 + number2;

mulvalue = number1 * number2;

subvalue = number1 - number2;

write("" + addvalue +"");

write(lineEnd);

write("" + mulvalue +"");

write(lineEnd);

write("" + subvalue +"");

write(lineEnd);

}

}}When the parsing of XML message starts, first startDocument() method is triggered as soon as program encounters the line <?xml version="1.0" encoding="UTF-8"?>. so we will call write() method by passing the <?xml version="1.0" encoding="UTF-8"?> to argument “s”. The write() method writes this string to the OutputStream. Similarly we will also pass the

string <ns0:MT_IB_SAX_MAP xmlns:ns0="http://learningxi.com"> to write() method. In between these statementswrite(LineEnd) is used to introduce a newline.

Taking analogy from the example explained in the Sax parser section the sequence of method call is given below:startDocument()

startElement() - <MT_OB_SAX_MAP>

startElement() - < NUMBER1>

characters() - body of NUMBER1 ( i.e 1 )

endElement() - </NUMBER1>

startElement() - <NUMBER2>

characters() - body of NUMBER2 ( i.e, 1)

At this point we calculate the values for ADD, MUL and SUB elements and call the write() method to write these elements to the OutputStream out.endElement() -</NUMBER2>

endElement() - </MT_OB_SAX_MAP>

endDocument()

Now place the java file in a folder with name jmapsax ( this is package name we have specified in the java program). Compile the program and zip the java file and generated class file.Create a new imported archive and import the zip file.Imported archive ” newarchive”

Interface Mapping IM_SAX_MAP

click the test tab in the interface mapping and enter some integer values for NUMBER1 and NUMBER2. click on execute you will see the target message.Interface testing tree view

Interface testing XML view

Sankar Rao Bhatta is an SAP NetWeaver Consultant with Intel, India. After completing M.Tech from IIT Bombay, he worked with IBM as SAP Consultant before joining Intel. Other areas of his expertise include SAP SRM and ABAP.