Adapter Module Development - Presentation

8/20/2019 Adapter Module Development - Presentation

http://slidepdf.com/reader/full/adapter-module-development-presentation 1/47

XI 3.0 Adapter ModuleDevelopment

Stefan GrubeSAP NetWeaver RIG EMEA

SAP AG



Adapter Framework Overview

Module Development Overview

Logging in the Adapter Modules

Prepare Development Environment

Create Adapter Module as Enterprise Java Bean

Deploy the Adapter Module to the Adapter Engine



© SAP AG 2005, SAP Skills November 2005 Conference / D5 / Joachim Orb / 3

The SAP XI Adapter Framework

Based on SAP J2EE Engine

Uniform Handling of Deployment,

Configuration, Administration, Monitoring

and Security

Technical Basis for Adapter Engineand SAP Partner Connectivity Kit

Adapters run as services within the SAP

J2EE Engine and use the services of theAdapter Framework (e.g.

Queuing/Logging)

Usage of open standards: SOAP, JMS,

JDBC…..


http://slidepdf.com/reader/full/adapter-module-development-presentation 4/47© SAP AG 2005, SAP Skills November 2005 Conference / D5 / Joachim Orb / 4

SAP XI 3.0 Architecture

Integration Server

Plain

J2SE

Adapter

Engine

Partner Connectivity

KitOptional non-central

Adapter Engine

Central

Adapter Engine

Integration Repository / Integration Directory / System Landscape Directory

Business Process Engine

Integration Engine

Adapter Framework

Messaging

Queuing

Security Handling

R e s o ur c e

A d a p t er

R e s o ur c e

A d a p t er

R e s o ur c e

A d a p t er

Adapter FW

Messaging

Queuing

Security Handling

Adapter FW

Messaging

Queuing

Security Handling

PCK Configuration

and Monitoring

HT T P / I D o c

A d a p t er

Adapter

File/DB/JMS

Marketplace

3rd Party Sys.

File

DB

JMSSOAP

SAP &

Non-SAP

System

File/DB/JMS

Marketplace

3rd Party Sys.

File/DB/JMS

Marketplace

3rd Party Sys.

Adapter Framework

Messaging

Queuing

Security Handling

Adapter FW

Messaging

Queuing

Security Handling

Adapter FW

Messaging

Queuing

Security Handling



SAP Partner Connectivity Kit – Overview

Supports Smaller Companies / Subsidiaries to exchange XML

documents with their business partner’s / headquarters' SAP XI

SAP / 3rd

Party Appl.SAP XI

Smaller Company / Subsidiary

SAP

PCK

SAPApplication

3rd Party

Application

Large Business Partner /

Headquarters

Internet

Provides a Platform for Development of own JCA Resource Adapters

SAP

PCK



SAP XI-Adapters vs. SAP XI-Proxies

Adapters Connect existing (legacy) systems to XI

Specific wire protocol

Interface semantics externally pre-defined Outside-in development approach

Proxies

Connect new SAP applications to XI

Native connectivity to Application system (adapter-less)

Interfaces designed centrally in Integration Repository

Inside-out development approach



Use Cases for Adapter Module Development

Converting the payload (not covered with standards)

Changing encoding (escaping, de-escaping)

Encryption and decryption

Creating and merging of additional attachments







Create Adapter Module as Enterprise Java Bean

Deploy the Adapter Module to the Adapter Engine



SAP XI Adapter Framework Components Overview

XI

Integration Server

Integration Repository

Integration Directory

System LandscapeDirectory

Runtime Workbench

XI Adapter Framework on SAP J2EE Server 6.40 ConnectedSystem

JCA 1.0 Adapter

XI MessagingService

ConfigurationServices

Administrational Services

AF ModuleProcessor

Generic AFmodules

R R

R

R

R

R R

Adapter specific

modules

R

RR

Cache

R

Logging API

Log File & Audit DB

2

3

8

4

5

7

Message Definition(WSDL, xsd, dtd)

Utilities(Threads,

Transactions)

R6

R

externalprotocol

RJCA 1.0

Framework

1

Adapter (configuration) meta

data (xsd)

R4



Java Resource Adapter

