How mature is the EchoSign API

Java Web Services With Apache Axis 2 German [PDF]

This document was uploaded by our user. The uploader already confirmed that they had the permission to publish it. If you are author / publisher or own the copyright of these documents, please report to us by using this DMCA report form. Report DMCA

E-book content

Thilo Frotscher, Marc Teufel, Dapeng Wang Java Web Services with Apache Axis2

Thilo Frotscher, Marc Teufel, Dapeng Wang

Java Web Services with Apache Axis2

Thilo Frotscher, Marc Teufel, Dapeng Wang: Java Web Services with Apache Axis2 ISBN: 978-3-935042-81-9

© An imprint from Software & Support Verlag GmbH

Your contact to the publisher and editing department: [email protected]

Bibliographic information from the Deutsche Bibliothek The Deutsche Bibliothek lists this publication in the Deutsche Nationalbibliografie; detailed bibliographic data are available on the Internet at

Proofreading: mediaService, Siegen Typesetting: mediaService, Siegen Cover graphics: Melanie Hahn, Maria Rudi Cover design: Caroline Butz Exposure, printing & binding: M.P. Media-Print Informationstechnologie GmbH, Paderborn All rights, including translations, are reserved. Reproduction of any kind (photocopy, reprint, microfilm, recording on electronic data carriers or other processes) only with the written consent of the publisher. No liability can be accepted for the correctness of the entire work, despite careful examination by the author and publisher. The products, trademarks and company names mentioned in the book are usually protected by their owners.

Table of contents Preface


Who Should Read This Book?




Important note about the listings















Supported standards



What does Axis2 include?



Why use Axis2? Better performance through StAX and AXIOM More flexible communication infrastructure Easier deployment of services Better support during development Extended handler concept Better support for current standards

24 24 24 24 24 25 25


The future of Axis2



Web service basics



SOAP message format Processing model SOAP fault message exchange Protocol binding SOAP 1.2 vs. SOAP 1.1

27 28 31 34 36 39 41


WSDL MEPs - Message Exchange Patterns WSDL 1.1 WSDL 2.0

44 45 46 52


Code First vs. Contract First The Code First Approach The Contract First Approach Use of Contract First with existing code

54 55 58 61

Java Web Services with Apache Axis2


Table of Contents



First steps



Axis2 distributions



Installing Axis2 The Axis2 Standard Distribution web application

64 64 67


Central concepts of Axis2 AXIOM Service Archive Message Receiver Repository

69 69 69 70 71


Implementation of simple web services with POJOs



Deployment of services in a standalone server



Use of the Axis2 web application. Deployment of Web Services Service Administration

81 81 83


Development of a client for the SimpleHotelService. Direct use of the Axis2 client API. Development of clients with the help of code generation

85 85 89


Peaceful nights with Axis Hotels



Development with Axis2



Using Eclipse as Development Environment Project Setup Eclipse Web Tools Platform

93 93 95


Axis2 Eclipse Plug-ins Code Generator Wizard Service Archiver Wizard

96 96 96





Diving into the Sources View and browse the Axis2 source code Exploring the Axis2 source code - A small example

99 100 101


Tools for dealing with SOAP messages Apache TCPMon SOAP Explore and learn with TCPMon SOAPMonitor

103 103 106 107








StAX Push vs. Pull Parsing StAX API XML parsing with StAX

111 111 113 114

Table of Contents


AXIOM AXIOM architecture AXIOM API caching

122 123 125 132


Web service implementation with AXIOM



Client API






Call pattern Request-Response with blocking API Request-Response with non-blocking API via one connection Request-Response with non-blocking API via two connections One-way call Reliable one-way call

144 146


Client-side configuration JavaBean properties Generic properties HTTP properties

155 155 157 160





Contract First with Axis2



Code generation Calling WSDL2Java from the command line Axis2 code generator wizard for Eclipse Ant task

169 170 177 181


Implementation and deployment of services The resources folder Generated code and implementation of the packaging and deployment service

183 183 186 190


Implementation of service clients



One way communication



Further aspects of development


Error handling Definition of errors in XML schema and WSDL code generation

203 205 208


Service life cycle



Session management Request session scope SOAP session scope Transport session scope

216 219 220 222

Java Web Services with Apache Axis2

147 149 153 154



Table of Contents

Application scope session management with client applications Code example


223 224 224


REST Introduction of SOAP or REST? Configure REST in Axis2 HTTP GET HTTP POST HTTP GET or HTTP POST?

230 230 231 232 233 234 243


Architecture and configuration



Internal processing of SOAP messages flows phases dispatch mechanism

246 246 251 255


Internal data structures: Description and context description hierarchy Context hierarchy Relationship between context and description hierarchies Loading of configurations

257 257 259 261 262


Global configuration parameters Message Receiver Transports Globally activated modules and module configurations Standard module version Phases Target Resolver Listeners / Observers

263 264 265 265 266 266 266 267 268


Configuration of services Services and service groups Definition of the names of services and service groups WSDL documents and automatic WSDL generation Elements of the services.xml file Service parameters

270 270 271 271 272 277


Deployment of services Axis2 web application standalone server

279 279 280


Access of a service to context and configuration



Access to resources in the service archive



Start of Axis2 with a remote repository


Table of Contents


Handlers and modules


10.1 Handler The handler interface Implementation of handlers Configuration of handlers

286 287 289 290

10.2 Modules The Module Interface Configuration of Modules Packaging and Deployment Engagement Dynamic engagement at runtime

292 293 294 299 302 307


Data binding


11.1 Basics of XML data binding


11.2 Code generator framework


11.3 ADB - Axis Data Binding ADB schema compiler ADB integration in Axis2 code generation

318 318 322 323

11.4 XMLBeans


11.5 JiBX


11.6 JAXB RI


11.7 JAXME


11.8 Summary



Message Receiver & ServiceObjectSupplier


12.1 Introduction Looking back: Providers in Axis 1.x Looking ahead: Journey through the Axis2 engine

357 357 358

12.2 Message receiver Contract First Message Receiver from the inside

359 360 360

12.3 Axis2 and Groovy


12.4 Message Receiver and WSDL


12.5 Enterprise JavaBeans and Axis2 Introduction Possibilities to integrate an EJB The bank code service as EJB The implementation of EJBMessageReceiver EJB provide as a web service

371 371 373 374 379 380

Java Web Services with Apache Axis2


Table of Contents

12.6 ServiceObjectSupplier


12.7 Spring Framework Introduction of Axis2 and the Spring Framework The sort code service as Spring Bean SpringServletContextObjectSupplier Required Spring libraries SpringAppContextAwareObjectSupplier

385 385 386 388 393 395 396

12.8 The EJBUtil implementation





13.1 Base64 & SwA Base64 SwA

409 410 411


414 414 418 419

13.3 MTOM in Axis2 OMText MTOM Web Service with AXIOM-API MTOM data binding

420 420 421 432

13.4 SwA in Axis2


13.5 Attachment caching




Transport protocols


14.1 Transport mechanism TransportListener TransportSender

447 448 449

14.2 Activation of transport protocols at the service level


