Web Services with Apache CXF Part 1: SOAP Web Services Robert Thornton

This is a training, NOT a presentation Please ask questions Notes This is a training, NOT a presentation Please ask questions This is being recorded https://tech.lds.org/wiki/Java_Stack_Training Prerequisites Maven Spring Web Application Development

Objectives At the end of this presentation, the participant will be able to: Describe the role of Apache CXF in building SOAP web services. Understand the basic characteristics and terminology of a SOAP web service. Describe the pros and cons of SOAP vs. REST. Use Apache CXF and Spring to produce a SOAP HTTP endpoint in a Java web application. Be able to consume a SOAP HTTP web service within an integration test. Be able to identify the purpose and components of a SOAP WSDL document.

What is Apache CXF and what does it provide? Apache CXF: What is it? What is Apache CXF and what does it provide? An open-source web services framework Support for web service standards and JSR APIs. Tooling and configuration for building and consuming web services using the JAX-WS and JAX-RS frontend APIs. Spring namespace handlers for integration with the Spring Application Framework. Originally the combination of two open-source projects, Celtix and Xfire and combined into one by the Apache Software Foundation, hence the name Apache CXF.

Apache CXF: A Robust Framework Apache CXF provides robust support for producing and consuming web services: JSR APIs: JAX-WS, JAX-RS, JSR-181 annotations, SAAJ WS-* specifications for web service interoperability. A variety of message transports, protocol bindings, data bindings, and formats. Flexible, lightweight deployment in a variety of web application containers or stand-alone. Tooling for code and WSDL generation and validation. Multiple language support. JSR Support: JAX-WS: Java API for XML-based (SOAP) Web Services JAX-RS: Java API for RESTful (HTTP) Web Services JSR-181 Web Service Metadata Annotations SAAJ: SOAP with Attachments API for Java Apache CXF supports the WS-* specifications for interoperability with web services produced using other frameworks, such as .NET. Basic Support: WS-I Basic Profile 1.1 Quality of Service: WS-Reliable Messaging Metadata: WS-Policy, WSDL 1.1 Security: WS-Security, WS-Security Policy, etc. Messaging Support: WS-Addressing, SOAP 1.1/1.2, MTOM (Message Transmission Optimization Mechanism) Apache CXF supports: Message Transports: HTTP, Servlet, JMS, SMTP, POP3, and many more. **(Transport = how messages are transmitted from server to client.) Protocol Bindings: SOAP, REST/HTTP, pure XML **(Protocol Binding = how the transport is bound to the web service protocol) Data Bindings: JAXB 2.x (Java XML Binding API), XMLBeans, and others **(Data Binding = how the data is bound to the service protocol) Formats: XML, JSON, and others **(Data Format = how the data is represented in the message) Additional binding and format support through an extensibility API.

Apache CXF: Help, I’m drowning! With all these features, how do I choose?

Apache CXF: Recommendations The Java Stack recommends the following two basic feature sets for using CXF to produce and consume web services in Java applications: Option #1: JAX-WS, using the SOAP protocol over HTTP transport with JAXB data binding. Option #2: JAX-RS using REST over HTTP with JAXB, XML, or JSON data binding. This training will focus on producing and consuming SOAP web services with JAX-WS. A future training session will cover JAX-RS.

Apache CXF: Still too many choices? Apache CXF allows JAX-WS with SOAP and JAX-RS (REST) to be used side by side. But which is right for my project?

SOAP vs. REST: An Overview Both SOAP and REST are front-end technologies. That is, their services are exposed within the view layer of an application. SOAP Supports a variety of transports (HTTP, JMS, etc.) Integrates with a variety of web service standards. Typically used to pass contractually structured data between applications. REST Simple point-to-point communication using well-established HTTP verbs, protocols, and standards. Often used to faciliate dynamic HTML page creation.

SOAP: Pros and Cons Pros: Agnostic to language, platform, and transport. Designed for distributed environments and applications. Richer, more mature, standards-based support and integration. Built-in error-handling (faults). Extensible through integration with other transports and data bindings. Cons: Heavier abstraction and steep learning curve. More verbose. Difficult to develop without tools.

REST: Pros and Cons Pros: Cons: Agnostic to language and platform. Conceptually simpler to understand and develop. Less reliance on tools Closer in design and philosophy to the web. Cons: Locked into the HTTP transport model. Cannot be scaled to non-HTTP communication models. Lack of standards support for security, policy, messaging, etc., making apps with richer requirements harder to develop. * For a more detailed comparison of SOAP and REST, see the following excellent article: http://ajaxonomy.com/2008/xml/web-services-part-1-soap-vs-rest or perform an internet search on “SOAP vs REST”.

