Migration Guide for Java Proxies

Applies to:
SAP enhancement package 1 for SAP NetWeaver Process Integration 7.1. For more information, visit the Service Bus-based Integration homepage

Summary
Java proxies are generated in the Integration Repository in SAP Exchange Infrastructure (XI) 3.0 and SAP NetWeaver 7.0. As of SAP NetWeaver Process Integration 7.1, enhancement package 1 (EHP 1), Java proxy generation in the Enterprise Services Repository (ES Repository) is only intended for minor adjustments to service interfaces that have been created in the ES Repository due to the automatic migration of the message interfaces of an Integration Repository (XI 3.0 or SAP NetWeaver 7.0). These service interfaces have the interface pattern stateless (XI 3.0-compatible); they have one operation and support the same programming model as in SAP XI 3.0 and SAP NetWeaver 7.0. Java proxy generation in SAP NetWeaver Developer Studio is intended to be used for new developments or for larger adaptations of service interfaces that already exist. The Java proxies created using this proxy generation introduce a new programming model. This guide provides information about how to migrate Java proxies from the old to the new environment. Author: Annemarie Kiefer, Alexander Zubev

Company: SAP AG Created on: 18 December 2009

Author Bio
Annemarie Kiefer joined SAP AG in 2008 and works as a solution manager in the SOA Middleware area focusing on Web services standards. Before this she worked freelance for SAP from 1999 in various projects and areas. Anne started working in 1988 as a consultant and later as a senior consultant and project lead in various sales force automation projects for Kiefer & Veittinger GmbH, Mannheim.

Alexander Zubev studied computer science and technology at the Technical University of Sofia, Bulgaria. While still a student, he started work at InQMy, a subsidiary of SAP AG, which subsequently became SAP Labs Bulgaria. He worked in the development of the XML Toolkit and later developed parts of the Web Services Framework in SAP NetWeaver. Today, Alexander is responsible for connectivity configuration within SOA Middleware.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 1

Migration Guide for Java Proxies

Table of Contents
Why Should You Migrate? ............................................................................................................................. 3 Java Proxies in SAP NetWeaver PI 7.1, EHP 1 ............................................................................................. 3 Prerequisites and Limitations ........................................................................................................................ 4 Implementing and Configuring a Java Proxy as a Sender .............................................................................. 4 Implementing and Configuring a Java Proxy as a Receiver............................................................................ 8 Error Handling............................................................................................................................................. 11 Supported Methods in the Web Services Environment ................................................................................ 11 Methods Currently Supported .................................................................................................................. 11 Methods Supported as of SAP NetWeaver PI 7.1, EHP 1, SPS 5 ............................................................. 12 Methods Not Currently Supported ............................................................................................................ 13 Related Content .......................................................................................................................................... 14 Copyright .................................................................................................................................................... 15

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 2

Migration Guide for Java Proxies

Why Should You Migrate?

If you want to create new applications using new features offered with Java EE5 and SAP NetWeaver Process Integration 7.1, enhancement package 1, SAP recommends that you start using the new programming model for services: Java API for XML Web Services (JAX-WS). JAX-WS replaces the JAX-RPC API in Java EE5 and, although Java EE5 still supports JAX-RPC for backwards compatibility, develop new applications to benefit from the new standard. For example, Java API for XML Web Services (JAX-WS) uses JAXB as a data mapping model that covers all XML schemas (apart from the JAX-RPC data mapping model which supports most, but not all, XML schemas). SAP provides integrated support for the XI 3.0 message protocol in SAP JAX-WS implementations. Therefore, you can benefit from the JAX-WS standard without the need to modify your existing integration scenarios. You do not need to switch to a SOAP adapter, for example, in order to benefit from JAX-WS. In addition, the new JAX-WS based proxies are integrated completely into SAP NetWeaver Developer Studio and you can use Eclipse as your standard development environment.

Java Proxies in SAP NetWeaver PI 7.1, EHP 1

Advanced Adapter Engine WS Consumer WS Provider

WS Message
XI Message

Web service runtime

WS Message
XI Message

Java Proxy Runtime

XI adapter with XI message protocol SAP NetWeaver PI as WS Provider

Integration Server

SAP NetWeaver PI as WS Consumer

Receiver System

Sender System

