Web Services with Apache CXFPart 2: JAXB and WSDL to Java

Robert Thornton

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, and Web Application Development– Web Services, Part I: SOAP– A general familiarity with XML simple and complex

schema types.

Objectives

At the end of this presentation, the participant will be able to:• Understand the role of JAXB as a web service data binding

solution.• Model data entities using JAXB annotations.• Understand the purpose and usage of the CXF WSDL2Java tool.• Be able to use WSDL2Java to generate a client proxy in a stand-

alone Java application.• Be able to configure Spring to manage and consume a generated

WSDL2Java client proxy .

Web Services with Apache CXF

Java XML BindingModeling Web Service Messages with JAXB

Introduction

In all software applications and data management systems, languages are necessary to describe the data and perform instructions. A single language is rarely adequate in real-world applications, certainly not in the enterprise. Usually at least two languages are necessary:• A language to describe the data for storage or transfer.• A language to perform manipulations on that data.

XML

• XML is a language for describing data:– Platform agnostic.– Strongly typed (though use of XML Schema)– Useful for long or short-term data storage.– Useful for data transfer between vastly different

architectures.– Particularly useful to describe the operations and

messages passed to and from web services.

Java

• Java is a language for performing instructions:– Strongly typed.– Object-oriented.– Machine and operating system independent (through

its JVM).– Exceptionally useful for implementing software that

performs services.– Available on servers, desktops, mobile devices, cards,

nearly everywhere.

Java and XML

Bringing them together:• How do we instruct Java to read, process, and

write XML?• How do we keep the Java XML processing simple

and clean?• How do we make it maintainable long term?These are questions that many technologies have attempted to address.

Java and XML: Choices, choices….

As Java has matured, several strategies and APIs have developed around Java XML processing:

• DOM• StAX• JAXP• DOM4J• JAXB

• XML Beans• JDOM• XStream• and many more….

Java and XML: Overview

Most Java XML strategies fall into three spaces:• DOM (Document Object Model)– Entire document model is held in memory as nodes in a

document tree.

• Streaming– An event-based API for operating on each piece of the XML

document individually and in sequence.

• XML-to-Object Binding– XML types and elements are bound to Java types and fields.

In practice, most solutions use some combination of these. Web services typically use XML-to-Object binding.

JAXB: A Data Binding Solution

The JAXB API is the standard solution provided by the JDK for Java XML data binding:• Java classes are bound to XML types, elements, and attributes

through Java annotations.• A XML streaming event-based (StAX) parser is used to parse XML

documents and construct Java objects as well as to write Java objects back to XML.

• The XJC tool (included in the JDK) can generate JAXB annotated classes from an existing XML Schema.

• The Schemagen tool (also included in the JDK) can generate an XML schema from JAXB annotated classes.

JAXB and Web Services

As a data modeling API, JAXB is particularly useful to web services, because:• XML is the most common form of data transport.• Annotated Java classes can be made to represent XML schema

types.• JAXB APIs can unmarshall XML into Java data objects and back

again.• Fits into an RPC-style of service method invocation with POJO

parameters and results.* Note that the CXF web service framework automatically handles the marshalling and unmarshalling of XML data to and from JAXB annotated Java classes.

JAXB: Marshalling and UnmarshallingCXF handles the marshalling and unmarshalling of serviced XML, but it can be helpful to know how CXF does it.• A web service developer occasionally needs to

experiment with how JAXB annotations affect the parsing and rendering of XML.

• A web service developer often needs to debug issues that arise from data being marshalled or unmarshalled incorrectly.

• The JAXB Marshalling/Unmarshalling APIs can be used to apply additional validation or to generate a schema.

JAXB: Unmarshalling

JAXB makes unmarshalling from XML easy:

// Just create a JAXB context for your Java data classesJAXBContext jaxb = JAXBContext.newInstance(myClasses);

// Unmarshall the XML document to instances of those classes.Foo obj = (Foo) jaxb.createUnmarshaller().unmarshall(xml);

The Unmarshaller can accept XML input as a character stream, a file, a DOM node, or several other input types.• Can be supplied listeners and a schema for validation.• Note that the Unmarshaller is not guaranteed to be thread-safe.

JAXB: Marshalling

Marshalling objects into XML is just as easy:

// Create a JAXB context for your Java data classesJAXBContext jaxb = JAXBContext.newInstance(myClasses);

// Marshall your Java object hierarchy into an XML document.jaxb.createMarshaller().marshall(myObject, output);

The Marshaller can serialize the XML to a character stream, a file, a DOM node, or several other output types.• It can be supplied listeners and a Schema for validation.• Note that the Marshaller is not guaranteed to be thread-safe.

JAXB: The Context

Instances of the JAXBContext class effectively represent an “in-memory” schema of your data:• It is a registry of all the classes that can be bound to

XML types.• It is a factory for Marshaller and Unmarshaller instances.• It can be used to generate an XML Schema from your

JAXB annotated classes.• Because the JAXBContext is immutable, it is safe for use

as a singleton by multiple threads.

JAXB: Non-annotated Class Demo

DemoXML Output without JAXB Annotations

JAXB: Annotations

Annotations control many aspects of XML marshalling:• The @XmlRootElement annotation is required for classes that

represent an XML document root element. All other annotations are optional in most cases, but useful nonetheless:

• Other annotations tell JAXB whether to unmarshal a field into an attribute or an element.

• They can inform JAXB of ID fields, element order, and other schema constraints.

