Apache CXF Web Service Development

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Tip

Downloading the example code for the book

Visit http://www.packtpub.com/files/code/5401_Code.zip to directly download the example code.

The downloadable files contain instructions on how to use them.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration, and help us to improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata added to any list of existing errata. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

Piracy

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or web site name immediately so that we can pursue a remedy.

Please contact us at <[email protected]> with a link to the suspected pirated material.

We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions

You can contact us at <[email protected]> if you are having a problem with any aspect of the book, and we will do our best to address it.

Chapter 1. Getting Familiar with CXF

We often require real world systems and applications to integrate with each other. Application integration is one of the critical areas that you need to focus on during application development, if your application involves integrating with third party or external systems. Alternatively, depending on your requirements, you may want other systems to access your application. Let's take an example of a credit card company providing services to guarantee payments made by consumers. These services are available over the Web, and consumers or applications, such as an online shopping application, or an airline firm that accepts credit cards as payment for its services, uses the credit card payment service for a consumer's payments. Since the credit card services can be accessed by any application client such as a web browser or a WAP (Wireless Application Protocol) enabled phone, and developed using any programming language, there is a need for a standard-based communication where the services offered can be used by any application, irrespective of any underlying technology. This is where web services come into play, and to simplify the design and development of web services, you have the option of using various web service frameworks. Apache CXF is one such leading standard-based web services framework whose goal is to simplify web services development.

In order to get started with the CXF framework, you first need to understand the concepts behind web services, the technology, and the standards that make up web service and features provided by the CXF framework. This chapter will cover these core concepts.

Specifically, in this chapter we will cover the following topics:

The core technology standards and concepts behind web services

Approaches for web services development

Overview of Apache CXF framework

Features provided by Apache CXF framework

Setting up Apache CXF environment

Web service technology standards

Before you look at the concept behind web services you need to understand the core technology standards that make up web services. Covering all the concepts and standards associated with web services is a vast topic in itself. In this chapter we attempt to cover the relevant web service standards and information used in the context of this book to get you acquainted with the technologies for developing web services using CXF. Some of the concepts will be explained in greater detail during the course of this book.

XML

XML stands for Extensible Markup Language. XML is a markup language that specifies or describes the format of the data to be exchanged between two parties. The data is significantly structured as tags or elements in a hierarchical order. A user can create his/her own tag to represent structured information. XML has become the de facto standard for representing structured information. Some of the important standard technologies associated with an XML document are listed below:

XML namespace—an XML namespace is a standard for providing uniquely named elements and attributes in an XML document. The XML namespace concept is similar to package definitions in Java, which provide conflict resolution of class names based on package declarations. A namespace is declared using the reserved XML attribute xmlns, the value of which must be a URI (Uniform Resource Identifier) reference, for example, xmlns=http://www.w3.org/1999/xhtml or using a prefix xmlns:xhtml=http://www.w3.org/1999/xhtml.

XML schema—XML schema provides a means of defining the structure, content, and semantics of XML documents. The XML Schema data model includes the vocabulary (element and attribute names), the content model (relationships and structure), and data types. An example of XML Schema describing address information is provided below:

xmlns:xs=http://www.w3.org/2001/XMLSchema>

address type=Address/>

Address>

  addressLine1 type=xs:string/>

  addressLine2 type=xs:string/>

  city type=xs:string/>

  state type=xs:string/>

  country type=xs:string/>

In the above example, xs represents the namespace of the XML Schema. The address represents an element whose type is Address. The Addresstype in turn is represented as complexType (similar to a Java bean Address class which stores address information), which is comprised of elements addressLine1, addressLine2, city, state, and country with data type as string. The code listing below provides a valid Address XML document based on the above Address XML schema. The Address XML Schema provides validation for the following XML document:

  xsi:noNamespaceSchemaLocation=address.xsd>

  1501 ACity

  UCity

  SFO

  CA

  US

SOAP (Simple Object Access Protocol)

SOAP is a protocol for exchanging XML-based messages over a network, typically using HTTP protocol. The SOAP message format is comprised of a SOAP Envelope which encloses all request information. The SOAP Envelope, in turn, is then made up of optional headers and a body. The headers optionally contain context related information, such as security or transaction, while the body contains actual payload or application data.

The following listing provides a sample SOAP message format containing address information:

1.0?>

http://schemas.xmlsoap.org/soap/envelope/

xmlns:ns1=http://apress.com/beginjava6/address

xmlns:xsd=http://www.w3.org/2001/XMLSchema>

1501ACity