Based on a service interface designed in the Enterprise Services (ES) Repository with interface pattern stateless (XI 3.0-compatible), you implement your Java EE5-based Web service consumer or provider in the SAP NetWeaver Developer Studio using Eclipse as your standard development environment. Then you deploy the consumer or provider on the Advanced Adapter Engine. If the AS Java (Advanced Adapter Engine) is the consumer of a Web service at runtime, the message is processed by the Web service runtime and then transformed into an XI-message and processed by the Java Proxy Runtime (JPR) to the Integration Server. The Integration Server acts as a Web service provider and processes the message to the final receiver system. If the AS Java (Advanced Adapter Engine) is the provider of a Web service at runtime, the message is sent by a sender system to the Integration Server. The Integration Server acts as a Web service consumer, processes the message, transforms it into an XI message and forwards it to the Java Proxy Runtime. From there it is processed to the Web service runtime, transformed into a WS message, and then sent to the service provider.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 3

Migration Guide for Java Proxies

The Java Proxy Runtime is connected to the Integration Server by the XI adapter using the XI 3.0 message protocol.

Prerequisites and Limitations

Parameter isWSProxy of XPI Service: Java Proxy Runtime If you continue using JAX-RPC-based proxies with the Java Proxy Runtime (XI 3.0 message protocol) to connect to the Integration Server, set the parameter value to false (default value). If you migrate your existing JAX-RPC based proxies to JAX-WS based proxies, set the parameter value to true. You can then choose to use either the Java Proxy Runtime to connect to the Integration Server using the XI adapter (for this you must configure a logical port using the XI message protocol) or you do not use the Java Proxy Runtime and configure a logical port based on WS. You cannot run JAX-WS based and JAX-RPC based proxies using the Java Proxy Runtime on the same engine. Service interfaces with interface pattern stateless (XI 3.0 compatible) have exactly one service operation. Deploy your Java EE application on either a central or a non-central Advanced Adapter Engine. You cannot deploy the application on any other engine supporting Java EE, for example, SAP NetWeaver Composition Environment (CE). Java Proxy Runtime is not available there. If you want to use JAX-WS with SAP NetWeaver CE, connect the CE system to the Integration Server by either using the SOAP or the WS Adapter. Do not use the XI adapter. Existing integration scenarios in the Integration Directory remain unchanged. For the following description, we assume that you have already configured your integration scenarios in the Integration Directory, for example, using a receiver channel based on the XI adapter pointing to the appropriate Java Proxy Runtime. The following description is based on the delivered demo scenario FlightSeatAvailabilityCheck. More information: Checking Flight Availability

Implementing and Configuring a Java Proxy as a Sender

To implement a Java proxy as a sender, you have to create a Web service consumer: 1. Reuse your outbound service interface, for example, FlightSeatAvailabilityQuery_Out from the ES Repository with interface pattern stateless (XI 3.0 compatible). o o o Import the WSDL of the service interface into the SAP NetWeaver Developer Studio. In your project, select File Import Web services WSDL. Select Enterprise Service Repository as available WSDL source and select the interface to be imported.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 4

Migration Guide for Java Proxies

2. Generate an outbound JAX-WS proxy based on the WSDL document. o o Right-click on the imported WSDL and choose Web Services Generate Client. This starts the proxy generation wizard. Verify that SAP Server and SAP NetWeaver are selected as Server and Web service runtime and move the slider to the Develop Client step.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 5

Migration Guide for Java Proxies

Select Next. You are notified that the WSDL does not contain any service. The system asks if you want to generate a default service. You do not need to update the WSDL with the default service unless you want to use JAXWS customization files to customize the default proxy generation algorithm.

Complete the wizard by accepting all values proposed on the next pages or change them as required.

The JAX-WS proxy is generated. 3. Create a consumer application that uses your generated deployable proxy. The consumer application instantiates the deployable proxy by JAX-WS means using the WebServiceRef annotation. o In your client code (servlet or EJB), add a field for the service and annotate it with the WebServiceRef annotation:

@WebServiceRef(name="FlightSeatAvailabilityQueryOutService")
private FlightSeatAvailabilityQueryOutService service;

o o

In your application, invoke the getPort method to get an instance of the service endpoint interface. You can now invoke the appropriate method of the port instance to call the service exposed by PI (based on the XI adapter).

FlightSeatAvailabilityResponseType result = port.flightSeatAvailabilityQueryOut(query );

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 6

Migration Guide for Java Proxies

Instantiate the input objects using plain JAX-WS: FlightID flightID = new FlightID(); flightID.setAirlineID("LH"); flightID.setConnectionID("1000"); XMLGregorianCalendar date = DatatypeFactory.newInstance().newXMLGregorianCalendar(); date.setDay(1); date.setMonth(11); date.setYear(2009); flightID.setFlightDate(date); FlightSeatAvailabilityQuery query = new FlightSeatAvailabilityQuery(); query.setFlightID(flightID);