14.3 HTTP Transport Receiver for Standalone Mode Embed SimpleHttpServer in your own applications CommonsHTTPSender

451 451 453 454

14.4 TCP


14.5 Mail Transport (SMTP) Configuration of the web service mail transport via mail

460 461 466

14.6 JMS Installation of ActiveMQ Services with JMS communication Client applications with JMS communication

471 471 472 475

Table of Contents


Modules for WS- * extensions


15.1 WS-Addressing Basics WS-Addressing with Axis2

478 478 480

15.2 WS-Policy Basics Neethi: WS-Policy with Axis2

485 485 488

15.3 WS-Security basics Rampart: WS-Security with Axis2 Configuration with WS-Policy

490 490 494 534

15.4 WS-ReliableMessaging Basics Sandesha2: WS-ReliableMessaging with Axis2

537 537 542


XML Schema and WSDL from Axis Hotels






Command line



Ant task



Maven plug-in





Command line



Maven plug-in



Maven 2 AAR plug-in


Keyword index


Java Web Services with Apache Axis2



Preface It has been three years since we published our first book on Apache Axis 1.x. A long time, especially in the IT industry. At the time, web service technology was still in its infancy and the second generation of web service frameworks was just about to replace the first. Many developers and experts agreed that the concepts underlying the technology were extremely helpful and beneficial when integrating heterogeneous applications. There were plenty of potential areas of application, but overall web services gained acceptance somewhat more slowly than was to be expected in view of the hype surrounding the topic. This was for a number of different reasons. One of the most important ones was certainly that some basic requirements for business-critical applications, such as security, had not yet been satisfactorily met at the time. Various specifications already existed for corresponding extensions of the web service world, but the available implementations were not yet fully developed and repeatedly triggered interoperability problems. In general, the interoperability of most frameworks was not the best. A grotesque situation, given that web service technology is supposed to solve such problems instead of creating new ones. In the meantime, the situation has changed significantly: Web services have practically become an integral part of software development - they serve well in many areas of application and in a wide variety of industries. And even if more powerful and, above all, more efficient solutions are still available for many communication requirements, web services meanwhile keep the original promise of integrating heterogeneous systems with one another in a relatively simple way. At the same time, fewer web services are publicly available and available to everyone than was initially assumed. But in the communication between companies and business partners as well as in the interior of company architectures, web services are very widespread these days. Be it international hotel reservation systems with a large number of connected hotel chains and sales partners, systems in the financial services sector, in the logistics industry or various bodies in the public sector (authorities, ministries, etc.) - the areas of application are extremely diverse. The Web Services Interoperability Organization (WS-I) made an important contribution to the widespread use of web service technology. It publishes policy documents such as the Basic Profile, which describe how the individual technologies (SOAP, WSDL, etc.) should be used to ensure the highest possible interoperability. Today, no framework and no implementation in this area can seriously afford not to follow the Basic Profile. To be compatible with this, on the other hand, can be considered a seal of approval that indicates that the most common interoperability problems can be safely circumvented by the respective tool.

Java Web Services with Apache Axis2



As web service technology has grown, Axis 1.x is getting on in years. When it was implemented, some assumptions were made that were certainly sufficient at the time, but are more of a handicap today. In addition, the requirements for web service technologies have continued to develop. The technology is used in increasingly complex scenarios, and the requirements of modern web service applications are either impossible or very difficult to implement with Axis 1.x. A new architecture became necessary for Axis, which is more flexible and more powerful. Axis2 is therefore not just a new version of Axis 1.x, but in many ways a completely new framework. This was implemented on the basis of the experience of past years, whereby many proven concepts and ideas can be found in a refreshed form. As with many open source projects, developers quickly come up against the limits of the official documentation when using Axis2. This is where this book comes in and offers several hundred pages of detailed information on using the framework. Much of the information in this book is first documented and discovered through time-consuming analysis of Axis2's source code.

Who Should Read This Book? This is a book by developers for developers who already have previous knowledge of the most important web service technologies and now want to create applications with Axis2. The basic technologies SOAP and WSDL are introduced in Chapter 2, but it is more used to look up or refresh existing knowledge. Its reading, however, is not exhaustive enough to give newcomers to the web service world sufficient knowledge about this technology. Numerous other books that are available on the market help here. The situation is similar with further web service specifications such as WS-Security, WS-Addressing or WS-Policy, the use of which with Axis2 is explained in Chapter 15. Here, too, it is true that these are presented in an introductory manner, but more in-depth knowledge of these technologies should be acquired for serious use in the project. This book, on the other hand, focuses entirely on Axis2. It contains hundreds of pages with information and suggestions on how the framework can be used and configured. In addition, there are numerous assessments and recommendations based on our many years of project experience with web service technologies.

Structure The book consists of three parts. In the first part, after an introductory chapter, important basics are imparted, which lay the necessary foundation for the further course of the book. Chapter 2 first describes the two most important technological foundations of web services, namely SOAP and WSDL. Then the two most important approaches to developing web service applications are compared (Code First and Contract First). Every developer should know the difference and be aware of the pros and cons of both approaches,



before starting the development of web service applications. Chapter 3 then accompanies the reader in the first steps with Axis2 and shows how simple services can be created on the basis of POJOs (Plain Old Java Objects) and corresponding clients can be developed. In addition, central concepts of Axis2 are explained here. The second part of the book then deals in detail with topics of daily development work when using Axis2. Chapter 4 introduces helpful tools for development and testing and Chapter 5 deals with AXIOM, a new object model for working with XML on which the entire Axis2 framework is based. Chapter 6 then describes the new client API, the development of web service applications with the contract-first approach and using the Axis2 code generator is the content of Chapter 7. Further aspects of application development such as session management, error handling, REST or the life cycle of service instances are dealt with in Chapter 8 and round off this part of the book. Up to this point it is advisable to read all the chapters in their given order. In the third and last part of the book, advanced topics are taken up. Chapter 9 describes the internal architecture of Axis2 and shows how messages flow through the framework and which components are involved in their processing. This is followed by a complete listing of all configuration options. A particular strength of Axis2 is its expandability with handlers and modules. Chapter 10 explains how developers can create their own extensions and thus adapt Axis2 to their own requirements. XML data binding is also an important aspect of web service applications. Axis2 provides support for several different data binding frameworks, which are presented and compared in Chapter 11. One of the most central components of the Axis2 framework are the message receivers. On the server side, you are responsible for calling up the service implementation and implementing the communication pattern of the operation. Message receivers can be used, among other things, to easily provide EJBs, script code or other alternative forms of implementation as a web service. Chapter 12 describes how to do this. This is followed by information about sending attachments with MTOM or SwA in Chapter 13 and about the use of the various supported transport protocols (HTTP, TCP, SMTP and JMS) in Chapter 14. The last chapter is all about further web service specifications like WS-Addressing, WS-Policy, WS-Security and WS-ReliableMessaging. The chapter describes to what extent these are supported by Axis2 or additionally available expansion modules and, in the further course, how these are used and configured.

Java Web Services with Apache Axis2



