how to create modules for the jee adapter engine · ho sap netweaver w-to guide . how to... create...

SAP NetWeaver How-To Guide

How To... Create Modules for the JEE Adapter Engine

Applicable Releases:

SAP NetWeaver Process Integration 7.1

Topic Area: SOA Middleware

Capability: Service Bus

Version 1.1

June 2008

Copyright 2008 SAP AG. All rights reserved.

No part of this publication may be reproduced or

transmitted in any form or for any purpose without the

express permission of SAP AG. The information contained

herein may be changed without prior notice.

Some software products marketed by SAP AG and its

distributors contain proprietary software components of

other software vendors.

Microsoft, Windows, Outlook, and PowerPoint are

registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel

Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390,

OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP,

Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix,

i5/OS, POWER, POWER5, OpenPower and PowerPC are

trademarks or registered trademarks of IBM Corporation.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader

are either trademarks or registered trademarks of Adobe

Systems Incorporated in the United States and/or other

countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered

trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame,

WinFrame, VideoFrame, and MultiWin are trademarks or

registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or

registered trademarks of W3C, World Wide Web

Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems,

Inc., used under license for technology invented and

implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP

NetWeaver, and other SAP products and services

mentioned herein as well as their respective logos are

trademarks or registered trademarks of SAP AG in

Germany and in several other countries all over the world.

All other product and service names mentioned are the

trademarks of their respective companies. Data contained

in this document serves informational purposes only.

National product specifications may vary.

These materials are subject to change without notice.

These materials are provided by SAP AG and its affiliated

companies ("SAP Group") for informational purposes only,

without representation or warranty of any kind, and SAP

Group shall not be liable for errors or omissions with

respect to the materials. The only warranties for SAP

Group products and services are those that are set forth in

the express warranty statements accompanying such

products and services, if any. Nothing herein should be

construed as constituting an additional warranty.

These materials are provided as is without a warranty of

any kind, either express or implied, including but not

limited to, the implied warranties of merchantability,

fitness for a particular purpose, or non-infringement.

SAP shall not be liable for damages of any kind including

without limitation direct, special, indirect, or consequential

damages that may result from the use of these materials.

SAP does not warrant the accuracy or completeness of the

information, text, graphics, links or other items contained

within these materials. SAP has no control over the

information that you may access through the use of hot

links contained in these materials and does not endorse

your use of third party web pages nor provide any warranty

whatsoever relating to third party web pages.

SAP NetWeaver How-to Guides are intended to simplify

the product implementation. While specific product

features and procedures typically are explained in a

practical business context, it is not implied that those

features and procedures are the only approach in solving a

specific business problem using SAP NetWeaver. Should

you wish to receive additional information, clarification or

support, please refer to SAP Consulting.

Any software coding and/or code lines / strings (Code)

included in this documentation are only examples and are

not intended to be used in a productive system

environment. The Code is only intended better explain and

visualize the syntax and phrasing rules of certain coding.

SAP does not warrant the correctness and completeness of

the Code given herein, and SAP shall not be liable for

errors or damages caused by the usage of the Code, except

if such damages were caused by SAP intentionally or

grossly negligent.

Disclaimer

Some components of this product are based on Java. Any

code change in these components may cause unpredictable

and severe malfunctions and is therefore expressively

prohibited, as is any decompilation of these components.

Any Java Source Code delivered with this product is only

to be used by SAPs Support Services and may not be

modified or altered in any way.

Document History Document Version Description

1.10 Update for PI 7.1

1.00 First official release of this guide

Typographic Conventions Type Style Description

Example Text Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options.

Cross-references to other documentation

Example text Emphasized words or phrases in body text, graphic titles, and table titles

Example text File and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools.

Example text User entry texts. These are words or characters that you enter in the system exactly as they appear in the documentation.

Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system.

EXAMPLE TEXT Keys on the keyboard, for example, F2 or ENTER.

Icons Icon Description

Caution

Note or Important

Example

Recommendation or Tip

Table of Contents

1. Business Scenario............................................................................................................... 1

2. Background Information..................................................................................................... 1

3. Prerequisites ........................................................................................................................ 2