Know your deployment environment and infrastructure. SOAP vs. REST: Summary Know your deployment environment and infrastructure. Will your service be distributed? Will communication need to pass through non-HTTP boundaries? Know your interoperability and scalability requirements. Who will be consuming your service? Will you need to support non-HTTP transports (e.g. JMS, SMTP, POP3) now or in the future?

Oh, I wish I were a little bar of … And now for a song…. ¯ Oh, I wish I were a little bar of … SOAP!

Essential Terminology: WSDL Web Service Namespace URI JAX-WS and SOAP Essential Terminology: WSDL Web Service Namespace URI Endpoint URL or Port Service Endpoint Interface (SEI) Operation Message Envelope

JAX-WS: Defining a Service Endpoint The JAX-WS specification uses Java annotations to define your web service endpoint. CXF processes these annotations to produce your WSDL The annotations can be used to customize many aspects of how your WSDL and web service schema are published.

@javax.jws.WebService @javax.jws.WebMethod @javax.jws.WebParam JAX-WS: Annotations @javax.jws.WebService Marks a Java interface as a Service Endpoint Interface. Marks a Java class as a web service endpoint implementation. @javax.jws.WebMethod Optional annotation for customizing a SOAP web service operation @javax.jws.WebParam Optional annotation for customizing the mapping of an individual parameter to a web service message part, or input parameter. @javax.jws.WebResult Optional annotation for customizing how SOAP treats the output of a web operation.

JAX-WS: More Annotations @javax.jws.soap.SOAPBinding Customizes the mapping of the web service onto the SOAP message protocol. Its use is optional as the default settings are the recommended values and will make your web service the most portable.

JAX-WS: Defining a Service Endpoint A Basic Example: package org.lds.training.cxf.labs.ws; import java.util.List; import javax.jws.*; // General web service annotations import javax.jws.soap.*; // SOAP-specific WS annotations @SOAPBinding( style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) @WebService( targetNamespace = "http://schema.lds.org/cxf-labs/user/v1.0") public interface UserService { @WebMethod(action = "CreateExample") public User getUser(@WebParam(name = "username") String username); }

Web Services on the Java Stack A Java Stack web service provider typically consists of the following Maven projects: A parent (POM) module An API (JAR) module This is where you should define your web service interface. A web application (WAR) module This is where you implement your web service functionality A QA module This is where your integration tests will consume your web service during development and testing. A deployment module

Lab 1: An Example SOAP Web Service Apache CXF: SOAP: Lab 1 Lab 1: An Example SOAP Web Service http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_1

<stack-ws:produce/> Namespace Handlers For Spring bean configuration, the Java Stack defines two namespace handlers for JAX-WS web services: <stack-ws:produce/> Used in the web application to configure the JAX-WS web service bean. <stack-ws:consume/> Used in a QA module or other application to configure a JAX-WS client proxy bean.

Configuring a Web Service Provider Attributes to <stack-ws:produce/> implementor The bean name of the endpoint implementation class secured Whether to secure the web service with LDS Account. address The endpoint address where the service will be published. authentication-manager-ref allows customization of the authentication manager

Configuring a Web Service Client Attributes to <stack-ws:consume/> service-class The bean name of the endpoint implementation class. endpoint The published endpoint service address. user, password, password-type For user authentication. Both plain text and digest passwords are supported. wam-authenticator, wam-cookie-resolver-ref Provides authentication through WAM ssl-trust-server Specifies whether the server’s SSL cert should be automatically trusted.

Lab 2: Producing a SOAP Web Service Apache CXF: SOAP: Lab 2 Lab 2: Producing a SOAP Web Service http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_1

Lab 3: Consuming a SOAP Web Service Apache CXF: SOAP: Lab 3 Lab 3: Consuming a SOAP Web Service http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_1

Resources On the web: http://cxf.apache.org http://www.w3.org/TR/soap/ http://en.wikipedia.org/wiki/Cxf http://en.wikipedia.org/wiki/SOAP http://ajaxonomy.com/2008/xml/web-services-part-1-soap-vs-rest In Print: Developing Web Services with Apache CXF and Axis 2, Kent Kai Iok Tong, TipTech Development, 2005-2010. ISBN: 978-0-557-25432-3