how to create modules for the jee adapter engine

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 HistoryDocument Version 1.10 1.00 Description Update for PI 7.1 First official release of this guide

Typographic ConventionsType Style Example Text Description 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 File and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. 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. Keys on the keyboard, for example, F2 or ENTER.

IconsIcon Description Caution Note or Important Example Recommendation or Tip

Example text

Example text

EXAMPLE TEXT

Table of Contents1. 2. 3. 4. Business Scenario............................................................................................................... 1 Background Information..................................................................................................... 1 Prerequisites ........................................................................................................................ 2 Step-by-Step Procedure...................................................................................................... 3 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 Obtain the library (or jar) files necessary for development........................................... 3 Include the jar files in the library classpath of SAP Netweaver Developer Studio ....... 3 Create EJB and EAR projects for the User-Module ..................................................... 5 Create an Enterprise Bean in the EJB project.............................................................. 9 Examine and verify the content of ejb-jar.xml ............................................................ 12 Enter the JNDI name in the ejb-j2ee-engine.xml........................................................ 13 Include external libraries in the EJB project so the java class can be compiled ........ 13 Enter the code for GetHostNameBean....................................................................... 16 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. 6. Test Landscape.................................................................................................................. 27 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 usermodule (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.

PrerequisitesSoftware NWDS 7.1 SP3 is minimum J2EE engine running on jre 1.5.0_06 PCK 7.0

The prerequisites are as follows:

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-toApplication 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.4.1...

Step-by-Step ProcedureObtain 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: com.sap.aii.af.cpa.svc_api.jar: com.sap.aii.af.ms.ifc_api.jar: /services/com.sap.aii.af.svc/lib /services/com.sap.aii.af.cpa.svc/lib /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 StudioNavigate 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.

Open up NW Developer Studio and follow the following steps

Click OK, to exit the Preferences window.

June 2008

3


June 2008

4


4.3...

Create EJB and EAR projects for the UserModule

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 projectThe 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 engine.j2ee14.facade com.sap.aii.af.svc.facade com.sap.aii.af.ifc.facade com.sap.aii.af.lib.facade com.sap.base.technology.facade

Reference Type hard hard hard hard hard

Reference Target Type library service interface library library

Provider Name sap.com sap.com sap.com sap.com 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


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 examplepackage 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.jav a#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"); ModuleException me = new ModuleException(e); 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) {

ModuleException me = new ModuleException(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 configurationIn 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

how to create modules for the jee adapter engine

Documents

nw developer

party web

jee adapter

default module

adapter module

adapter framework

module chain

business component