Important Note About the Listings Many of the listings in this book have been reformatted to improve readability. XML documents in particular, such as SOAP messages and configuration files, often have significantly longer lines than fit on a book page. In the case of configuration files, however, it must be ensured that opening and closing element tags as well as the element contents in between should be in the same line. If an XML element was formatted over several lines, e.g.

Element content

this should usually be used as follows instead: Element content

Feedback We are very interested to know how you like our book. What do you find successful, in which areas do you have suggestions for improvement? Are you missing content that you have searched in vain in this book? Or maybe you even found a bug? Please write to us, we look forward to your feedback. Only if you tell us what you like or what you don't like can we make everything even better for the next book. However, depending on the number of readers who send us feedback, we may not be able to answer all emails. We ask for your understanding. The publisher has set up an email address that you can use to contact us: 쮿

[email protected]

Alternatively, you can contact the authors directly. 쮿

Thilo Frotscher: [email protected]


Marc Teufel: [email protected]


Dapeng Wang: [email protected]

Acknowledgments Many people are involved in the creation of a book, not just the authors. Without the help of many people, a book like this cannot come into being. At this point we would like to express our thanks to the following people:



Thilo Apache Axis2 is a fairly new framework and accordingly very little documentation was available when we started working on this book. The writing therefore turned out to be extremely time-consuming and the book project could only be mastered in a team. So I'm very happy that Dapeng and Marc were there again. Thank you both for the friendly cooperation. It was hard work again, but it was a lot of fun. From the publisher, I would particularly like to thank our editor Christiane Auf, who was very patient when we had to change the schedule again. In addition, a big thank you goes to Sebastian Meyen for his support in implementing the idea of ​​writing a book about Axis2. I would also like to thank our typesetter Andreas Franke very much. I would also like to thank the Axis2 development team, to whom I reported numerous bugs and asked questions. The team always responded to both with very prompt help. In this context, I would like to ask all users not to be displeased with any bugs or missing documentation. Axis2 is an open source project and everyone can help to make it even better. This is the only way open source can work. My special thanks go to Cathy, who always showed a lot of understanding as I spent numerous evenings, nights and weekends researching the depths of the source code and putting my discoveries on paper. With her support she has made a major contribution to the success of this book.

Marc First of all, I would like to thank everyone who worked with me on this book, above all of course my two author colleagues Thilo and Dapeng (our Skype sessions will be fondly remembered!). I would also like to mention our editor, Ms. Christiane Auf from, who literally showed "angelic patience" and gave us the necessary time to research and edit the manuscript for this book as thoroughly as possible. A very special and heartfelt thank you goes to my dear wife Daniela. She gave me the freedom I needed when I was working on this book (and that was mostly the evenings, weekends, and a few nights). Dani, you are the best that could have happened to me. The whole world should know: Dani, I love you! Timo and Tom, you are my drive!

Java Web Services with Apache Axis2



Dapeng First of all, I would like to thank everyone who has actively collaborated on this book. Special mention should be made of our editor, Ms. Christiane Auf from, who has shown a lot of patience and insight over the long period in which this book was written. Such a book project cannot be tackled alone. I would like to thank my two co-authors for this, who were also so patient with me when I ran behind schedule at the beginning. I think we managed everything very well. I enjoyed discussing web services with you. The book would certainly not have existed if the developers of WSO2 hadn't launched Axis2 in the first place. I thank you for your excellent work and the resulting software. My very special thanks go to my wife, Lan Zhang, who, despite her own stress, always tried to keep my back free so that I could devote myself fully to the book project. She always showed understanding when I sat in front of my computer in the evenings, at night and on the weekend and worked on the book project. I should also like to take this opportunity to thank my son Edison Tianyi Wang. He showed just as much consideration as with the first book project (at that time he was only born after the book project) by being satisfied with less playing time together during the project. I just hope that next time you will forego the gummy bears and model cars as an additional reward. Last but not least, I would like to thank my parents who raised me over the years and still do it today.

Wellington, Ellingen and Wiesloch in March 2007

Thilo Frotscher Marc Teufel Dapeng Wang


Preface Far from its humble beginnings, Web services are gaining popularity in B2B environments. The many additions and updates to various WS- * specifications are providing users with a multitude of features. Applications have reached a level of maturity where people now expect high performance too when using Web services. The Axis2 platform from the Apache Web services project is ideally placed to fill in the growing demand of requirements of users. Apache being the pioneer in open source Web services stacks, designed Axis2 from the ground up and also introduced several new concepts including a more flexible pipeline architecture to the "handler chain" model, hot deployment and real asynchronous web service invocations. Another driving force for Axis2 is the move away from RPC-oriented Web services towards more document-oriented, message style asynchronous service interactions. It is centered on a new representation for SOAP messages called AXIOM (AXIs Object Model). This book, which is a first of its kind, aims to provide insights to these concepts and gives an overview of using the rich set of features Axis2 provides. Marc, Thilo and Dapeng, all experienced campaigners in the Web services arena, start by introducing the architecture and basics of Axis2 and slowly move on to more advanced concepts like attachment handling. They have managed to cover everything you need to know, all in one book! I am very proud to be part of this effort and congratulate Marc, Thilo and Dapeng for a job well done.

Eran Chinthaka Apache Axis2-Project Team from Indiana University, USA

Java Web Services with Apache Axis2


Introduction Apache Axis2 is the successor to Apache Axis and, like its predecessor, an open source implementation of the SOAP web service standard under license from the Apache Software Foundation. In addition to SOAP, Axis2 also supports the increasingly popular REST for communication with web services. Building on the extensive experience that the development team had made with Axis 1.x, the decision was made to completely redesign the framework so that Axis2 was developed from scratch. As a result, Axis2 is much more powerful and more XML-based than its predecessor. It has a modular structure and care was taken right from the start that extensions using so-called modules can be added very easily. Some of these extensions, such as for WSSecurity and an extension for SOAP monitoring, are already available. Axis2 offers the following highlights: 쮿

Open source license from the Apache Software Foundation


High performance


Flexible configuration and expandability through modules


Improved, XML-based client API with full support for WSDL and WS-Policy, as well as synchronous and asynchronous web service calls


Support for any communication pattern (MEPs)


POJO support


Spring integration


Deployment mechanism for services and modules based on archives


Hot deployment and hot update


Built-in transport support for HTTP, SMTP, JMS and TCP


Support of REST (Representational State Transfer)


Support for various XML data binding frameworks



With Axis 1.x, the Apache Software Foundation created a very popular framework for developing web services applications using Java. The project is now getting on in years: Axis 1.x was too slow, used up too

Java Web Services with Apache Axis2


1 Introduction