4. Step-by-Step Procedure...................................................................................................... 3 4.1 Obtain the library (or jar) files necessary for development........................................... 3 4.2 Include the jar files in the library classpath of SAP Netweaver Developer Studio ....... 3 4.3 Create EJB and EAR projects for the User-Module ..................................................... 5 4.4 Create an Enterprise Bean in the EJB project.............................................................. 9 4.5 Examine and verify the content of ejb-jar.xml ............................................................ 12 4.6 Enter the JNDI name in the ejb-j2ee-engine.xml........................................................ 13 4.7 Include external libraries in the EJB project so the java class can be compiled ........ 13 4.8 Enter the code for GetHostNameBean....................................................................... 16 4.9 Delete the package containing the Local and Remote interfaces from the build ....... 17 4.10 Configure the EAR project.......................................................................................... 18 4.11 Setting target server for deployment .......................................................................... 22 4.12 Deploy the EAR file .................................................................................................... 24

5. Test Landscape.................................................................................................................. 27

6. Appendix ............................................................................................................................ 32


1. Business Scenario There are occasions when the features of the default adapters cannot handle the specific needs of data formatting and handling from/to source or target systems. An example is the decryption of data before it is sent to SAP NetWeaver Process Integration for processing.

When those special data handlings are required, the adapters can be enhanced using the user-module (or, user exits). This session walks through the process of developing and testing adapter user modules.

2. Background Information A message from the Integration Server is received in the Adapter Framework by the messaging service. Based on the receiver information, the corresponding module chain is selected for further processing. The Adapter Framework contains two default module chains: one for the sender/inbound direction and one for the receiver/outbound direction. You can use these default module chains for the adapter if the entire message processing is executed within the adapter. You can enhance the default module chains with customer-specific modules. The module processor controls the steps in the module chain by calling generic and, if defined, adapter-specific modules. The last module in the module chain forwards the message to the adapter. The adapter transfers the message to the connected system.

Message processing in the sender/inbound direction proceeds in a similar way. The adapter calls the module processor in the form of an EJB 2.1 local session bean and transfers the message object either as a PI message, or in its own format. If the message object is transferred in its own format, it must be converted to a PI message in an adapter-specific module.

In this exercise, we will use a user-module to retrieve the hostname where the adapter is running. The hostname will be appended as the last XML element of the message. The element name containing the hostname value, by default, is HostName. This element name can be configured by using the module parameter HostElementName.

June 2008 1


3. Prerequisites The prerequisites are as follows:

Software

NWDS 7.1 SP3 is minimum

J2EE engine running on jre 1.5.0_06

PCK 7.0

Hardware

At least 2GB of RAM

For more information about the Adapter module development in PI 7.1, see SAP Help Portal at help.sap.com SAP NetWeaver SAP NetWeaver 7.1. In the documentation, choose SAP NetWeaver Process Integration Library IT Scenarios at a Glance Enabling Application-to-Application Processes. Scroll down to section Further Informationdevelopment, and enter the SAP NetWeaver Developer's Guide under Enabling Application-to-Application Processes. Go to Tasks Designing A2A Processes. Here you find links pointing to Configuring the A2A Processes-> Developing Adapter Modules section. This gives information about adapter module development.

June 2008 2


4. Step-by-Step Procedure

4.1 Obtain the library (or jar) files necessary for development

...

In order to develop the user-module locally on the NW Developer Studio on your laptop, some PI libraries will be required. These libraries must be included in the java classpath during development.

The libraries, or jar files, have to be taken from an existing SAP PI/PCK 7.1 installation. Find the library files in following folders:

com.sap.aii.af.lib.mod.jar: /ext/com.sap.aii.af.lib/lib

sap.com~tc~logging~java~impl.jar: /system

com.sap.aii.af.svc_api.jar: /services/com.sap.aii.af.svc/lib

com.sap.aii.af.cpa.svc_api.jar: /services/com.sap.aii.af.cpa.svc/lib

com.sap.aii.af.ms.ifc_api.jar: /interfaces/com.sap.aii.af.ms.ifc/lib

= /usr/sap//J01/j2ee/cluster/bin on a SAP PCK 7.1 installation.

Create a temporary folder as C:/temp/AdapterJars adding all the jars above.

4.2 Include the jar files in the library classpath of SAP Netweaver Developer Studio

Open up NW Developer Studio and follow the following steps

Navigate to Windows Preference.

In the Preference window (as shown below), expand Java, and select Classpath Variables.

Click New to create a new variable entry: PI_AF_LIBS.

And, assign the directory containing the jar files we extracted: C:/temp/AdapterJars.

Note In Java, / is used for directory path.

Click OK, to exit the Preferences window.

June 2008 3


June 2008 4


4.3 Create EJB and EAR projects for the User-Module

...

In SAP NetWeaver Developer Studio, follow the steps below:

1. Create a new project by using the menu: File New Project

Select EJB EJB Project.

Click "Next".

CAUTION The user module still uses EJB 2.x, therefore we must not select EJB 3.0.