SAP J2EE 6.40 is J2EE 1.3

compliant and supports JCA 1.0

JCA 1.0 was designed to unify

access to non-Java backends

JCA 1.0 does not specify inbound

calls from non-Java backends

SAP XI Adapters might need to

support inbound and outbound calls

Source: Sun JCA 1.0 specification




SAP XI AF Message API

Messaging System (MS)provides the persistence

for messages within the

Adapter Framework.

Support for qualities

of service (QoS):

BE, EO, EOIO

The Message API usesfactories from MS to

instantiate message objects.

A message consists of amain payload and an arbitrary

number of attachments.




SAP XI Adapter Standard Modules

SAP J2EE Server 6.30

XI AF

Messaging

Service

ejb 2.0 Container

3rd Party JCA 1.0 Adapter

JCA 1.0 Framework

XI AF

Entry ejb

XI AF generic

modules (ejb)

XI AF

Module

Exit ejb

Adapter specific

modules (ejb)

(optional)

XI AF Module Processor

RJCA 1.0 CCI

Connections

R R

Rejb call Rejb call

Deployed

J2EE and

XI system

libraries:

aii_af_

service_util.

jar etc.

R

Java Classes

JDBC/

Open

SQL

XI AF

Configura

tion

HTTP(S)

Servlet

(Web

Cont.)

XI AF

Utilities

AF Log FilesData Base (SAP DB, other)

Rsession ejb

call

J2EE system & add-on services

R

SAP XI Messages

(SOAP w/A)

Rsession ejb

call

RJava

classes

Rservice call

R

3rd Party

Protocol

...

R

R

RJCA 1.0 SPI

Connections

Channel

templates define a

module chain to

be processed by

the SAP XI AFModule Processor

The default chain

can be modifiedby customers

Standard modules

can be re-used to

access JCA

adapters and SAP

XI Messaging

System

Ad t M d l P




Adapter Module Processor

Receiver Direction

Asynchronous

Communication

Messaging

System

Adapter

Module

Module

2

Module

1

Module

1

Module

2

Adapter

Module

JCA 1.0

Adapter

Standard Adapter

Module

Customer specific

Adapter Modules

Sender DirectionAsynchronous

Communication

Ad t M d l Ch i




Adapter Module Chain

Custom modules

can be added todefault module

chains

Additional

configuration

parameters can

be specified eachmodule

Ad t M d l (UML di )




Adapter Module (UML diagram)

Access toAdapter Configuration

Access toMessage content

Method called by

ModuleProcessor

Adapter Module (code fragment)




Adapter Module (code fragment)

public class CreateAttachment

implements SessionBean, Module {

public ModuleData process( ModuleContext moduleContext,

ModuleData inputModuleData)throws ModuleException {

Message messageIN =(Message) inputModuleData.getPrincipalData();

XMLPayload xmlPayloadIN = messageIN.getDocument();

String parameter =

moduleContext.getContextData("parameter");

}

}







Create Adapter Module as Enterprise Java BeanDeploy the Adapter Module to the Adapter Engine

Logging




Logging

Developers and systems management experts might have different

requirements on logging mechanisms.

SAP XI AF Logging API supports methods for displaying

processing output in the SAP XI Message Display Tool

trace output in the SAP J2EE engine.

The trace output can be maintained by default in the XML

configuration file log-configuration.xml or at runtime in the J2EE

service LogConfigurator for each log controller.

Logging: Service Trace




Logging: Service Trace

SAP J2EE Engine providesa LogViewer service

Trace output is configured

in the service

LogConfigurator

Each log destination can

be separately displayed

and filtered according touser-specific needs

Logging: Service Trace (code fragment)




Logging: Service Trace (code fragment)

public class CreateAttachment implements SessionBean,

Module {

private static final Trace TRACE = new Trace("yourVersion");

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

String SIGNATURE = "YourSignature";TRACE.entering(SIGNATURE,

new Object[] { moduleContext, inputModuleData });

try{ Message messageIN =

(Message) inputModuleData.getPrincipalData();

} catch (Exception e) {TRACE.catching(SIGNATURE, e);TRACE.errorT(SIGNATURE, "Error occurred");

}

}