lots of system resources and was too complicated to use. In addition, it is very much designed for request-response-based communication, while alternative communication patterns are awkward or impossible to implement. The implementation of some more advanced specifications of the WS world such as WS-SecureConversation or WS-Trust is almost impossible. The fact that Axis 1.x was originally developed with a focus on the SOAP message format RPC / Encoded became more and more of a problem. In short: Axis 1.x was no longer able to cope with the requirements of modern web service applications. For the new Axis generation, it was therefore decided to develop the framework from scratch and to offer better support for document-based communication and the Basic Profile published by WS-I (Web Services Interoperability Organization) right from the start. Other reasons for a new development were the support for asynchronous communication, performance, and some new specifications that should be implemented, such as WSDL 2.0. Development on Axis2 actually began in September 2003, when three young students joined the Lanka Software Foundation (LSF) and had to face a special task from their supervisor, from which Axis2 was later born. LSF has set itself the task of supporting young budding software developers from Sri Lanka (by the way, this island state was still called Ceylon until 1972). The supervisor in question gave the students the task of working on Axis 1.x and using a pull parser to achieve a 10-fold increase in performance. The task was done with flying colors by the students and the fruits of this labor were donated to the Apache Foundation under the name Axis Mora. Spurred on by Axis Mora, heated discussions broke out on the Axis developers' mailing list about what to do next with Axis. At first, however, it remained a matter of discussion. However, after the Lanka Software Foundation received a financial injection from SIDA (Swedish International Development Agency), enough money was finally available to let 4 to 5 motivated developers work full-time and for a whole year on the next generation of Apache Axis. The result of these efforts was Axis2 1.0, which was released on May 4th, 2006. The development work on Axis2 has not stopped since then. On November 13, 2006, the development team released version 1.1, another stable Axis2 version for productive operation, which not only shines with numerous bug fixes, but also contained a not inconsiderable number of new features. At the beginning of January 2007 the bugfix version Axis2 1.1.1 was finally released.


Supported standards

Support for the core web service standards SOAP and WSDL is of course a matter of course for a web service framework. However, Axis2 also supports a number of other standards. In the version 1.1.1 current at the time of publication of this book these are: 쮿

SOAP 1.1 and 1.2


WSDL 1.1 (including SOAP and HTTP bindings) and partly already WSDL 2.0


What does Axis2 include? 쮿

MTOM (Message Transmission Optimization Mechanism), XOP (XML Optimized Packaging) and SwA (SOAP with Attachments)


WS addressing




SAAJ 1.1

Additional modules are also available which expand Axis2 with support for the following web service standards: 쮿







WS-Reliable Messaging

In contrast to frameworks such as Axis 1.x or XFire, for example, Axis2 cannot yet support the standardized Java Web Services APIs JAX-RPC or its successor JAX-WS (Java API for XML-based Web Services). wait up. There is also no support for the JSR 181 (Web Services Metadata) yet. Axis2 offers a very fast and easy-to-program API with AXIOM, which is based on StAX. In order to support the JAX-WS standard in the future, however, the Axis2 developers are currently working flat out on a thin adapter layer that will be compliant with the JAX-WS 2.0 standard. Since JAX-WS 2.0 makes extensive use of JAXB 2.x for data binding, Axis2 will in future also have support for JAXB 2.x in addition to the data bindings ADB, XML Beans, JaxMe and JiBX that have been supported so far. Furthermore, additional expansion modules for web service standards are already being developed. These will include support for WS-Eventing and WS-Transactions.


What does Axis2 include?

Axis2 consists of a number of different components that can either be used together or separately from one another. Various distributions are also available. Depending on which one you choose, they contain different amounts of the following ingredients: 쮿

a runtime environment (or a container) for web services, either in the form of a Java web application and / or various standalone servers


Libraries for creating web service clients


extensive web interface for administration of the Axis2-Web application


a SOAP monitor module for tracking SOAP messages


Tools for the automatic generation of code and WSDL documents


Plug-ins for Eclipse and IntelliJ IDEA that simplify the deployment of your own services and code generation


Extensive documentation with many examples

Java Web Services with Apache Axis2


1 Introduction


Why use Axis2?

This is a legitimate question, especially since Axis 1.x in its current version 1.4 is still very popular and is now also very stable due to the long development time. In addition, Axis 1.4 can now come up with improved support for the Document / Literal message format, as required by the Basic Profile. However, there are several good reasons for switching to Axis2, which are explained below.


Better performance through StAX and AXIOM

A central aspect of SOAP frameworks is the internal processing of XML-based messages. Axis2 turns away from the tried and tested DOM (Document Object Model), in which an object tree is first created in memory for all incoming messages, which represents the content of the incoming message. Instead of DOM, StAX-based XML parsing is used in Axis2, which parses SOAP messages only as far as is necessary at a given point in time during processing. This “postponed” parsing prevents, for example, a SOAP body from being read unnecessarily, although the message is already rejected because of its header. Based on StAX, a lightweight object model called AXIOM (Axis Object Model) was developed for Axis2, which offers efficient access to the individual message contents. Since AXIOM is not a standardized API, there will be an adapter layer based on it that conforms to JAX-WS 2.0 (formerly JAX-RPC). The switch from DOM to AXIOM alone brings significant improvements in terms of speed and memory consumption compared to Axis 1.x, which have been proven with the help of benchmarks and performance tests.


More flexible communication infrastructure

In principle, Axis2 supports any communication pattern and is not limited to RequestResponse or one-way communication. Asynchronous communication is also fully supported.


Easier deployment of services

The deployment of your own web services has become much easier with Axis2. In Axis2, services are combined with a configuration file to form an archive and installed and managed using the web-based administration front-end, which has been significantly expanded compared to Axis 1.x.


Better support during development

Code generators are still available for application developers, with the help of which, based on WSDL descriptions, basic structures for service implementations and proxy classes for client applications can be generated. To the


The future of Axis2

To make working with Axis2 even easier, Axis2 also offers plug-ins for Eclipse and IntelliJ IDEA, which support developers in generating code and packaging web services.


Extended handler concept

With the help of the concept of handlers, it was already possible in Axis 1.x to intervene in the processing of SOAP messages and thus adapt the framework to your own needs or to expand the required functionalities. In Axis2, the concept was expanded to include so-called phases, which represent different sections of message processing. In this context, rules can be defined that describe in which phase a handler should be located and in which position. For example, you could define that a handler should always be activated first or last within a phase. One or more handlers are combined with a configuration file to form expansion modules that are easily installed and linked to specific services.


Better support for current standards

With regard to the numerous new web service specifications, Axis2 is largely up to date. In addition to SOAP 1.2, WSDL 1.1 and MTOM, the important SOAP extensions WS-Addressing, WS-Security, WS-Reliable Messaging and WS-Policy are also included supports, with the help of which web services can also be used in more complex scenarios. Support for these standards is also important for interoperability with Microsoft's .NET 3.0 and its communication component WCF (Windows Communication Foundation, also known under the code name “Indigo”). The XML data binding was completely redeveloped for Axis2 and is now called ADB (Axis Data Binding). However, the interface for data bindings was implemented in an open manner, so that ADB can be replaced by other solutions such as XML beans or JiBX if necessary. Support for JAXB 2.x (or JaxMe) is currently under development and will probably be available with one of the next versions of Axis2. As already mentioned, the same applies to JAX-WS 2.0 (JSR 224) and Web Services Metadata (JSR 181). For Axis 1.x, on the other hand, no new features are planned, so that for this reason alone one should think about switching to Axis2.


The future of Axis2

Axis2 was designed from the ground up to be completely independent of any particular standard. This enables the development team to easily add, swap, or customize support for current standards. Conformity to current standards, in particular Basic Profile 1.1, WSDL 2.0, JAXWS 2.0, JAXB 2.x and JSR 181 are at the top of the roadmap and will be addressed in the upcoming versions of Axis2. In addition, support for cluster environments is already being developed. Also on the wish list are so

