implementing webservices with camel and cxf in servicemix

Copyright © 2010 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved. 1 A Progress Software Company

A Progress Software Company

Creating and consuming web services with camel-cxf

Adrian Trenaman,March 3rd 2011

twitter : adrian_trenaman | LinkedIn: adrian.trenamanhttp://trenaman.blogspot.com


When you joined today’s session …

Audio is broadcast from your computer

Submit your questions via the Chat Window

Contact today’s Host

via the Chat Window

Submit your questions via the Chat Window

Contact today’s Host

via the Chat Window


Our Speaker – Adrian Trenaman

15 years IT consulting experience• IONA Technologies, Progress Software Corp,

FuseSource• Committer, Apache Karaf• SOA, ESB, Open Source, BPM, Web Services, CORBA, …

Solution focused: architecting, mentoring, speaking, engineering, doing…

PhD Artificial Intelligence• Dip. Business Development• BA Mod Computer Science

http://trenaman.blogspot.comhttp://slideshare.net/trenaman twitter: adrian_trenamanLinkedIn: adrian.trenaman

http://trenaman.blogspot.comhttp://slideshare.net/trenaman twitter: adrian_trenamanLinkedIn: adrian.trenaman


SOAP 101: it’s all about body and headers

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:cus="http://demo.fusesource.com/wsdl/CustomerService/">

<soapenv:Header/>

<soapenv:Body>

<cus:lookupCustomer>

<customerId>0123</customerId>

</cus:lookupCustomer>

</soapenv:Body>

</soapenv:Envelope>

Message can contain zero or more headers!

Message can contain zero or more headers!

Body can contain a list of elements (RPC-literal) or a single element (Doc-literal / Wrapped Doc-literal)

Body can contain a list of elements (RPC-literal) or a single element (Doc-literal / Wrapped Doc-literal)

Key idea: the camel-cxf component lets you easily manipulate, route and transform the content of your SOAP messages.

Key idea: the camel-cxf component lets you easily manipulate, route and transform the content of your SOAP messages.


The goal – deploy / consume web services in with Camel

Show how to use the camel-cxf component to produce and consume SOAP messages

Some motivating use cases: • Trigger an integration flow from an incoming SOAP message, and provide

a SOAP response when it’s complete.– i.e. Implement a web service interface using a camel route.– Remember: there’s nothing wrong implementing a web service using plain-

old-java-code! See the first webinar for more!• Route XML from incoming SOAP/HTTP calls to XML/JMS.• Invoke on a web service from within an integration flow• Apply elegant Camel EIPs such as retry, error handling and throttling to a

web service endpoint.


Agenda: implementing web services with CXF and ServiceMix

A look at the options available to you…• POJO-based approach: you work with JAX-B objects.• Payload-based approach: you work with raw XML payload

– No code generation required!• Provider-based approach: SAXSource, DOMSource or StreamSource

Refresh on key techniques from first CXF webinar: • Code generation: WSDL, XSD -> JAX-WS, JAX-B• OSGi bundle-based packaging & deployment

New techniques using Camel: • Define camel-cxf endpoints for POJO, Payload and Provider

approaches.• How to work with the different payload types.

Useful references for your future work.


You will be spoilt for choice.

Apache ServiceMix thrives on innovation and experimentation.• As a result, there’s many different techniques you can use to implement

flows with camel-cxf.

My recommendations:• If you want to transform and route SOAP traffic with little marshalling

overhead, then prefer Payload mode.– If large files, consider using camel-cxf with a SAXSource Provider!

• If you want to route SOAP traffic but perform intensive Java manipulation of message content, then use POJO mode.


Sit back, relax, enjoy and ask questions.

Sample code will be shared at the end of the webinar!

We’ll cover a lot – ask questions as we go.

This session is being recorded• You can re-view later if you miss something.


Using camel-cxf in POJO mode


What does POJO format really mean?

POJO format is the default format for camel-cxf.

The SOAP body is marshaled into a list of Java objects• One Java object for each part of the SOAP body, or each parameter of a

wrapped doc-literal request.• Appropriate Java classes are code-generated in advance using