4. Build and deploy the Web service consumer on the Advanced Adapter Engine. 5. To create a logical port for the Web service consumer, go to SAP NetWeaver Administrator SOA Management Application and Scenario Communication Single Service Administration (alias /nwa/ssadmin). o Select Consumer Proxies and search for FlightSeatAvailabilityQuery_Out. On the Configuration tab, a list of logical ports is displayed for your proxy. At deployment, the engine has created a default logical port based on the XI 3.0 transport binding. o Either reuse the logical port or create a new one based on the XI 3.0 transport binding. o If you reuse the default logical port, select Edit and enter Sender Party and Sender Service (called Communication Component in the Integration Directory) as required by your sender agreement in the Integration Directory.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 7

Migration Guide for Java Proxies

Note: JAX-WS allows you to define multiple ports and specify which one to use at runtime by giving the port name in the getPort method. In point-to-point Web service communication without PI, this can be useful when you need to access multiple backend systems. When using PI as an integration broker, you define this setting in the receiver determination of your integration scenario, not in your application.

6. Instead of maintaining the Sender Party and Sender Service (Communication Component called in the Integration Directory) in SAP NetWeaver Administrator, you can include this information in your coding: Use XIManagementInterfaceFactory to instantiate an XIMessageContext before calling the port method:
FlightSeatAvailabilityQueryOut port = service.getPort(FlightSeatAvailabilityQueryOut.class); XIManagementInterface xiMngmnt = XIManagementInterfaceFactory.create(port); XIMessageContext msgCtx = xiMngmnt.getRequestXIMessageContext(); msgCtx.setSenderPartyName("MY_PARTY"); msgCtx.setSenderService("MY_SENDER"); FlightSeatAvailabilityResponseType result = port.flightSeatAvailabilityQueryOut(query );

7. To use XIManagementInterface, add a build, deploy and runtime dependency to the tc/je/webservices/lib development component. Running your application code (for example servlet) invokes the JAX-WS proxy. The proxy calls the Web service runtime. The Web service runtime transforms the JAX-WS message into an XI message and passes it to the Java Proxy Runtime (JPR). JPR runs on the Advanced Adapter Engine. The Advanced Adapter Engine sends the message to the Integration Server. The connection between the Advanced Adapter Engine to the Integration Server is already configured during technical configuration.

Implementing and Configuring a Java Proxy as a Receiver

To create a Web service provider as a Java proxy receiver, proceed as follows: 1. 2. Reuse your inbound service interface, for example FlightSeatAvailabilityQuery_In from the ES Repository with interface pattern stateless (XI 3.0 compatible). Import the WSDL document from the ES Repository into your SAP NetWeaver Developer Studio. o o o In your project, select File Import Web services WSDL. Choose Enterprise Service Repository as the available WSDL source. Select the interface you want to import:

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 8

Migration Guide for Java Proxies

3.

Generate an inbound JAX-WS proxy based on the WSDL document. The Web service framework generates the skeleton of the implementation bean containing the Web service methods declarations for the operation in the WSDL document. o Right-click on the imported WSDL and choose Web Services Generate Java Bean Skeleton. This starts the proxy generation wizard. o Verify that SAP Server and SAP NetWeaver are selected as Server and Web service runtime and move the slider to the Develop service step.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 9

Migration Guide for Java Proxies

Select Next. You are notified that the WSDL does not contain any service. The system asks if you want to generate a default service. You do not need to update the WSDL with the default service unless you want to use JAXWS customization files to customize the default proxy generation algorithm.

Complete the wizard by accepting all proposed values on the next pages or change them if you wish.

An EJB skeleton is generated with default implementation of the service operation. 4. To make the service callable through the XI 3.0 protocol instead of the WS protocol, do the following: o On bean class level, add an @XIEnabled annotation. The annotation specifies that the service will be called via the XI 3.0 protocol and not through the WS protocol. o Add a @TransportBindingRT annotation in the following way:

@TransportBindingRT(AltPath="{<service_interface_namespace>} <service_interface_local_name>")

If your interface contains an asynchronous operation, the following annotation is automatically added during the generation of the bean skeleton:

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 10

Migration Guide for Java Proxies

@RelMessagingNW05DTOperation(enableWSRM=true)

5. 6. 7.

Provide an implementation of the business methods of the Web service. Use ProviderXIMessageContext class to provide transport-relevant data. Deploy the Web service on the Advanced Adapter Engine.