Java Web Services with Apache Axis2


1 Introduction

interesting features such as code generation for C # clients, which is already included as an experimental feature in Axis2 1.1.1. Many large companies in the SOA environment have also announced that they will support the further development of Axis2 or integrate Axis2 into their products. A switch from Axis 1.x to Axis2 can therefore be unreservedly recommended, and this book would like to accompany motivated developers on this path.

References 쮿

Apache Axis2 on the web:


Apache Axis2 Wiki:


Apache Axis2 mailing lists:


Apache Axis2 article:


Web service basics Of course, knowledge of the basic web service technologies such as SOAP and WSDL are essential for the use of Axis2. Some marketing experts keep trying to convince developers that using the tools they advertise does not require any knowledge of SOAP or WSDL - everything works automatically. Such statements should be met with the utmost caution: At the latest when errors occur, the application does not seem to do exactly what it should, or your own use case deviates a little too much from the "standard", it is very necessary to deal with the underlying technologies. But this certainly applies to the vast majority of technologies. This book is a book about Axis2. These basics of the individual web service technologies are therefore not described in the necessary detail. The main focus should be clearly on the framework. There are a number of good books available that describe the specifications of major web service technologies and the ideas and concepts behind them. All readers who do not have this basic knowledge are strongly advised to do so before starting to use a web service framework. The time allotted for this should be a bit more generous: SOAP and WSDL in particular are not quite as simple as it may appear at first glance. As is so often the case, the devil is in the details. So this chapter only explains the most important facts about SOAP and WSDL. This is followed by a consideration and comparison of two different development approaches called Code-First and Contract-First. Every web service developer should be aware of the difference between these approaches and, in particular, their advantages and disadvantages. A decision for one or the other approach should be carefully considered - once an application is halfway through, it can often only be switched to the other approach with considerable effort.



SOAP is the most important communication protocol for web service applications. Its specification primarily describes the structure and format of the messages that are exchanged between the service provider and the service consumer when a Web service is called. SOAP was originally launched by DevelopMentor, IBM and Microsoft, while the further development of SOAP is carried out under the auspices of the W3C due to its importance. SOAP is currently in version 1.2, while version

Java Web Services with Apache Axis2


2 - Web Service Basics

1.1 is still widespread in practice and is supported by many programs. The name SOAP originally stood for Simple Object Access Protocol. It quickly became apparent, however, that SOAP, in contrast to IIOP or RMI, has little to do with object or object orientation. However, this appealing name that helped popularize the technology continues to be maintained. But it was explicitly stated that from version 1.2 SOAP is a simple name and is no longer an acronym. While in version 1.1 SOAP was only viewed as a communication protocol in which the structure and exchange of SOAP messages are in the foreground, SOAP was expanded into a messaging framework in version 1.2. Many aspects such as message routing and MEP (Message Exchange Pattern) have been added.


Message format

The fact that XML is a promising invention should not have escaped any developer. XML has established itself particularly in the area of ​​web technologies. The main advantage of XML documents is that they are not tied to any specific application, programming language, or operating system. A .Net-based C # program could, for example, generate an XML message under Windows and send it to a Java program running under Linux, which processes the message further. Firewalls that might have to be passed on the way do not represent any obstacles, because XML-based messages are mostly transported via HTTP, which is allowed through by all firewalls. XML's success is primarily due to its extensibility. In contrast to HTML, elements and attributes can be defined and any data structures can be formulated in XML. So it is not surprising that SOAP is based on XML for the exchange of messages. A SOAP message ultimately packs any XML document in a firmly defined structure in which, in addition to the actual user data (payload), further information can also be transmitted. What the structure of a SOAP message looks like and how an existing XML document can be packaged as a SOAP message is demonstrated below. The starting point is an XML document that represents a hotel reservation.

NH-HD 2007-02-22 2007-02-22 DOUBLE 4 Listing 2.1: XML document




Listing 2.1: XML document (cont.)

This XML document contains information about a hotel room reservation. In an online booking system, this document can be sent as an inquiry, for example, with the expectation that a confirmation with a reservation number will be returned as an answer. It is certainly possible for the communication partners to agree beforehand to exchange the documents directly via HTTP. This type of XML-based communication was not uncommon before the standardization of SOAP and is now also known as POX (Plain Old XML). But at the latest since the spread of web services and the establishment of standard technologies such as SOAP and WSDL, XML-based communication has been almost exclusively via the exchange of SOAP messages. One reason for using SOAP is that a SOAP message can be quickly created from an existing XML document with user data. A SOAP message (apart from SOAP messages with attachments) is itself an XML document and always contains a SOAP envelope, which in turn consists of an optional SOAP header and a SOAP body. The SOAP envelope forms the root element of a SOAP message and is represented by an element called the envelope. SOAP envelope and all SOAP-specific elements contained therein are defined in version 1.2 in the namespace The corresponding namespace for SOAP 1.1 is To obtain a SOAP message from an XML document, the XML document (without XML prologue and DTD reference) is stored directly in the SOAP body, which in turn is enclosed by the SOAP envelope. With these two packages, a SOAP message can be derived from any XML document. The SOAP body with the name Body is a mandatory element. There must always be exactly one SOAP body in each SOAP envelope.

NH-HD 2007-02-22 2007-02-22 DOUBLE Listing 2.2: SOAP message from the previous XML document

Java Web Services with Apache Axis2


2 - Web Service Basics

4 Duke

Listing 2.2: SOAP message from the previous XML document (cont.)

While XML is mainly used to describe data, SOAP clearly focuses on communication. In complex scenarios of web services, it is necessary not only to transmit the user data, but also to send parameters for technical features such as QoS (Quality of Service). Information for addressing, routing, identification, security or transaction control can be named as examples. It can also be useful to store part of the user data in a separate area so that this data can be accessed more efficiently during preprocessing. The SOAP specification has provided a separate area called SOAP Header for this purpose, which can optionally appear in a SOAP envelope. A SOAP header is defined by an element called a header in the SOAP namespace. Any number of header blocks containing metadata for different purposes can be stored within SOAP Header. In the course of processing a SOAP message, the header blocks can be evaluated, changed, added, removed or forwarded. Listing 2.3 illustrates the use of SOAP headers, where the SOAP message from Listing 2.2 has been expanded to include a SOAP header that contains a reference ID and a time.

uuid: 093a2da1-q345-739r-ba5d-pqff98fe8j7d

2001-11-29T13: 20: 00.000-05: 00

Listing 2.3: SOAP message with header



NH-HD 2007-02-22 2007-02-22 DOUBLE 4 Duke

Listing 2.3: SOAP message with header (cont.)

This results in the entire structure of a SOAP message, which is illustrated in Figure 2.1.

Figure 2.1: Structure of a SOAP message, processing model


Processing model

The legitimate question arises as to which data should be sent in the SOAP body and which data should be accommodated in the SOAP header. In order to answer this question, a basic understanding of the processing model of SOAP messages is required. The processing model describes the actions that a SOAP node performs when it receives a SOAP message. A SOAP message is sent from a sender or service requester (initial SOAP sender) to a recipient or service provider (ultimate SOAP receiver). However