Logging: Audit Log




Logging: Audit Log

The SAP XI Message DisplayTool provides comprehensive

filter mechanisms to find the

relevant messages

For each message content

and audit log can be

monitored

Logging: Audit Log




Logging: Audit Log

For each message an audit log is written that shows processing details

(e.g. the executed module chain).

SAP XI AF provides standard methods within its logging framework.

Logging: Audit Log (code fragment)




Logging: Audit Log (code fragment)

public class CreateAttachment

implements SessionBean, Module {

public ModuleData process( ModuleContext moduleContext,

ModuleData inputModuleData)throws ModuleException {

Message messageIN =(Message) inputModuleData.getPrincipalData();

AuditMessageKey amk =new AuditMessageKey(msg.getMessageId(),

AuditDirection.OUTBOUND);

Audit.addAuditLogEntry(amk, AuditLogStatus.SUCCESS,"CreateAttachment: Module called");

}

}








Development Kit and Module Processor




p

Development Kit for development of additional adapters (partner and

customer solutions) based on SAP J2EE und JCA (J2EE Connector

Architecture)

SAP NetWeaver Certification of Third-Party Adapters

Modulprocessor as extension concept (corresponds to dispatcher

functionality within the XI 2.0 Adapter Engine); Default-Modules per

Adapter

Development Environment




p

Adapter development, deployment andtesting is possible on a single machine, no

full-blown SAP XI is required.

Installation of SAP PCK already contains a

sample adapter (including Adapter MetaData) and a sample module that should

serve as a starting point.

For testing purposes integration scenarioscan be configured in SAP PCK

(e.g. loopback scenario).

SAP Partner Connectivity

Kit

Adapter FW

Messaging

Queuing

Security Handling

R e s o ur c e

A d a p t er

PCK Configuration

and Monitoring

File/DB/JMS

Marketplace

3rd Party Sys.

Java Doc and code samples for Module Development




Copy the JAR file of the example adapter locally to your computer.

The JAR file contains the Java Doc and the source text of theexample adapter.

Copy the file sample_ra.jar from

<serverDir>\apps\sap.com\com.sap.aii.af.sample.ra\connector\connectors\sample_ra.rar to a separate directory on your computer.

<serverDir> is C:\usr\sap\J2E\JC00\j2ee\cluster\server0, for example.

Extract the JAR file to the same directory.

Open index.html to display the Java Doc.

The source text for the example adapter is located in a

subdirectory com\sap\aii\af\sample\adapter\ra.

Java Doc for Module Development




Available Documentation




The Adapter

Development

documentation is

available via

http://help.sap.com

http://help.sap.com/

http://help.sap.com/








Create the Adapter Module EJB




Steps in the SAP NetWeaver Developer Studio:

1. Create an EJB Module Project

2. Apply the libraries (at least aii_af_mp.jar and aii_af_ms_api.jar )

3. Create a package (in folder ejbModule)

4. Create a Java class (not an EJB). Use template on the following

pages

5. Write the code of the Java class

6. Adjust the ejb-jar.xml

7. Adjust the ejb-j2ee-engine.xml

8. Build the EJB archive (JAR)

Overview of usable libraries




For the module development you have to extract following libraries

from your PCK/AF installation:

aii_af_mp.jar – the interface Module

aii_af_ms_api.jar – dealing with payload and attachments

aii_af_trace.jar – writing trace

aii_af_svc.jar – adapter services

aii_af_cpa.jar – reading channel entries

sapxmltoolkit.jar – XML parser

2

Adapter Module EJB template (1)




package yourPackage;

import javax.ejb.CreateException;

import javax.ejb.SessionBean;

import javax.ejb.SessionContext;

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

import com.sap.aii.af.ra.ms.api.*;

/**

* @ejbHome <{com.sap.aii.af.mp.module.ModuleHome}>

* @ejbLocal <{com.sap.aii.af.mp.module.ModuleLocal}> * @ejbLocalHome <{com.sap.aii.af.mp.module.ModuleLocalHome}>

* @ejbRemote <{com.sap.aii.af.mp.module.ModuleRemote}>

* @stateless

*/