UCity

SFO

CA

US

WSDL (Web Services Description language)

WSDL is a standard-based XML language used to describe web services. Under WSDL, a web service is described as a set of communication endpoints that are capable of exchanging messages. These communication endpoints are called ports.

An endpoint is comprised of two parts:

The first part is the abstract definitions of operations (similar to methods in Java) provided by the services and messages (input and output parameter types for methods) which are needed to invoke the service. The set of abstract operation definitions is referred to as port type.

The second part is the concrete binding of those abstract definitions of operations to concrete network protocol, where the service is located, and message format for the service.

The WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. Typically, the WSDL files would be created using the tool provided by the web service framework. The following block of code shows a listing of Address Verification WSDL, which uses the Address XML schema. Please refer to the inline comments for an explanation of the elements in the below WSDL file:

AddressVerifyProcessImplService targetNamespace=http://order.demo/ xmlns:ns1=http://schemas.xmlsoap.org/soap/http xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/ xmlns:tns=http://order.demo/ xmlns:wsdl=http://schemas.xmlsoap.org/wsdl/ xmlns:xsd=http://www.w3.org/2001/XMLSchema>

unqualified elementFormDefault=unqualified targetNamespace=http://order.demo/ xmlns:tns=http://order.demo/ xmlns:xs=http://www.w3.org/2001/XMLSchema>

Address type=tns:address />

verifyAddress type=tns:verifyAddress />

verifyAddressResponse type=tns:verifyAddressResponse />

verifyAddress>

0 name=arg0 type=tns:address />

address>

0 name=addressLine1 type=xs:string />

0 name=addressLine2 type=xs:string />

0 name=city type=xs:string />

0 name=country type=xs:string />

0 name=state type=xs:string />

verifyAddressResponse>

0 name=return type=xs:string />

  verifyAddressResponse>

    tns:verifyAddressResponse name=parameters>

  verifyAddress>

    tns:verifyAddress name=parameters>

  AddressVerifyProcess>

    verifyAddress>

      tns:verifyAddress name=verifyAddress>

      tns:verifyAddressResponse name=verifyAddressResponse>

  AddressVerifyProcessImplServiceSoapBinding type=tns:AddressVerifyProcess>

    document transport=http://schemas.xmlsoap.org/soap/http />

    verifyAddress>

      style=document />

      verifyAddress>

        literal />

      verifyAddressResponse>

        literal />

  AddressVerifyProcessImplService>

  tns:AddressVerifyProcessImplServiceSoapBinding name=AddressVerifyProcessImplPort>

      http://localhost:9000/AddressVerifyProcess />

Note

In Chapter 8 you will look at how to use the various CXF tools for web services development and format of WSDL files in detail.

REST (Representational State Transfer)

REST (Representational State Transfer) is neither a technology nor a standard; it's an architectural style—a set of guidelines for exposing resources over the Web. The REST architecture style is related to a resource, which is a representation identified by a Uniform Resource Indicator (URI), for example, http://cxf.soaweb.co.in/mybook. The resource can be any piece of information such as a book, order, customer, employee, and so on. The client queries or updates the resource through the URI and, therefore, influences a state change in its representation. All resources share a uniform interface for the transfer of state between client and resource.

