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 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
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 • <Prepared demo with non-annotated marshalling>
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: Annotated Class Demo • <Prepared demo with annotated marshalling>
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 the following ways: • Using a client JAR that contains the necessary Java classes and stubs to access the web service. • Using a WSDL-to-Java tool to automatically generate the necessary web service stubs from a published WSDL.
WSDL to Java: Code Generation • What is generated? • How do use what is generated? • Service client • Endpoint interface • JAXB annotated model classes
WSDL to Java: Code Generation IDE Demo
WSDL to Java CXF provides the wsdl2java tool to consume third-party SOAP services: • wsdl2Java
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 • When the generated stubs aren’t enough. • Need to apply security (WSS4J/Spring Security) • Need to apply addition in/out interceptors • <Spring integration of generated endpoint in Spring>
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 • 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