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
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 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 thread-safe.
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 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
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 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.annotation
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
• 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
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 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 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 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
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