Java Web Services with Apache Axis2


2 - Web Service Basics

the path that the SOAP message travels does not necessarily consist of the two nodes sender and receiver. Often there are also so-called intermediaries on the path that can also intervene in the processing process. For example, a security gateway can reject a request in the absence of an expected SOAP header with security information before the message even reaches the recipient. These intermediaries play an extremely important role in setting up a flexible web service infrastructure. Although an intermediary can also play the role of the recipient and process the SOAP body itself, this scenario is by no means common. The intermediaries usually only process one or more SOAP headers addressed to them, while the SOAP body with the user data is intended exclusively for the final recipient.

Figure 2.2: Processing path of a SOAP message with intermediaries

Thus, the above question can be easily answered. All data that are of interest to intermediaries on the way to the recipient should be transported in the SOAP header, while all data intended exclusively for the recipient should be inserted in the SOAP body. Since a SOAP message may contain several header blocks and must pass several intermediaries on the way to the recipient, a mechanism is required to regulate which header should be processed by which SOAP node (intermediaries and recipient). For this purpose, an attribute called role (in SOAP 1.1: actor) of the type anyURI is defined in the SOAP specification, which can be specified for each header block. If a SOAP node has a certain role, which is identified by the URI in the role attribute of a SOAP header, then the node must process the corresponding SOAP header. However, the specification leaves open how the roles of the individual SOAP nodes are to be assigned. This detail therefore remains implementation-specific. Three standard roles are defined for the most common use cases: 쮿

32 means that the corresponding SOAP header is not intended for any special node and therefore does not necessarily have to be processed. Such header blocks are used to transmit additional information that may be of interest for processing other header elements. If such a header is not removed by one of the intermediaries, it will also reach the recipient.

SOAP 쮿 is used more often than none and identifies the next node along the processing path, regardless of whether it is an intermediary or the recipient. A header block with this role must therefore be processed by all nodes (including the final recipient) as long as this header block is passed on in the message.

쮿 states that the SOAP header is only intended for the final recipient and should therefore be ignored by all intermediaries. If no role attribute is contained in a header block, this implicitly means that the header block is only intended for the recipient. Thus ultimateReceiver is the default value for the role attribute.

In addition to these three standard roles, any application-specific role can of course be defined. The only requirement is that this role be identified by a unique URI.





Listing 2.4: Header Blocks with Role Attribute

The above SOAP message has three header blocks. The first has an application-specific role with the URI It is therefore only of interest to nodes that have this role. The second, on the other hand, has the standardized role next and must therefore be processed by all nodes on the path. Since the third header does not have a role attribute, only the final recipient has to process the content of this block.

Java Web Services with Apache Axis2


2 - Web Service Basics

After it has been clarified how it can be determined which node processes a certain header block, the processing of the data in the header will now be explained. In order to avoid that relevant headers are not simply ignored by the responsible node, such a header can be given the attribute mustUnderstand = "true".The mustUnderstand attribute already existed in SOAP 1.1 and means that the respective header must be processed according to the corresponding semantics. If, on the other hand, a node does not understand the data contained in the header block or cannot process it correctly, the node must abort further processing of the message and send back a SOAP fault as a response. If the attribute mustUnderstand has the value false or if this attribute does not exist at all, the node can freely decide whether the header is processed or ignored. In the case of header blocks with critical information such as data for security checks or transaction control, the mustUnderstand attribute should therefore always be set to "true". In the case of the SOAP body, it is not necessary to set this attribute explicitly because every SOAP body always implicitly has a value true for the attribute and must therefore be processed by the recipient. In SOAP 1.2, a third standard attribute is defined that can influence processing. The relay attribute is of the type xsd: boolean and controls whether a SOAP header should be forwarded by an intermediary if it was not processed by the intermediary. Normally, a header processed by the current node is removed from the message before it is forwarded, whereby the same header with the same or slightly different content can also be reinserted into the message. However, it is sometimes also desirable to implement an alternative behavior so that a header can also be processed by all or several nodes. The relay attribute is provided for this. If it is set to the value true, this allows a node to forward a header assigned to it anyway, even if it has not processed it. The combination of role = "next" and relay = "true" means, for example, that every intermediary is given the opportunity to process the header.


SOAP fault

One of the reasons for packing the XML user data in a SOAP envelope and thus using SOAP as the communication protocol is that SOAP has a built-in mechanism for error handling. If a SOAP header cannot be processed correctly by the responsible intermediary or the SOAP body cannot be processed correctly by the final recipient, the respective node must generate a SOAP fault and send it back in the response. The Fault element was defined in the SOAP namespace for this purpose. If it is used, it must be the only child element in the respective body of a SOAP message. The Fault element must always contain the two child elements Code and Reason; the child elements Detail, Node and Role can optionally be added. In the child element Value, the code contains a standardized error code such as "VersionMismatch", "MustUnderstand" or "DataEncodingUnknown". In addition, any deeply nested subcode elements can be inserted. With the standardized values ​​for the value element, the errors that have occurred can be classified at the top level. These errors can be remedied using



The subcode hierarchy defined by the user can be classified more finely. The values ​​of all five standardized error codes and their meanings are summarized in Table 2.1 below. SOAP error codes

Brief description


The recipient expects messages in a different SOAP version than the sender sent


A SOAP header cannot be processed by the SOAP node, although the attribute mustUnderstand was set to true


SOAP header or SOAP body use coding rules that are not supported by the SOAP node causing the error


The recipient cannot process the message because it is in an invalid format or does not contain the information it needs. This error is reported, for example, if the message does not contain the required authentication information. The error indicates that the same message should not be sent again without adjustment.


The recipient cannot process the message, but the error has nothing to do with the content of the message. Example: A database that is necessary for processing is not available for a short time. With this type of error, trying again at a later point in time can often lead to success.

Table 2.1: Predefined SOAP error codes

While the error code is intended for machine processing in code, a description of the cause of the error that can be understood by humans is broken down into the child elements Text and Reason. The description can even be available in several languages. In this case, each text element must have a unique attribute value for xml: lang. Should further details on the respective error situation be transmitted (e.g. a complete, server-side stack trace), the detail element offers space for this additional information. It can also include any application-specific XML fragments as a child element. An optional node element in the SOAP fault uses a URI to designate the SOAP node causing the error, while the role element can be used to indicate which function this node performed when the error occurred. If there is no node, it can be assumed that the error occurred at the receiver.

env: sender

Listing 2.5: SOAP Fault

Java Web Services with Apache Axis2


2 - Web Service Basics

rpc: BadArguments

Processing Error

Processing errors

Name does not match card number 999

Listing 2.5: SOAP Fault (cont.)


Exchange of messages