June 2008 5


2. Assign project names to the EJB and EAR projects.

EJB Project Name: UserModule_EJB.

EAR Project Name: UserModule_EAR (check the option to add EAR project).

Click "Next".

June 2008 6


3. Choose the correct EJB version.

Configure Module Project as SAP EJB J2EE 1.4 Project.

Choose the EJB Module 2.1.

Click "Next".

June 2008 7


4. Uncheck the flag to create the EJB client jar interfaces.

Click "Finish".

Note Please note, 2 projects will be created, an EJB project (UserModule_EJB) and an EAR project (UserModule_EAR).

June 2008 8


4.4 Create an Enterprise Bean in the EJB project ...

1. Right-click on the UserModule_EJB.

2. Select: New EnterpriseBean.

June 2008 9


3. Create the package and class for the EJB project

EJB Name: GetHostName.

Bean Type: Select the dropdown Stateless Session Bean.

Give a default EJBPackage: com.sap.adaptermodule.

Uncheck option: generate default interfaces.

Check option: add optional interfaces.

Click "Next".

June 2008 10


4. Assign user-module interfaces. Use the following values to assign to the parameters in the screen below:

Remote interface: com.sap.aii.af.lib.mp.module.ModuleRemote

Home interface: com.sap.aii.af.lib.mp.module.ModuleHome

Local interface: com.sap.aii.af.lib.mp.module.ModuleLocal

LocalHome interface: com.sap.aii.af.lib.mp.module.ModuleLocalHome

Uncheck option: Service End point

Click Finish

June 2008 11


4.5 Examine and verify the content of ejb-jar.xml ...

1. On the left panel, navigate: EJB project ejbModule META-INF.

2. Double click on the "ejb-jar.xml".

3. When the ejb-jar.xml is displayed on the right panel, select the "Enterprise Beans" tab at the bottom.

4. Expand "Session Beans" and select "GetHostName".

5. All the local and remote interfaces should be displayed. The Service endpoint should be empty.

June 2008 12


4.6 Enter the JNDI name in the ejb-j2ee-engine.xml ...

1. On the left panel, double click on the "ejb-j2ee-engine.xml".

2. "Ejb-j2ee-engine.xml" will be displayed on the right panel.

3. Expand Session beans and click on GetHostName.

4. Enter the JNDI Name: GetHostName.

5. Save the file.

4.7 Include external libraries in the EJB project so the java class can be compiled

...

1. Right click on the EJB project.

2. Navigate to "Build Path".

June 2008 13


3. Select "Configure Build Path".

4. In the Properties dialogue box, click the "Add Variable".

June 2008 14


5. Select the variable, "PI_AF_LIBS", created earlier.

6. Click on "Extend".

7. Select all the files and click on Ok.

June 2008 15


8. On the Properties screen click Ok.

4.8 Enter the code for GetHostNameBean ...

1. Double click on the "GetHostNameBean".

The Java program will be displayed on the right hand panel.

June 2008 16


2. Copy-n-paste the Java source program GetHostNameBean.java from Appendix on the source code panel.

3. Save the file.

4.9 Delete the package containing the Local and Remote interfaces from the build

When we created the Enterprise Beans, we entered the Local and Remote interfaces. These interfaces already exist in the adapter framework, therefore, we must exclude the ones created by NWDS from the build. ...

1. Expand the build folder in the EJB project.

2. Delete all the folders created under build classes com sap.

Important Do not delete the folder which has the build class of the bean you created. Rest of all other folders under com sap path should be deleted.

June 2008 17


Note If you do not see the com/sap/ folder, this means that the project has not been built. You can build the project by right-click on the EJP project, e.g. "UserModule_EJB", and select Build. The Project Build Automatically on the top menu will need to be turned off in order to see the Build in "UserModule_EJB".

4.10 Configure the EAR project The EAR file contains the following:

JAR file created from the EJB project.

It has configuration information of the libraries, services and interfaces that will be used by the user-module in the EJB.

It contains the SAP manifest file, which has unique identifiers for each specific EAR. The manifest information is generated uniquely each time it is modified.

...

June 2008 18


1. Expand the EAR project.

2. Double-click on the "application-j2ee-engine.xml" file.

3. In the right panel, click on the Reference and then on the + sign to "Add Elements".

4. Click "Create New" in the dialog.

June 2008 19


5. Enter the following information in the screen:

Reference target: engine.security.facade

Reference type: hard

Reference target type: service

Provider name: sap.com

6. Repeat the steps (click on the Reference and +) for all the following:

Reference Target Reference Type Reference Target Type Provider Name

engine.j2ee14.facade hard library sap.com

com.sap.aii.af.svc.facade hard service sap.com

com.sap.aii.af.ifc.facade hard interface sap.com

com.sap.aii.af.lib.facade hard library sap.com

com.sap.base.technology.facade hard library sap.com

Upon completion, the screen should appear like this:

June 2008 20


7. Check the option "Failover Mode".

8. Save the file.

Note Now we are ready to deploy the file.

June 2008 21


4.11 Setting target server for deployment ...

1. Navigate to Windows Preference.

2. In the Preference Window, select SAP AS Java.

3. Enter the J2EE server information.

Enter the J2EE server instance host and instance number.

Register the SAP instance.

Note Any local or remote host can be added in this manner.

Note This server will get registered and appear in the list of SAP System Instances.

June 2008 22


4. Click "Ok".

June 2008 23


4.12 Deploy the EAR file ...

1. Right click on the EAR file.

2. Select Run As Run on Server.

June 2008 24


3. Click Next.

4. In the next screen ensure that the EAR project appears in the right panel under "Configured Projects".

5. Click "Next".

June 2008 25


6. Choose the "Web Browser".

7. Click "Finish".

8. When prompted, enter the username and password for the J2EE engine. This will initiate the deployment of the EAR file on the J2EE engine.

June 2008 26


5. Test Landscape In the following a landscape is set up to test the user module.

In order to use PCK for testing adapters without a PI server, a loop configuration is required. This will allow PCK to be both sender and receiver of messages.

StepbyStep procedure for loopback configuration ...

1. Start the PCK

Use the URL: http://host:port/pck/start/index.jsp

Click on PCK. Logon using user-id and password configured for pck.

Note This user must have all the required roles required for configuration and monitoring. In example, user used is PCKUSER.

Note Well configure a file to file scenario and include the user module in the sender channel.

2. Create a service in PCK.

a. Right click on business component and click Next.

June 2008 27

http://host:port/pck/start/index.jsp


b. Click on Business Component and enter the communication component name, here HostNameService.

...

3. Create the Sender Communication Channel, here FileSenderChannel.

Set the values at different tabs in sender channel.

a. Parameters - Source tab:

June 2008 28


b. Parameters - Processing tab:

c. Module tab Include the custom module created earlier (GetHostName):

4. Create the Receiver Communication Channel, here FileReceiverChannel.

June 2008 29


Set the values for different tabs in receiver channel.

a. Parameters - Target tab:

b. Parameters Processing tab:

June 2008 30


5. Create the Sender Agreement and Receiver Agreement.

Note Sender Interface name and Namespace name can be anything you want. But, the names must match between the Sender and Receiver Agreements.

June 2008 31


6. Appendix

Appendix A - Code Sample used in the example package com.sap.adaptermodule;

// Classes for EJB

import javax.ejb.CreateException;

import javax.ejb.SessionBean;

import javax.ejb.SessionContext;

// Classes for Module development & Trace

import com.sap.aii.af.lib.mp.module.*;

import com.sap.engine.interfaces.messaging.api.*;

import com.sap.engine.interfaces.messaging.api.auditlog.*;

import com.sap.tc.logging.*;

// XML parsing and transformation classes

import javax.xml.parsers.*;

import org.w3c.dom.*;

import java.io.InputStream;

import java.io.ByteArrayOutputStream;

import java.net.InetAddress;

import java.net.UnknownHostException;

import javax.xml.transform.*;

import javax.xml.transform.Source;

import javax.xml.transform.Result;

import javax.xml.transform.dom.DOMSource;

import javax.xml.transform.stream.StreamResult;