JAX-WS/JAX-B.• The body of the Camel message contains a MessageContentsList object

Any SOAP headers are transmitted as a header in the exchange’s in message.


Ticklist – creating a route using camel-cxf pojo

Generate JAX-WS code from WSDL• … using the Maven cxf-codegen-plugin

Configure camel-cxf endpoints and integration framework using Spring Framework.• … using appropriate conventions so ServiceMix can locate your

Spring contexts.

Package your service• Here, use the maven-bundle-plugin for OSGi bundles and

deploy into Fuse ESB

Make sure you have appropriate TypeConverters available• Test your route!


Using the cxf-codegen-plugin

Maven-friendly location for generated code!

Maven-friendly location for generated code!

Location of WSDL fileLocation of WSDL file


Configuring a service implementation using Spring Framework

Here’s where we define the camel-cxf endpoint, and tie it to your SEI.

Here’s where we define the camel-cxf endpoint, and tie it to your SEI.

Useful technique: header-based routing by operationName to custom Processors

Useful technique: header-based routing by operationName to custom Processors


Accessing the message parts as POJOs

Use Camel Processors to get access to the CXF messages.

The body of a Camel CXF POJO message contains a MessageContentList.• For a request, this contains the In parameters, and InOut/Out parameter

holders in the order they are defined in the WSDL message.• For a response, this contains the return value (if any), followed by the

InOut/Out parameter holders in the order they are defined in the WSDL message.

Note: you need to know what to expect in the MCL, and in what order!


Accessing the message parts as POJOs (cont’)

For example, consider the getCustomerStatus operation:• 1 x In parameter: customerId• 2 x Out parameters: status, statusMessage.



… the generated JAX-WS method looks like this:



… the corresponding payload will look like this: • Request MCL =

{String customerId, Holder<String> status, Holder<String> statusMsg}

• ResponseMCL = {Holder<String> status, Holder<String> statusMsg}

You can access the payload as a MessageContentsList object or as an Object[] see next slide for example)



Example of accessing the data (see GetCustomerProcessor):


Packaging – OSGi bundles

The Spring configuration should be placed in the META-INF/spring directory in src/main/resources.

For OSGi bundling: • Usually keep implementation

packages private; however, default configuration will work fine.

• See Over!


Packaging – OSGi bundles (cont’) – maven-bundle-plugin

Configuration of maven-bundle-plugin is minimal!• Don’t forget to set <packaging>bundle</packaging> to

activate this.


Demo – deploy the POJO route!


Using the PAYLOAD format with camel-cxf


What is the ‘PAYLOAD’ format?

In PAYLOAD format the body of the Camel message contains a CxfPayload object.• getHeaders() returns a list of SoapHeader.• getBody() returns a list of org.w3c.dom.Element.

Allows you get to access body as a DOM Element• No need for generated code• Benefit: can save on the overhead of marshaling to and from JAX-B

objects.• Drawback: uses a DOM model; may not be good for large files.

Suits situations where you wish to manipulate raw XML payload; examples:• Route from SOAP/HTTP to JMS• Generate response using templates like Velocity


Ticklist – creating a route using camel-cxf payload


Spring contexts.





Spring configuration for PAYLOAD format

You must set the dataFormat to PAYLOAD in the URI.

You must set the dataFormat to PAYLOAD in the URI.

No need for generated code! Just specify the WSDL location.

No need for generated code! Just specify the WSDL location.


SOAP/HTTP to JMS

Very popular use-case!• Place incoming payload onto a reliable JMS queue for offline processing,

and return an acknowledgment response.• Note usage of inOut and jmsMessageType when sending to the

queue!• Note creation of response from inline XML – neat!


Using XPath templates for request-response traffic

Nice idea: inject values into a pre-packaged XML template.• Use XPath to extract useful data from the request and store as a header.• Inject response values into XML!

Nice use of the velocity component to generate response!

Nice use of the velocity component to generate response!

Processor does the work of getting the customer status, maybe from a DB or backend system.

Processor does the work of getting the customer status, maybe from a DB or backend system.


