Axis2JiBXClient

You want to generate a Java client for a WebService from its WSDL file. This documentation gives you the step by step instructions.

Types of Axis2 Clients

With Axis2 you can generate clients using 3 types of bindings.

As stated in the Axis2 Documentation ADB is the most straightforward way to generate Java clients but it has limitations when it comes to dealing with XML elements that extend other elements, i.e., polymorphic elements. If the response of your webservice call contains polymorphic elements that are nested, ADBException: Unexpected subelement hits you hard while parsing the response into Java Objects.

XMLBeans: Unlike ADB, XMLBeans is a fully functional schema compiler, so it doesn't carry the same limitations as ADB. It is, however, a bit more complicated to use than ADB. It generates a huge number of files, and the programming model, while being certainly usable, is not as straightforward as ADB.

JiBX: JiBX is a complete databinding framework that actually provides not only WSDL-to-Java conversion, as covered in this document, but also Java-to-XML conversion. In some ways, JiBX provides the best of both worlds. JiBX is extremely flexible, enabling you to choose the classes that represent your entities, but it can be complicated to set up. On the other hand, once it is set up, actually using the generated code is as easy as using ADB.

Generate Java Client using Axis2 and JiBX

The instructions provided here are based on the most recent versions of Axis2 1.7.4 and JiBX 1.3.1 that are available as of this writing.

Step 1: JiBX CodeGen

JiBX CodeGen tool generates Java Objects for the XML elements that are present in the WSDL or in the XSD files referenced by the WSDL. This tool also generates a binding file that is needed for Step 2.

Download the latest version of JiBX 1.3.1 and Unzip the contents. The lib directory has jibx-tools.jar that has CodeGen tool.
The WSDL file has elements referenced either inline or by means of XSD files in the schema section.
```
  <wsdl:types>
    <schema>
    ...
    ...
    </schema>
  </wsdl:types>
```
If the schema is inline extract that as an XSD file as explained here. If the schema isn't defined inline and it refereces externally hosted XSD files, we just need the URLs of the top level XSD file(s). CodeGen will automatically load other XSD schemas refrenced by the top level XSD file and include them in the code generation.
Navigate to the lib directory of JiBX and run the following CodeGen command to generate java classes and the binding file:

java -Xms512M -Xmx512M -cp ./jibx-tools.jar org.jibx.schema.codegen.CodeGen -p com.yourCompany.axis2.jibx.packageName -t /Users/directory/path/for/yourService -w "http://remote.webservice.com/yourService.svc?xsd=xsd0"
This generates binding.xml file and java classes in the directory /Users/directory/path/for/yourService/com/yourCompany/axis2/jibx/packageName.

Step 2: Axis2 WSDL2Java

The steps below will generate the stub needed to create the java client for the web service. Axis2 needs the binding.xml file generated from the previous step for creating the stub.

Download the binary distribution of the latest version of Axis2 1.7.4 and Unzip the contents.
Navigate to the bin directory and run the wsdl2java command.

./wsdl2java.sh -o /Users/directory/path/for/yourService -s -p com.yourCompany.axis2.jibx.packageName -d jibx -Ebindingfile /Users/directory/path/for/yourService/binding.xml -sp -uri "http://remote.webservice.com/yourService.svc?wsdl"
This generates build.xml file and /src directory with Axis2 generated java classes in /Users/directory/path/for/yourService.
Move the JiBX generated java classes that are under /Users/directory/path/for/yourService/com/yourCompany/axis2/jibx/packageName into the same /src directory so that both Axis2 and JiBX generated classes are in /Users/directory/path/for/yourService/src/com/yourCompany/axis2/jibx/packageName.
Kick start the Ant build using build.xml. If you are using Eclipse, set up Environment Variable AXIS2_HOME with the directory path where you have Unziped Axis2 1.7.4 as the value. If you are using IntelliJ, in the Ant build set up a property env.AXIS2_HOME with the same directory path as the value.
This will generate a jar file with the name specified in the build.xml. Feel free to change the name of the jar by updating build.xml.

Step 3: JiBX Binding

The above step compiles most of the available classes, but not everything. Fortunately, it does compile the classes needed by the JiBX compiler, so you can now generate the actual JiBX resources. With the JiBX binding compiler we need to compile the bindings into the class files generated.

Navigate to the build/classes directory. It our example it is /Users/directory/path/for/yourService/build/classes.
Run the following command to compile the bindings:

java -jar /Users/directory/path/jibx/lib/jibx-bind.jar -v /Users/directory/path/for/yourService/binding.xml
This will generate several class files prefixed with JiBX_binding... in /Users/directory/path/for/yourService/build/classes.
Re-run the Ant task again as explained in Step 2 above. The generated jar file will have the bindings included.

Step 4: Create Client with needed Dependencies

If you check the src directory /Users/directory/path/for/yourService/src/com/yourCompany/axis2/jibx/packageName you will have an interface for your webservice and a stub implementation. Example YourService.java and YourServiceStub.java. The client can be created using the interface and implementation.

import com.yourCompany.axis2.jibx.packageName.YourService;
import com.yourCompany.axis2.jibx.packageName.YourServiceStub;

public class YourServiceClient {
    private YourService service = new YourServiceStub();

    public void doSomething() {
        service.callSomething();
    }

The client needs several of the Axis2 and JiBX jars to run. You may want to either include the jars with your client or declare dependency on them. Here is a snippet of Grails dependency declaration for a client created using Axis2 1.7.4 and JiBX 1.3.1

        runtime ('org.apache.ws.commons.axiom:axiom-api:1.2.20',
                'org.apache.ws.commons.axiom:axiom-dom:1.2.20',
                'org.apache.ws.commons.axiom:axiom-impl:1.2.20',
                'org.apache.axis2:axis2-transport-local:1.7.4',
                'org.apache.axis2:axis2-transport-http:1.7.4',
                'commons-httpclient:commons-httpclient:3.1',
                'wsdl4j:wsdl4j:1.6.2',
                'org.apache.ws.commons.schema:XmlSchema:1.4.7',
                'org.apache.neethi:neethi:3.0.3',
                'javax.mail:mail:1.4',
                'org.apache.httpcomponents:httpcore:4.4.4',
                'org.apache.woden:woden-core:1.0M10',
                'org.apache.axis2:axis2-jibx:1.7.4',
                'org.jibx:jibx-run:1.3.1',
                'xpp3:xpp3:1.1.4c') {
            transitive = false
        }

TutteRamson/Axis2JiBXClient