While SOAP was initially mainly viewed as a new RPC (Remote Procedure Call) protocol that brings greater interoperability due to the use of XML and HTTP, there is now a consensus that SOAP should be used both for the RPC scenario and for pure message exchange in the sense of a MOM (Message Oritented Middleware) is suitable. In order to differentiate between the two possible uses, the new term MEP (Message Exchange Pattern) was introduced in the SOAP 1.2 specification. In general, SOAP supports two forms of communication: conversational message exchange and remote procedure calls (RPC). While the request-response form in the RPC style is restricted to certain use cases, a much larger number of possible usage scenarios can be modeled using simple XML-based documents for mutual conversation. Each communication partner can send a message as a sender or receive a message as a recipient. A sender does not necessarily expect a reply message for its messages. The user data of the messages are transported in the body and must be understood by the respective recipient. With this dialog-oriented message exchange it is of course possible to simulate the request-response communication (analogous to the RPC style). The two messages, which are independent of one another, only need to be related by a clear reference (correlation ID) so that their relationship can be recognized. The correlation ID can e.g.



transmitted in the header of the message. This technology is also used in other MOMs such as JMS.

uuid: 093a2da1-q345-739r-ba5d-pqff98fe8j7d

Listing 2.7: Response with correlation ID

SOAP can also be used to implement remote method calls. To call such a method, at least the address, name and parameters of the remote method must be known. So that a SOAP message in RPC style can also be recognized as such, the format of an RPC message is precisely defined. Accordingly, the RPC must have a struct (data model similar to Struct in the programming language C or JavaBeans in Java; describes a complex data type with nested elements) as the only child element in the body of the SOAP message. The name of this struct must match the method or operation name Java Web Services with Apache Axis2


2 - Web Service Basics

chen and each parameter is stored as a direct child element of struct using its name.



Duke Master 123456789099999 2005-02

Listing 2.8: RPC call via SOAP

The SOAP message above is a message for a remote call to the chargeReservation method, which expects two parameters called reservation and creditCard. The chargeReservation element contains an attribute called encodingStyle, the value of which has been assigned a URL. This is a coding scheme that is part of the SOAP specification and regulates how the content of the corresponding element (in this case chargeReservation) is coded during shipping. This example also shows that a message for RPC calls can also contain SOAP headers for additional information. The structure of a response message for a remote method call is very similar to that of the request message. In this case, however, the name of the struct element consists of the called method name and the suffix “Response”. The output parameters of the method are in turn stored within this element. Since most methods return a maximum of one return value, this is also specially marked in a response message using the rpc: result element. This element has a value of type xs: QName and references another element in the same struct element. If the element rpc: result is missing, it can be assumed that the method does not return any.




m: status confirmed FT35ZBQ

Listing 2.9: Response to an RPC call via SOAP


Protocol binding

SOAP is an application protocol that can only be transmitted with the help of underlying transport protocols. The protocol binding defines how a SOAP message is transported from one SOAP node to the next node using the corresponding protocol. The SOAP 1.2 specification was created on the basis of XML information sets (XML infoset), so that the question of the specific syntax in which the infoset of a SOAP message is represented when binding the protocol must first be answered. In most cases, the XML 1.0 syntax is selected for this, so that a SOAP message must first be converted into a well-formed XML document before it can be sent via a transport protocol. However, any other suitable format could also be used. In addition, the protocol binding includes a mechanism to support properties that are required by SOAP applications. Message correlation, reliable delivery or encryption can be cited as examples of such properties. These properties are mostly related to the form of the message exchange. When using UDP, the message correlation must be implemented completely differently than with HTTP, in which the correlation is derived directly from the request-response assignment of the underlying protocol.

Java Web Services with Apache Axis2


2 - Web Service Basics

can be switched. In practice, only the HTTP binding plays a role, although the use of SMTP, TCP and JMS as transport protocols are also occasionally used. In the following, however, only the HTTP binding is presented. The HTTP binding uses the "SOAP Web Method Feature" to enable applications to select a so-called web method (currently only GET or POST). In addition, it supports two different forms of message exchange: 쮿

Use of the HTTP GET method for requests to the service and sending a SOAP message in the body of the HTTP response (SOAP Response Message Exchange Pattern)


Use of the HTTP POST method for sending SOAP messages to the service in the body of an HTTP request and sending a SOAP message in the body of the HTTP response (SOAP Request-Response Message Exchange Pattern)

In the first form, a normal HTTP request is sent via GET. All parameters for the requests are encoded in the requested URL. In addition, it is specified in the Accept header that a SOAP message is expected as the result. GET / HTTP / 1.1 Host: Accept: text / html; q = 0.5, application / soap + xml Listing 2.10: HTTP GET request

The associated response contains a SOAP message as a response in the body. HTTP / 1.1 200 OK Content-Type: application / soap + xml; charset = "utf-8" Content-Length: nnnn



Listing 2.11: SOAP response for the HTTP GET request

This form of message exchange should be used in scenarios in which information is requested from the service. If, on the other hand, the request triggers an operation that manipulates data, then a message exchange via HTTP-POST makes more sense. In this case, both communication partners can use any XML data



or replace RPC. The following example shows a complete HTTP POST request with one of the SOAP messages shown above. In this case, the HTTP response cannot be distinguished from that of a GET request. POST / Reservations HTTP / 1.1 Host: Content-Type: application / soap + xml; charset = "utf-8" Content-Length: nnnn



Duke Master 123456789099999 2005-02

Listing 2.12: SOAP request via HTTP POST


SOAP 1.2 vs. SOAP 1.1

All previous descriptions are based on the current SOAP 1.2 specification. In this version, many inaccuracies have been eliminated compared to the previous version. However, SOAP 1.1 is still more widespread in practice, so this section briefly lists the differences between the two versions. SOAP 1.1 is defined in a single document, while the specification of SOAP 1.2 is divided into three documents. In addition to an introduction (primer), the first part describes the structure and processing model of SOAP messages as well as the

Java Web Services with Apache Axis2


2 - Web Service Basics

Framework for protocol bindings. The second part, on the other hand, focuses on optional functionalities that SOAP implementations can, but do not have to support. This includes serialization rules for sending SOAP messages via HTTP or the implementation of RPC calls using SOAP. In contrast to SOAP 1.1, the description of the message structure in SOAP 1.2 is no longer based on concrete syntax (XML 1.0 document) but on an abstract model (XML Infoset). This makes it possible to formulate SOAP messages in any syntax (e.g. also in binary format) if this is more suitable for the transport protocol used.

SOAP syntax SOAP 1.2 is stricter than its predecessor in many respects: While it was still possible in version 1.1 to accommodate further child elements in the envelope after the body, this is strictly forbidden in the new version. It should also be noted that the encodingStyle attribute can no longer be accommodated in every element of a SOAP message as it was originally. This attribute is no longer permitted in the envelope. Instead, SOAP 1.2 defines special elements in which the encodingStyle attribute can be used. This specification of the specification was urgently needed because a number of fuzzy formulations in SOAP 1.1 led to numerous interoperability problems. When using SOAP 1.1 it was common to use the attribute values ​​0 and 1 for mustUnderstand. In SOAP 1.2 messages, however, the logical expressions true and false are recommended. The actor attribute is replaced by the new role attribute without changing the semantics. The attribute called relay can now be used to determine whether a SOAP header should be forwarded if it has not been processed.