The World Wide Web is a classic example built on the REST architecture style. As implemented on the World Wide Web, URIs identify the resources (http://amazon.com/mybook), and HTTP is the protocol by which resources are accessed. HTTP provides a uniform interface and set of methods to manipulate the resource. A client program, like a web browser, can access, update, add, or remove a Web resource through URI using various HTTP methods, like GET and POST, thereby changing its representational state.

Note

In Chapter 6 and 7 you will look at the REST concepts in detail and how to develop web services using the REST architecture style (also termed RESTful Web Services).

Service Registry

Service Registry provides a mechanism to look up web services. Traditionally, there was UDDI specification that defined the standards on registering and discovering a web service, but it lacked enterprise-wide adoption. Enterprises started shipping their own version of Service Registry, providing enterprise capabilities like service versioning, service classifications, and life cycle management.

Introducing web services

There are many different definitions available for a web service. The World Wide Web Consortium (W3C) defines a web service as follows:

A Web service is a software system identified by a URI whose public interfaces and bindings are defined and described using XML (specifically WSDL). Its definition can be discovered by other software systems. These systems may then interact with the web service in a manner prescribed by its definition, using XML-based messages conveyed by Internet protocols.

Simply, put web service is a software component that provides a business function as a service over the web that can be accessed through a URL. Web services are next generation web applications, modules, or components that can be thought of as a service provided over the web. Traditionally, we had static HTML pages as web content, which evolved into more dynamic full featured web applications providing business functionality and rich GUI features to the end user. A web service component is one step ahead of this web paradigm and provides only business service, usually in the form of raw XML data that can be digested by virtually all client systems. The GUI and business functionality are well separated. A web service can be thought of as a self contained, self describing, modular application that can be published, located, and invoked across the web.

The greatest benefit that web services provide is interoperability. Web services can be ported on any platform and can be written in different programming languages. Similarly, the client accessing the web service can be an application written in a different language and running on a different platform than that of a service itself.

Approaches for web service development

Two of the most widely used approaches for developing web services are SOAP (Simple Object Access Protocol) and the REST (Representational State Transfer) architecture style. In depth details on developing SOAP-based web services are provided in Chapters 2-5, while Chapters 6 and 7 are dedicated to RESTful web service development.

A web service involves three types of roles—a service consumer, a service provider, and an optional service registry. The following diagram shows the interaction between the service provider, the service consumer, and the service registry:

The service providers furnish the services over the web and respond to web service requests. The service consumer consumes the services offered by the service provider. In SOAP-based web services, the service provider publishes the contract (WSDL file) of the service over the web where a consumer can access it directly or by looking up a service registry. The service consumer usually generates a web service client code from a WSDL file using the tools offered by the web service framework to interact with the web service. In the next chapter you will look at how to create web service clients from a WSDL file.

Note

In Chapter 8 you will look at how to use various CXF tools for web service development.

With RESTful Web Services there is no formal contract between the service provider and the service consumer. The service requestor needs to know the format of the message, for instance, XML or JSON (Java Script Object Notation), and operations supported by the service provider. The service provider exposes the set of operations using standard HTTP methods like GET or POST. The service requestor invokes one of the methods defined for the resources using the URI over the HTTP protocol.

The choice of adopting SOAP rather than REST depends on your application's requirements. If your requirement consists of transmitting and receiving simple XML messages, then you would probably go with RESTful Web Services. However, if your requirement consists of various contracts to be defined and negotiated between the provider and consumer such as using a WSDL (Web Service Description Language) file and adhering to various web services specifications (WS Specifications) such as web service security for enterprise adoption, then SOAP-based web services is the right option. If you are developing SOAP-based services, then you also need to be aware of SOAP communication styles.

Web service SOAP communication styles

The web service SOAP communication style plays a significant role in communicating SOAP XML messages between the service provider and the service consumer. There exist two types of SOAP message styles, Document and RPC. The SOAP message styles are defined in a WSDL document as SOAP binding. A SOAP binding can have either an encoded use or a literal use. Encoding as the term implies, the message would be encoded using some format, while literal specifies plain text messages without any encoding logic.

Document style, as the name suggests, deals with XML documents as payloads which adhere to well defined contracts, typically created using XML schema definitions. The XML schema format specifies the contract for business messages being exchanged between web service provider and consumer, which the consumers can call and adhere to. The XML schema defines the request and response message format between the service provider and the service consumer. Document literal style is the preferred way of web service communication for achieving interoperability.

RPC (Remote Procedure Call) style, on the other hand, indicates that the SOAP body contains an XML representation of a method. In order to serialize method parameters into the SOAP message so it can be deserialized back by any web service implementation, the SOAP specification defines a standard set of encoding rules. As RPC is traditionally used in conjunction with SOAP encoding rules, the combination is referred to as RPC/encoded. You also have an RPC/literal communication style model where you don't have any encoding formats, but the messages are still limited to RPC method-based communication, where messages can't be validated as they are not tied to any XML Schema definition. You should probably avoid developing RPC style web services as it has a lot of interoperability issues.

Note

There are lot of specifications designed for SOAP-based web services. These web service specifications are designed for interoperable protocols for Security, Reliable Messaging, Management, and Transactions in loosely coupled systems. The specifications are built on top of the core XML and SOAP standards.

Apache CXF

Apache CXF is an open source web service framework that provides an easy to use, standard-based programming model for developing web services. Web services can be implemented using different application protocols like SOAP, XML, JSON, RESTful HTTP, and support various transport protocols like HTTP or JMS (Java Message Service).

History of CXF

Exactly what does CXF stand for? Apache CXF is the product of two projects, Celtix and XFire, hence the name CXF. Celtix, an open source Java-based Enterprise Service Bus (ESB) project, is a product of ObjectWeb consortia that delivers open source middleware solutions. The project was sponsored by IONA. On the other hand, XFire, a Java-based SOAP framework, is an open source project from Codehaus. Both Celtix and XFire, while in their initial versions, had many things in common and therefore the developers of both projects decided to bring out the best of both worlds and planned a better 2.0 version of Celtix and XFire. The communities of both these projects entered incubation at the Apache Software foundation to develop version 2.0. It took about 20 months at the Apache incubator before CXF finally rolled out. CXF is now formally known as Apache CXF which concentrates on delivering an open source web service framework. The framework which had its first release as v2.0, is now evolved as v2.2, with bug fixes, and the addition of new features.

Why CXF?

Picking up a framework is always a challenging task. There are many web service frameworks available today. Historically, there was Axis 1 which evolved into Axis 2, providing better flexibility and enhanced support for web service standards. Other widely used web service frameworks are GlassFish Metro, Glue, JBossWS, and so on. Every web services framework aims to provide a robust infrastructure for the developer to conveniently build, deploy, and publish the web services. So which one is the better framework? That's a million dollar question!

We choose CXF rather than other web service frameworks as it supports all the leading web service standards and provides a simplified programming model for developing SOAP and RESTful-based web services, along with options for various other application protocols. CXF provides a flexible deployment model for implementing web services. More specifically, we choose CXF as it provides the following capabilities.

Support for web service standards

Web service standards define the norms of a web service implementation with respect to its interoperability. The standards ensure that a web service is accessed independently of the client platform.

The framework provides the following web service standards support:

Java API for XML Web Services (JAX-WS)

SOAP

Web Services Description Language (WSDL)

Message Transmission Optimization Mechanism (MTOM)

WS-Basic Profile

WS-Addressing

WS-Policy

WS-ReliableMessaging

WS-Security

One of the most important web services technologies is JAX-WS. JAX-WS is a specification designed to simplify the construction of primarily SOAP-based web services and web service clients in Java. JAX-WS also includes the Java Architecture for XML Binding (JAXB) and SOAP with Attachments API for Java (SAAJ).

JAXB offers data binding capabilities by providing a convenient way to map XML schema to a representation in Java code. The JAXB shields the conversion of XML schema messages in SOAP messages to Java code without having the developers see the XML and SOAP parsing. The JAXB specification defines the binding between Java and XML schema. SAAJ provides a standard way of dealing with XML attachments contained in a SOAP message. CXF provides support for a complete JAX-WS stack. We will look at how to use the JAX-WS standards while developing web services in the next chapter.

The WS-Addressing, WS-Policy, WS-ReliableMessaging, and WS-Security are all part of the web services specification aimed to bring in consistency in various areas of web services. For instance, WS-Security specification is about how integrity and confidentiality can be enforced on web services using a standard method.

The WS-I Basic Profile is a specification from the Web Services Interoperability industry consortium (WS-I), which provides a reasonable set of rules and guidelines that are best suited for achieving web services interoperability. The rules and specifications are applied to a WSDL file, as the said file serves as the contract between service provider and service consumer in SOAP-based web services. Adhering to WS-I basic profiles ensures that your services can interoperate between different platforms.

Support for POJO (Plain Old Java Object)

POJOs are Plain Old Java Objects that don't implement any infrastructure framework-specific interfaces such as JMS or EJB interfaces. Using the POJO programming model simplifies testing and keeps things simple. POJO makes it easier to integrate with other frameworks like Spring, which provides various services such as transactions, and conforms to POJO in a standardized way. Throughout the book we have used POJO to demonstrate the CXF capabilities. CXF implements the JAX-WS and JAX-RS (Java API for RESTful services) specification, which provides a set of annotations to convert POJOs as SOAP and RESTful web services.

Frontend programming APIs

CXF frontends are programming APIs that can be used to develop web services and web service clients. CXF supports two types of frontends, namely standard-based JAX-WS, and simple frontend. These CXF frontends provide simple to use APIs to expose POJOs as web services and create web service clients. In Chapter 3, we will look at how to use the frontend programming APIs for developing web services.

Tools support

CXF provides different tools for conversion between JavaBeans, web services, and WSDL. These tools assist developers in generating web service clients like Java and JavaScript from WSDL or generating a WSDL file from a service implementation. CXF provides support for Maven and Ant integration for build and dependency management. Some of the tools supported are as follows:

Java to web service

Java to WSDL

WSDL to Java

WSDL to JavaScript

WSDL to Service

WSDL to SOAP

WSDL to XML

WSDL Validator

XSD to WSDL

In