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_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 standalone 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
Java and XML
The Marriage of XML and Java:
• XML is a data markup language.
– Used for long or short-term data storage.
– Useful for data transfer between vastly different architectures.
– Particularly useful for web service architectures.
• Java is an object-oriented programming language.
– Unmarshalls (reads) data from existing XML into Java data
objects.
– Performs manipulations on Java objects via services.
– Marshalls (writes) Java objects into a new XML representation.
Java and XML: Choices, choices….
The marriage of Java and XML has produced a large
family of technologies, strategies, and libraries:
•
•
•
•
•
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. Often used to stream XML for building DOM
trees or construct XML Object bindings.
• XML-to-Object Binding
– XML types and elements are bound to Java types and fields.
In practice, most solutions use some combination of these.
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
Although CXF handles the marshalling and unmarshalling
of serviced XML, 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);
// Then unmarshall the XML document into instances of
// those classes.
MyClass obj = (MyClass)
jaxb.createUnmarshaller().unmarshall(xml)
The Unmarshaller can accept XML input as a character
stream, a file, a DOM node, or several other input types.
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.
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 supplied listeners and a Schema for additional
validation.
• It can be used to generate an XML Schema from your
JAXB annotated classes.
JAXB: Non-annotated Class Demo
Demo
XML Output without JAXB Annotations
JAXB: Annotations
Although JAXB can bind almost any Java data object with
little or no annotations, annotations are typically
desirable, for example:
• They can 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,
etc.
JAXB: Common Annotations
JAXB defines many annotations to customize Java
XML data binding. Here are just a few:
•
•
•
•
@XmlRootElement
@XmlElement
@XmlAttribute
@XmlElementWrapper
• @XmlElementRef
• @XmlElementRefs
• @XmlTransient
These and more can be found in the following package:
• javax.xml.bind.annotation
• <insert link to docs or tutorial>
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.
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.
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.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 rich Spring integration, the Java Stack
recommends the CXF wsdl2java tool to consume
third-party SOAP services.
Maven Usage:
<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 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 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.
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