public class YourClass implements SessionBean, Module{

private SessionContext myContext;

4

Adapter Module EJB template (2)




public void ejbRemove() {

}

public void ejbActivate() {

}

public void ejbPassivate() {

}

public void setSessionContext(SessionContext context) {

myContext = context;

} public void ejbCreate() throws CreateException {

}

public ModuleData process(ModuleContext moduleContext,

ModuleData inputModuleData)

throws ModuleException {

// put your code here

return inputModuleData;

}

}

4

Code sample: adding an additional attachment




public ModuleData process(ModuleContext moduleContext,

ModuleData inputModuleData)

throws ModuleException {

try {

Message msg = (Message) inputModuleData.getPrincipalData();

TextPayload attachment = msg.createTextPayload();

attachment.setName("Attachment");

attachment.setContentType("text/plain");

attachment.setText("Hello World"); msg.addAttachment(attachment);

inputModuleData.setPrincipalData(msg);

} catch (Exception e) {

ModuleException me = new ModuleException(e);

throw me;

}

return inputModuleData;

}

5

The ejb-jar.xml




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

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD EnterpriseJavaBeans 2.0//EN“"http://java.sun.com/dtd/ejb-jar_2_0.dtd">

<ejb-jar> <description> EJB JAR description </description> <display-name> EJB JAR </display-name>

<enterprise-beans> <session>

<ejb-name> YourEJBName </ejb-name> <home> com.sap.aii.af.mp.module.ModuleHome </home> <remote> com.sap.aii.af.mp.module.ModuleRemote </remote>

<local-home> com.sap.aii.af.mp.module.ModuleLocalHome </local-home> <local> com.sap.aii.af.mp.module.ModuleLocal </local> <ejb-class> yourPackage.YourClass </ejb-class> <session-type> Stateless </session-type> <transaction-type> Container </transaction-type>

</session> </enterprise-beans>

</ejb-jar>

6

The ejb-j2ee-engine.xml




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

<!DOCTYPE ejb-j2ee-engine SYSTEM "ejb-j2ee-engine.dtd"><ejb-j2ee-engine>

<enterprise-beans>

<enterprise-bean>

<ejb-name> YourEJBName</ejb-name><jndi-name> YourJNDIName</jndi-name>

<session-props/>

</enterprise-bean>

</enterprise-beans>

</ejb-j2ee-engine>

7



Deploying SAP XI Adapter Components




SAP recommends to

use SAP SoftwareDeployment Manager

(SDM) for deployment

Software Delivery

Archives (SDA) can

contain software

components of different

types (e.g. applications,

libraries)

Detailed version

information and

dependencies to othercomponents simplify

program management

Files in the SDA/EAR




Besides the JAR file with the Adapter Module classes and the ebj

descriptors, there are following files with path META-INF:

MANIFEST.MF

Contains the version numbers and the provider names.

SAP_MANIFEST.MF

Contains version numbers, content, and component names,

similar to a catalog. The SDM uses this information to manage the

deployment information in its database.

application.xml

Contains display names and references to icons if the adapter is

displayed with SAP J2EE tools.

application-j2ee-engine.xml

Contains references required during SDM deployment.

Create the Enterprise Application Archive




Steps in the SAP NetWeaver Developer Studio:

1. Create an Enterprise Application Project

2. Add the EJB module

3. Adjust the application-j2ee-engine.xml like follows

4. Build the Application archive (EAR)

5. Deploy the EAR file to the PCK/AE

It is not possible to create an SDA file for EJB direct out of

the SAP NetWeaver Developer Studio. But you can deploy

the EAR files with SDM as well

The Application-j2ee-engine.xml




In this file you have to create following references:

Reference target Reference

type

Reference

target-type

Provider name

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

com.sap.aii.adapter.xi.svc hard service sap.com

com.sap.aii.af.svc Hard service sap.com

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

3

Deploy the EAR File Using SDM




Check Deployment Using Visual Admin Tool (1)




Check, if the EJB is

deployed and active

Checking Deployment Using Visual Admin Tool (2)




In the EBJ

Container you can

see and change the

JNDI name

Questions?




Q



Documents

Adapter Module Development - Presentation