public class GetHostnameXXBean implements SessionBean, Module {

public static final String VERSION_ID = "$Id://tc/aii/30_REL/src/_adapters/_sample/java/user/module/GetHostName.java#1 $";

static final long serialVersionUID = 7435850550539048631L;

private SessionContext myContext;

public void ejbRemove() {}

public void ejbActivate() {}

public void ejbPassivate() {}

public void setSessionContext(SessionContext context) {

myContext = context; }

June 2008 32


public void ejbCreate() throws CreateException {}

public ModuleData process(ModuleContext moduleContext, ModuleData inputModuleData) throws ModuleException {

String SIGNATURE = "process(ModuleContext moduleContext, ModuleData inputModuleData)";

Location location = null;

AuditAccess audit = null;

// Create the location always new to avoid serialization/transient of location

try {

location = Location.getLocation(this.getClass().getName());

}catch (Exception t) {

t.printStackTrace();

ModuleException me = new ModuleException("Unable to create trace location", t);

throw me;

}

Object obj = null;

Message msg = null;

String hostName = getHostName();

MessageKey key = null;

try {

obj = inputModuleData.getPrincipalData();

msg = (Message) obj;

key = new MessageKey(msg.getMessageId(), msg.getMessageDirection());

audit = PublicAPIAccessFactory.getPublicAPIAccess().getAuditAccess();

audit.addAuditLogEntry(key, AuditLogStatus.SUCCESS, "GetHostName: Module called");

}

catch (Exception e) {

ModuleException me = new ModuleException(e);

throw me;

}

// Read the channel ID, channel and the module configuration

String hostElementName = null;

try {

// CS_GETMODDAT START

June 2008 33


hostElementName = (String) moduleContext.getContextData("HostElementName");

// CS_GETMODDAT END

if (hostElementName == null) {

location.debugT(SIGNATURE, "HostElementName parameter is not set. Default used: HostName.");

audit.addAuditLogEntry(key, AuditLogStatus.WARNING, "HostElementName parameter is not set. Default used: HostName.");

hostElementName = "HostName";

}

location.debugT(SIGNATURE, "HostElementName is set to {0}", new Object[] {hostElementName});

audit.addAuditLogEntry(key, AuditLogStatus.SUCCESS, "HostElementName is set to {0}", new Object[] {hostElementName});

} catch (Exception e) {

location.catching(SIGNATURE, e);

location.errorT(SIGNATURE, "Cannot read the module context and configuration data");

audit.addAuditLogEntry(key, AuditLogStatus.ERROR, "Cannot read the module context and configuration data");


location.throwing(SIGNATURE, me);

throw me;

}

try {

XMLPayload xmlpayload = msg.getDocument();

DocumentBuilderFactory factory;

factory = DocumentBuilderFactory.newInstance();

DocumentBuilder builder = factory.newDocumentBuilder();

Document document = builder.parse((InputStream)

xmlpayload.getInputStream());

Element rootNode = document.getDocumentElement();

if(rootNode != null) {

Element childElement =

document.createElement(hostElementName);

childElement.appendChild(document.createTextNode(hostName));

rootNode.appendChild(childElement);

}

June 2008 34


// Transforming the DOM object to Stream object.

TransformerFactory tfactory = TransformerFactory.newInstance();

Transformer transformer = tfactory.newTransformer();

Source src = new DOMSource(document);

ByteArrayOutputStream myBytes = new

ByteArrayOutputStream();

Result dest = new StreamResult(myBytes);

transformer.transform(src,dest);

byte[] docContent = myBytes.toByteArray();

if(docContent != null) {

xmlpayload.setContent(docContent);

inputModuleData.setPrincipalData(msg);

}

}

catch (Exception e) {


throw me;

}

return inputModuleData;

}

private static String getHostName() {

String host = "unknown";

try {

InetAddress inet = InetAddress.getLocalHost();

host = inet.getHostName().toLowerCase();

int i = host.indexOf(".");

if (i > 0) {

host = host.substring(0, i);

}

}

catch (UnknownHostException e) {

host = "error";

}

return host;

}

}

June 2008 35


Appendix B PCK configuration

Loopback configuration In order to use PCK for testing adapters without a PI server, a loop configuration is required. This will allow PCK to be both sender and receiver of messages.

Below are snapshots of NWA for PCK 7.1 setup. These will be similar to Visual Administrator. Since no Visual Administrator will be available with PI 7.1, hence the settings are required in NWA.

June 2008 36

www.sdn.sap.com/irj/sdn/howtoguides

1. Business Scenario2. Background Information3. Prerequisites4. Step-by-Step Procedure4.1 Obtain the library (or jar) files necessary for development4.2 Include the jar files in the library classpath of SAP Netweaver Developer Studio4.3 Create EJB and EAR projects for the User-Module4.4 Create an Enterprise Bean in the EJB project4.5 Examine and verify the content of ejb-jar.xml4.6 Enter the JNDI name in the ejb-j2ee-engine.xml4.7 Include external libraries in the EJB project so the java class can be compiled4.8 Enter the code for GetHostNameBean4.9 Delete the package containing the Local and Remote interfaces from the build4.10 Configure the EAR project4.11 Setting target server for deployment4.12 Deploy the EAR file

5. Test Landscape6. AppendixAppendix A - Code Sample used in the exampleAppendix B PCK configuration

how to create modules for the jee adapter engine · ho sap netweaver w-to guide . how to... create...

Documents