Web Services with Apache CXF

Part 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_Trai
ning
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 Binding

Modeling 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

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 Unmarshalling

CXF 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 classes
JAXBContext 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

JAXB: Marshalling

Marshalling objects into XML is just as

easy:
// Create a JAXB context for your Java data classes
JAXBContext 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

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

Demo
XML 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

JAXB: Common Annotations

JAXB defines many annotations to

customize Java XML data binding. Here
are
just a few:
@XmlRootElement
@XmlType
@XmlElement
@XmlAttribute
@XmlElementWrapper
These
and
more
can
be
found
in
the
following
@XmlElementRef
package:
@XmlElementRefs
javax.xml.bind.annotation
@XmlTransient

For usage information see the JAXB API

Documentation.

JAXB: Non-annotated Class Demo

Demo
XML 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 Binding

http://tech.lds.org/wiki/Web_Services_with_Apache_CXF_-_Part_2

Web Services with Apache CXF

WSDL to Java
Consuming 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

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

Demos
http://www.webservicex.net/geoipservice.asmx?wsdl

A Generated Web Service Client

A Generated Endpoint Interface
Generated 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.htm
l
)

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.
Dont need to tweak generated code
Dont 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 webservice 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 Java

http://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 arent enough.
Need to apply security (WSS4J/Spring Security)
Need to apply additional in/out interceptors

Stack namespace handler: <stackws: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 servers 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

Demo
Using 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