Error Handling
SAP NetWeaver PI can handle system and application errors. System errors are triggered by the messaging system. System errors happen during transfer or due to a failed server, for example. Application errors are triggered or handled by the application alone. An example of an application error could be a request for data about a material that is unknown in the receiver system. For application errors, define fault messages in the ES Repository. Using synchronous communication, an application can report application errors to the caller application. In asynchronous cases, you can catch an error that has occurred during transfer and, on the inbound side, forward an error to monitoring. Model fault messages in the ES Repository for each application error. During proxy generation (inbound or outbound), the framework generates an exception class for each fault message. The declaration of the service operation method also contains this exception in its throw clause. Therefore, you can catch such a checked exception and receive an instance of the particular application error. For system errors you get a WebServiceException that is a RuntimeException that you have to catch.

Supported Methods in the Web Services Environment

With SAP Exchange Infrastructure 3.0 and SAP NetWeaver 7.0, usage type Process Integration, you can use the MessageSpecifier interface that provides methods for accessing the payload, setting the receiver, handling attachments, querying the message ID, requesting acknowledgments, and so on. With SAP NetWeaver Process Integration 7.1, EHP 1, the XIMessageContext and the ProviderXIMessageContext interfaces allow access to information in the XI message. XIMessageContext is available for outbound/sender communication. ProviderXIMessageContext is available for inbound/receiver communication. Methods Currently Supported The following methods of MessageSpecifier are currently supported in the Web Services environment by the XIMessageContext interface: Serialization Context public void setQueueId(String id) You can assign a serialization context to multiple messages to guarantee the quality of service exactly once in order. Setting the Receiver public void addReceiver(String partyName, String partyAgency, String partyScheme, String service) You can add a receiver party to the set of all receivers. public void clearReceivers() Deletes all specified receivers.

Requesting Acknowledgments public void setSystemAckRequested(String ackListenerName) This method requests a positive system acknowledgment.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 11

Migration Guide for Java Proxies

public void setSystemErrorAckRequested(String ackListenerName) This method requests a negative system acknowledgment. public void setApplicationAckRequested(String ackListenerName) This method requests a positive application acknowledgment. public void setApplicationErrorAckRequested(String ackListenerName) This method requests a negative application acknowledgment.

Methods Supported as of SAP NetWeaver PI 7.1, EHP 1, SPS 5 As of SAP NetWeaver PI 7.1, EHP 1, SPS 5 the following MessageSpecifier interfaces will be made available with the ProviderXI MessageContext interface: Serialization Context public String getQueueId() This method returns the queue ID of the XI request message. Determining the Sender at the Receiver public String getSenderService() This method determines the sender communication component (service) of a message received at the receiver. public String getSenderPartyName() This method determines the sender party of a message received at the receiver.

Receiving Acknowledgments getApplicationAckRequested This method returns the request XI message application acknowledgment. getSystemAckRequested This method returns the request XI message system acknowledgment. getSystemErrorAckRequested This method returns the request XI message system error acknowledgment. getApplicationErrorAckRequested This method returns the request XI message application error acknowledgment. Additionally, the following methods will be made available: getProperty This method returns the property value mapped to the specified key. getServiceInterfaceName This method determines the service interface. isAsync This method determines whether the request XI message is an asynchronous message.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 12

Migration Guide for Java Proxies

Methods Not Currently Supported The following MessageSpecifier methods are not currently supported: Serialization Context public void setMessagingTimeoutInMSec(long timeout)

Calling the Payload public String getInputPayload() public String getOutputPayload() public void setPayload(String payload)

Setting the Receiver public void addReceiverService( String service) public boolean removeReceiverService(String service)

Attachments public MessageAttachment createAttachment( String name, String type, Object data) public MessageAttachment addAttachment( String name, String type, Object data) public void addAttachment( MessageAttachment attachment) public boolean removeAttachment(MessageAttachment attachment) public void clearAttachments() public MessageAttachment getAttachment(String name) public java.util.Enumeration getAttachments()

Determining the Sender at the Receiver public String getSenderPartyAgency() public String getSenderPartyScheme()

Querying a Message ID public com.sap.guid.IGUID getMessageID() public com.sap.guid.IGUID getMessageIDLastSent()

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 13

Migration Guide for Java Proxies

Related Content
Methods of MessageSpecifier: Special Services of the Proxy Runtime Methods of XIMessageContext: Application Program Interfaces for Outbound Proxy Communication Methods of ProviderXIMessageContext: Application Program Interface for Inbound Proxy Communication For more information, visit the Service Bus-based Integration homepage

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 14

Migration Guide for Java Proxies

Copyright
Copyright 2009 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, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. 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. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, 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 other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects S.A. in the United States and in other countries. Business Objects is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this docume nt 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 ("S AP 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.

SAP COMMUNITY NETWORK 2009 SAP AG

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com 15