Using headers to transmit request information…

A custom Processor can retrieve the customerId, and store response information as headers on the message.


Creating a response using Velocity

Headers from the Camel Exchange are injected easily into a Velocity template using ${headers.<headerName>} place-holders.• Example velocity template

(src/main/resources/getCustomerStatusResponse.vm):


Payload conversion issues.

Working with CxfPayload is sometimes wearisome.• How do you convert a String to a CxfPayload?

– Velocity component produces a String, but camel-cxf needs a CxfPayload object in the response

• How do you convert a CxfPayload to a String? – Want to place a JMS TextMessage on the queue; however, no conversion

available from a CxfPayload to a String • How do you convert a CxfPayload to an org.w3c.dom.Node?

– Want to run an X-Path expression on the payload, but X-Path expects a Node

Without the right conversions in place, you may see: • Class cast exceptions in the route.• Empty SOAP body on the return message.


Payload conversion is common in Camel routes!

Recall: Camel doesn’t enforce a canonical format.• It is the endpoint at the start of the route that determines what’s in the

message body.• An InputStream, a String, a Node, a CxfPayload, …

Camel will lazily convert from one format to another when needed.• Popular conversions are provided within Camel! • You can write your own converters easily (see over)

– Also see http://camel.apache.org/type-converter.html

Our example includes some custom converters.• … I’ll contribute these to the community. Honest!


Sample converter

Note: @Converter annotation used to allow automatic registration of converters with Camel runtime.

Note: @Converter annotation used to allow automatic registration of converters with Camel runtime.


Demo – deploy the payload route!


Hidden Gem: Camel CXF and the JAX-WS Provider interface.


CxfPayload is great, but…

CxfPayload always creates DOM elements – this might be inappropriate for large XML payload.• If you want to access your payload as a SAXSource or StreamSource, use

CXF’s support for JAX-WS Providers.

JAX-WS Providers offer an elegant alternative accessing SOAP payload without marshaling to Java • See http://cxf.apache.org/docs/provider-services.html


Ticklist – creating a route using camel-cxf JAX-WS Provider

Create a Provider<?> implementation class.• Replacing ‘?’ with SAXSource, DOMSource or StreamSource


Spring contexts.





The Provider class

Note: the invoke() method is a dummy placeholder – only it’s signature is used when registering your service endpoint!

Note: the invoke() method is a dummy placeholder – only it’s signature is used when registering your service endpoint!

We define a provider to receive the SOAP body (payload) as a SAXSource

We define a provider to receive the SOAP body (payload) as a SAXSource


Spring configuration

Now your routes can access the message body as a SAXSource

Configure the cxfEndpoint, using your provider as the serviceClass.Configure the cxfEndpoint, using your provider as the serviceClass.


Summing up!


Summing up

Camel gives you a number of options on how to implement and consume and provide SOAP web services with CXF• POJO: Great for when you want to access the payload as Java objects• PAYLOAD: Great for when you want access to the SOAP Body for

transformation and routing purposes.• PROVIDER: Great for when you want to to access SOAP payload as a

DOMSource, SAXSource or StreamSource.

Your choice of payload should be compatible with other EIPs & components in your route!

All make use of Spring or OSGi Blueprint declarative configuration, and deploy easily into Fuse ESB.


Next Webinars

See http://fusesource.com/resources/video-archived-webinars/

April 7th 2011: • How to Secure CXF Web Services with SSL/TLS and WS-Security

See you then!


Useful references

FuseSource – http://fusesource.com• http://fusesource.com/products/enterprise-cxf/#documentation • http://fusesource.com/products/enterprise-servicemix/#documentation

Maven – http://maven.apache.org• http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html • http://maven.apache.org/plugins/maven-war-plugin/

Bnd - http://www.aqute.biz/Code/Bnd

CXF – http://cxf.apache.org• http://cxf.apache.org/docs/maven-cxf-codegen-plugin-wsdl-to-java.html • http://camel.apache.org/cxf.html


Learn More at http://fusesource.com

implementing webservices with camel and cxf in servicemix

Technology