Thursday, December 17, 2015

SOAP Web Services using CXF/JiBX [JAX-WS]

SOAP Web Services - Architecture

Fig. 1 SOAP Web Services Architecture (SOAP - WSDL - UDDI)

Advantages of Apache CXF
Apache CXF, is currently the most widely used framework and preferred over Axis due to:

1. It separates the JAX-WS code from the core application code.
2. It is compliant with the Spring Framework.
3. It is more performant than all JAX-WS implementations.
4. It supports both JAX-WS and JAX-RS.
5. It is the most popular JAX-WS framework and is replacing all other implementations.   
6. It is relatively easy to use and generates lesser code with Eclipse support being available.

 [image publicly available at]

Fig. 2 CXF Architecture with all Components 
[Especially Note the 'Front-Ends' and 'Pluggable Data Bindings']

Advantages of JiBX
JiBX, unlike other binding frameworks provides two distinct features or advantages:

1. It generates an additional binding class, apart from the regular schema and this 'separates' the java code changes from the binding changes; which mean both can be changed independently of each other.
2. It optimizes the bytecode generated, and is more performant data binding mechanism by a factor of 2 (!!?) or more than other binding mechanisms. 
3. It does using various 'goals' or 'phases' including Code Generation, Binding Compiler and the Binding Runtime. The number of java classes and configuration code generated by  JiBX is far greater and is the 'acceptable tradeoff' to achieve the performance gain.

 [image publicly available at]

Fig. 3 JiBX Simple XML Binding

CXF/JiBX using Eclipse (Spring / Standalone Server)
You need the following tools, dependencies (with specific versions) to build this sample:
1. Maven Connector for Eclipse - m2e
2. CXF Codegen Plugin (Maven Eclipse Connector)
3. JiBX Maven Plugin  (Maven Eclipse Connector)
4. Maven Configuration (Spring Dependencies)

These are the steps to follow to create a sample "Calculator" web service using CXF and JiBX. We used the following as a reference:

There are a very few (next to none) links that explain the step-by-step web service creation. After my reading of Apache CXF and JiBX, I would recommend it for all JAX-WS/SOAP based web development in terms of performance. Though I have not done any benchmarking myself, I am impressed with the facts provided for both CXF and JiBX. You can use the below steps to understand (deploy) and then use it directly (as RI) into your project or product. The only drawback seems to be the curve in understanding (read the 'depths') completely both the frameworks, at times perplexing. Since there are many features that one never uses in a normal 'web services' project or product, you may be skeptical that you have missed something or there might be something more in there. But to start off, I give the detailed steps below. Rest, I leave it to the time you have and your curious mind. :-) Please do share in reply/comment to this entry, with your own blog entries or code samples or enhance this same sample!

1. Create a Maven Project in Eclipse
You can download the attached source code and understand further the 'Maven Project Object Model'. I am outlining the most important sections here:

The properties contain the version for easy reference and changes to the maven build file. The above are the right version, but you may want to try JiBX 1.2.6+ and also Spring 4.0.0+Also, you may want to try this on JDK 1.8.0; we used JDK 1.7.0.

 The above dependencies are only for Apache CXF and the version is read from the properties section. This contain 'all' the dependencies required for building this project related to CXF.

The above dependencies are only for JiBX and the version is read from the properties section. This contain 'all' the dependencies required for building this project related to CXF.

The above dependencies are only for Spring. Note that only 'Spring Context' is required for building and running this project. This is true even if you would want to deploy this on a Web/App Server.

2. Contract First Web Services (Develop the WSDL/XSD in Eclipse)
I was never a fan of 'Contract-First' approach. But after using Apache CXF/JiBX, I start believing this is the 'best' way of developing 'web services' progressively from a 'requirements' and 'design' phase. If you plan early, at the end you may just want to / have to 'copy and paste' your specification to generate code using Maven (CXF/JiBX). Even otherwise, it will involve only 'some work' to create the WSDL/XSD out of your documented 'service specifications' in a 'Software Requirements Specification' or 'System Design' document. You may go through the WSDL/XSD in the attached source code. (Note the in the XSD contains the types as normal 'verb names'. The standards recommend that the response/request 'message' names be suffixed with 'HttpIn', 'HttpOut', 'Request', 'Response', 'SoapIn', 'SoapOut')

Fig. 4 XML Schema Definition (XSD)

You may go through the WSDL/XSD in the attached source code.

Fig. 5 Web Services Definition Language (WSDL)

3. Run the Maven Build (mvn install)
a. generate-sources
The following is the code extract from the pom.xml for the generate-sources from the cxf-codegen-plugin. Also, shown is the declaration (inclusion) of the Maven Compiler for running the Binding Compiler.

Fig. 6 Maven Code Extract for 'Generating Java Sources for Web Services'
 (Note -nexclude Flag for Types)

b. generate-java-code-from-schema
This goal is used to generate the Java Types using the JiBX maven plugin. It also generates the binding.xml. All of the generated  will be available under the 'target/generated-sources'.

Fig. 7 Maven Code Extract for 'Generating Java Type from Schema'
(Note we have mentioned a dummy/mock 'Custom JiBX Code Generation' XML)

c. bind
The 'bind' goal to bind the generated sources, types and the binding. This phase is the 'Binding Compiler' and when a request is made, then the 'Binding Runtime' will 'kick-in or trigger'.

Fig. 8 Maven Code Extract for 'Binding Compiler'
(Note Path to the 'Generated Sources' and 'Binding')

4. Identify the Generated Classes (Understand CXF/JiBX Better)
Spend some time to identify the generated classes and artefacts to better understand and appreciate the cxf-codegen-plugin and jibx-maven-plugin

Fig. 9 Maven Code Extract for 'Binding Compiler'

5. Deploy and Run (Start with Standalone Java using Spring Context) 
You can run the Main class at 'de.frvabe.sample.calculator.Main'. This will load (and deploy the web services Endpoint) the web services configuration using a Spring ClassPathXmlApplicationContext (from the spring configuration 'calculator-app-context.xml').

Fig. 10 Running the Main Class (Console)

6. Verify on the Browser (Check if WSDL Exists and is Accessible) - Alternatively, use SoapUI
Find the request provided and the response returned, using SoapUI.

 Fig. 11 SOAP Request (Using SoapUI)

Fig. 12 SOAP Response (Using SoapUI)

[The function  performed is a 'dummy add' with the value supplied (and zero) and the result is returned as response]

You can download the archive from here. You may choose to run this example on Tomcat or Weblogic or Websphere or JBoss or ??. Try adding functionality or exploring other 'Sophisticated Code Generation' capabilities of JiBX, as per your project requirement.

[You may want to use other reference implementations of JAX-WS or use the default JAXB for developing web services. This article is specifically for SOAP using CXF/JiBX (Eclipse/Standalone/Tomcat). This article may also help people, needing introduction to CXF/JiBX, who are already well versed in building SOAP Web Services using any of (or combination of) JAX-WS, Axis, Spring, JAXB and XML.]