• They can be used to identify or customize schema types, element names, attribute names, element wrapping, and so forth.

• The @XmlTransient annotation can tell JAXB to ignore certain fields during marshalling .

JAXB: Common Annotations

JAXB defines many annotations to customize Java XML data binding. Here are just a few:• @XmlRootElement• @XmlType• @XmlElement• @XmlAttribute

• @XmlElementWrapper• @XmlElementRef• @XmlElementRefs• @XmlTransient

These and more can be found in the following package:• javax.xml.bind.annotationFor usage information see the JAXB API Documentation.

JAXB: Non-annotated Class Demo

DemoXML Output with JAXB Annotations

JAXB: Rules and Conventions

Some general rules about JAXB annotations:• Concrete classes must have a public default no-arg constructor.• Properties that reference interfaces must be annotated with one

or more @XmlElementRef annotations that identify the possible concrete types.

• Annotations may be placed on the fields or on the setters but not on both.

• By convention, annotating fields is preferable for simple POJOs.• Properties not bound to XML values must be annotated with

@XmlTransient.

Apache CXF: SOAP: Lab 1

Lab 1: JAXB Data Bindinghttp://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_2

Web Services with Apache CXF

WSDL to JavaConsuming 3rd Party Web Services

WSDL 2 Java

Third-party SOAP web services are typically consumed in one of two ways:• Using a client JAR prepared by the service provider.– Contains the necessary Java classes and stubs for accessing

the web service.

• Using a WSDL-to-Java tool.– Automatically generates the necessary Java classes and stubs

from a published web service descriptor, or WSDL.– Note that the WSDL is not the same as the service endpoint.

• An endpoint is where the web service accepts SOAP requests• A WSDL may be queried from the endpoint (e.g. by appending ?wsdl to

the enpoint URL.

WSDL to Java: Code Generation

What is generated by a WSDL to Java tool?• A service client.– Will extend javax.xml.ws.Service and/or be

annotated with javax.xml.ws.@WebServiceClient• One or more service endpoint interfaces.– Will have the @javax.jws.WebService annotation

• Model classes bound to any complex XML types used by the service.– Will have with JAXB annotations.

• An object factory is also generated to facilitate the creation generated stubs.

WSDL to Java: Code Generation

Demoshttp://www.webservicex.net/geoipservice.asmx?wsdl

A Generated Web Service ClientA Generated Endpoint InterfaceGenerated JAXB Model Classes

WSDL 2 Java: Code Generation

Client code generation is cool, but …

When do you use it?

WSDL to Java: Code Generation

Option #1: One-time generation• Run command-line tools and copy to project.– wsimport (JDK)

• http://download.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html)

– wsdl2java (CXF)• http://cxf.apache.org/docs/wsdl-to-java.html

• IDE Web Service Client Wizards

When to use?• Need to customize what is generated• Want to avoid dependence on build tools

WSDL to Java: Code Generation

Option #2: Build-time generation• Using Maven Plugins:– org.codehaus.mojo:jaxws-maven-plugin

• Uses the JDK wsimport tool

– org.apache.cxf:cxf-codegen-plugin• Uses the CXF wsdl2java tool

When to use?• Need to stay up-to-date with a changing WSDL.• Don’t need to tweak generated code• Don’t want to own or manage the generated source code.

WSDL to Java: Code Generation

Due to its integration with CXF, the Java Stack recommends the CXF wsdl2java tool if there is a need to generate web-service clients at build-time.

<plugin> <groupId>org.apache.cxf</groupId> <artifactId>cxf-codegen-plugin</artifactId> <executions>...</executions></plugin>

Maven execution:<execution> <id>wsdl2java</id> <phase>generate-sources</phase> <goals><goal>wsdl2java</goal></goals> <configuration> <wsdlOptions> <wsdlOption> <wsdl>${wsdlUrl}</wsdl> </wsdlOption> </wsdlOptions> </configuration></execution>

WSDL to Java: Lab 2

Lab 2: Using WSDL to Javahttp://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_2

WSDL to Java: Spring Integration

Managing the generated endpoint with Spring:• When the generated stubs aren’t enough.– Need to apply security (WSS4J/Spring Security)– Need to apply additional in/out interceptors

• Stack namespace handler: <stack-ws:consume/>– To simplify common security and configuration needs– http://code.lds.org/schema/spring/ws/stack-ws-1.1.xsd

• CXF namespace handler: <jaxws:client/>– For more advanced client configuration.

WSDL to Java: Spring Configuration

Attributes to <stack-ws:consume/>• service-class

– The bean name of the service endpoint interface.

• 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.

WSDL to Java: Spring Configuration

Example Usage:<stack-ws:consume service-class="org.lds.MyService" endpoint="http://www.lds.org/myservice"> <stack-ws:in-interceptors> <bean idref="customInInterceptor2"/> </stack-ws:in-interceptors> <stack-ws:out-interceptors> <bean idref="customOutInterceptor1"/> </stack-ws:out-interceptors></stack-ws:consume>

WSDL to Java: Spring Integration

DemoUsing an endpoint interface generated by WSDL to

Java in a Spring integration test.

Conclusion

• The standard Java APIs can be used to model your data for use by web services.

• The JDK, CXF, and the Java Stack provide code generation and configuration utilities to make it easier to consume third-party web services.

• For more information about JAXB and CXF, please visit the links on the following page.

Resources

On the web:• http://cxf.apache.org• Java 6 API Documentation• JDK 6 Programmer Guides• Java Stack Documentation