Fault With SOAP 1.2, the new error code DataEncodingUnknown is introduced. Furthermore, the error codes client and server are now called sender and receiver, to emphasize that SOAP is not a special RPC protocol, but is designed for general message exchange. The element names faultcode and faultstring have been renamed to Code and Reason. To improve the readability of SOAP faults, there are now hierarchical SOAP faults. The original dot notation, which made errors in SOAP 1.1 more precise, has now given way to a formulation that is typical of XML. For RPC, two standard subcodes are also defined in SOAP 1.2: 쮿

rpc: ProcedureNotPresent: The called method does not exist.


rpc: BadArguments: Parameters were passed to a method either incompletely or incorrectly.

Listing 2.13 compares SOAP fault in 1.1 and 1.2.



SOAP 1.1:

soapenv: Server.generalException No such operation

SOAP 1.2:

soapenv: server


No such operation

Listing 2.13: Comparison of a fault in SOAP 1.1 and SOAP 1.2

HTTP binding In SOAP 1.2, the relationships between SOAP, MIME and HTTP are more clearly defined. Since XML is now used in many areas of application, a new convention with "+ xml" was established as a suffix for MIME types to express that these are XML documents that, however, require special processing. SOAP 1.1 still uses the MIME type application / xml or text / xml. This means that it is not possible to differentiate between a SOAP message and any XML document. Thanks to the new convention, SOAP 1.2 messages now have the MIME type application / soap + xml so that they can be clearly identified as SOAP messages. Another change affects the SOAPAction HTTP header.While it is still a mandatory field in SOAP 1.1, it was declared as optional in SOAP 1.2. Rather, this information should be specified as an action parameter in MIME type. SOAP 1.1: Content-Type: text / xml SOAPAction: “” SOAP 1.2: Content-Type: application / soap + xml; action = http: // Listing 2.14: MIME type for SOAP 1.1 and SOAP 1.2 messages

While in SOAP 1.1 the HTTP status code 500 (Internal Server Error) is returned in the event of an error, SOAP 1.2 replies with a normal message and the HTTP status code 200 (OK). The SOAP-specific error information can only be found in the message itself and no longer in the HTTP header. This is intended to clarify the separation between the transport and application protocol.

Java Web Services with Apache Axis2


2 - Web Service Basics



In addition to SOAP, WSDL represents the second important basis for web service applications. WSDL stands for Web Services Description Language and it is a language that can be used to describe web services in a standardized way. On the one hand, the description contains the abstract interface of the service, i.e. all operations and the messages and data types to be sent. On the other hand, WSDL can also be used to describe the way in which a specific implementation of this interface or this service can be communicated and the address at which a service can be reached. A WSDL document thus defines a contract between the service provider and the user. The basic idea is that a WSDL document contains all the information necessary to call the service. If this is observed, the creation of client applications can be automated. Various code generators make use of this, which, based on a WSDL description, generate program code for client-side stub or proxy classes. In this context, WSDL is very similar to IDLs (Interface Definition Language), as they are known from other technologies such as CORBA or COM. The difference with WSDL, however, is that these interface descriptions are written in XML and are therefore potentially better interoperable.

Figure 2.3: Role of WSDL documents in web service applications

If advanced web service technologies are to be used, such as WS-Security for sending encrypted or digitally signed messages, the use of this feature can no longer be represented with WSDL alone. Of course, this means that code generators also fail and cannot generate program code for such functionalities. In such cases, however, extension mechanisms can be used, for example by using special extension elements or by linking to a policy in accordance with WS-Policy.




MEPs - Message Exchange Patterns

Web service operations are defined by the messages that have to be sent between the service client and the service provider. For example, a hotel's web service could offer a room reservation operation. In order to carry out the operation successfully, the following scenario would be conceivable: First, a message with the reservation data must be sent to the service, in response to which the service sends a response message containing either a reservation confirmation or a negative response. From the point of view of the service, the operation consists of an incoming message (IN) followed by an outgoing message (OUT). This scenario is certainly the most widespread and is referred to as IN-OUT or request-response. Another very common scenario is the one-way operation, in which only a message is sent to the service, but the service does not return a response message (IN-only). In addition to these very common cases, any message exchange pattern is in principle conceivable. For example, a service could send a message of its own accord that was not triggered by a message received from a client immediately before, but by another event (notification or OUT-only). In addition, it is by no means absolutely necessary that an operation always consists of either one or two messages. Theoretically it is possible to define very complex operations for which the sending of a large number of messages is necessary. The technical term for message exchange pattern is MEP (Message Exchange Pattern). WSDL 1.1 supports four different MEPs: 쮿

One-way: The service receives a message.


Request-Response: The service receives a message and then sends a message back.


Solicit-Response: The service sends a message and then receives a message back.


Notification: The service sends a message.

A widespread misunderstanding is that request-response and solicit-response operations are automatically synchronous and therefore the programming models and communication protocols that can be used to implement these operations must also be blocking and synchronous. However, this is not the case. Both MEPs can also be implemented using protocols such as SMTP, and both blocking and non-blocking asynchronous calls can be used in programming. WSDL does not even request that the response message be sent to the same communication partner from which the request message was received. WSDL 2.0 is more open and in principle supports any MEPs, whereby the eight supposedly most common ones are already predefined. For these predefined MEPs, WSDL 2.0 also defines unique URIs with which the MEPs can be identified. Everyone is free to define their own MEPs based on this.

Java Web Services with Apache Axis2


2 - Web Service Basics

An obvious difference to the MEPs of WSDL 1.1 is the more flexible handling of error cases. Three cases are distinguished in the so-called Fault Propagation Rules: 쮿

No Fault: No error messages are sent.


Fault Replaces Message: Every message from the MEP, except the first, can be replaced by an error message in the same direction.


Message Triggers Fault: Every message from the MEP can trigger an error message in the opposite direction

Table 2.2 shows how MEPs and the handling of errors are related. With an in-only operation, only one message is ever sent, even if its processing causes an error. This is then just not reported. A robust-in-only operation also consists of a single message, but there is an exception in the case of an error: If an error occurs (and only then), a message can also be returned by Service. An in-out operation always consists of two messages; the second can be replaced by an error message if necessary. Finally, in-opt-out means that sending a reply message is optional, should an error occur, but this will in any case be reported with a corresponding message. MEP

Fault Propagation Rule

No fault

Message Triggers Fault

Fault Replaces Message

Message Triggers Fault

No fault

Message Triggers Fault

Fault Replaces Message

Message Triggers Fault

Table 2.2: MEPs and error handling according to WSDL 2.0 specification

2.2.2 WSDL 1.1 The WSDL 1.1 specification dates from 2001 and was still up to date at the time this book was published. However, it is not an official standard, just a so-called W3C grade. WSDL 1.1 has been criticized from the start for its technical shortcomings and stumbling blocks and has also been the cause of numerous interoperability problems in the past. For this reason, a successor specification called WSDL 2.0 has been worked on since 2002, but it has still not been completed. At least an end is in sight and it is to be hoped that the standardization of WSDL 2.0 will be completed in the course of 2007. The fact is, however, that despite all the problems and shortcomings, developers cannot avoid WSDL 1.1 in the meantime. Even after saying goodbye to