jibx2wsdl

Jibx2Wsdl takes the start-from-code approach to web service development to a new level, with support for Java 5 enumerations and generic collections, JavaDoc extraction for use in service definitions, and automatic generation of JiBX bindings along with the matching schema and WSDL. It allows you to expose existing code as web services using Axis2 and JiBX data binding, while retaining the flexibility to modify your data model and adjust the JiBX bindings so that the XML is unchanged. Alternatively, you can just generate a WSDL and schema using Jibx2Wsdl and throw away the JiBX binding definitions, using the generated WSDL and schema as a quick start on a start-from-WSDL approach. The generated doc/lit wrapped WSDLs are compatible with Axis2 versions 1.1.1, 1.2, and 1.3, as well as other major web service frameworks.

For more discussion of the start-from-code approach, see my InfoQ article "Code First" Web Services Reconsidered. The current version of Jibx2Wsdl linked from this page matches that article, and includes the full sample code for the article as part of the distribution.

This wiki page is a temporary home for Jibx2Wsdl, until it's bundled in with the core JiBX distribution. The current Jibx2Wsdl code is the third public version. It's still considered pre-release software, but is already in use by many organizations. The first official release will be as part of the upcoming JiBX 1.1.6 release, due in early September.

Getting started

Eager to give it a try? Download jibx2wsdl4.zip and unpack it into an installation directory (which you can name jibx2wsdl, or whatever you want). This gives you a lib directory within your installation directory containing a full set of JiBX jars, including all the Jibx2Wsdl code as well as the normal runtime and binding compiler. Then in a console run "java org.jibx.ws.wsdl.Jibx2Wsdl" with all these jars in your classpath and you should get a summary of command line options. You can also check out the usage samples included in the distribution, and described in more detail in the following links:

-example1 - simple book service with Java 5 generic lists

-example2 - simple book service with arrays rather than lists, and using a customization file

-example3 - library service using polymorphism to handle different types of items (books and dvds), along with Java 5 enumerations

-example4 - library service using polymorphism with interfaces and multiple layers of derivation

The generated bindings and WSDLs are compatible with Axis2 1.3. To use them with older versions of Axis2, you'll need to replace the jibx-binding.jar and jibx-run.jar files in your Axis2 installation lib directory with the versions of these jars from the lib directory of this zip file. You may also want to update to the latest version of the axis2-jibx.jar for your version of Axis2, if you're using 1.1.1 or 1.2 - see axis2-jibx for that update. This will give you the latest bug fixes for using JiBX with Axis2. Remember to make this change for the jibx-run.jar and axis2-jibx.jar used in your Axis2 server, too (in the expanded axis2/WEB-INF/lib directory).

The command line options for the Jibx2Wsdl tool are described below, and you can find most details of the customization file format here: customize. The details of the customization format will be completed in time for the next update of Jibx2Wsdl, which will be by the end of August.

Command line options

Here's a list of the command line options, with a little more explanation:

-p path class file path component - this says where to find the class files for your service and data model classes. Unless your class files are in the classpath you'll need to use this option at least once.

-s path source file path component - this tells JiBX where to find the Java source files. This is optional, but very useful for JavaDoc access and such.

-t path target directory for generated files. The default is the current directory.

-b name file name for generated root binding. The generated bindings are namespace-modular, with a root binding that includes the bindings for each namespace, and this says the name to use for that root binding. The default is just binding.xml.

-x class1,class2,... extra classes to be included in the binding. This option can be used when not all the data model classes are explicitly referenced, either by your service classes or the data model classes reference by the service. One common use case is when you're using subclasses as runtime substitutes for base class references. See example3 for an example of this type of polymorphism.

class1 class2 ... actual service classes. Each of these classes is generated as a service exposing the public methods defined in that class, with a separate WSDL for each class and schema for the message elements used by that class. Once you've used the Axis2 WSDL2Java tool on the WSDL you should be able to just modify the generated service skeleton code to call your service implementation classes directly.

There's also an extensive customization structure that can be used with Jibx2Wsdl. Most of the customization options require the use of a separate customization file (see example2 for an example of using a simple customization file), but some global options can be passed directly on the command line. Here's a list of those customization options:

--namespace=uri base namespace used for data model classes.

--namespace-style=xxx method used for deriving namespaces: "none" for no namespace, "package" for derive from package name (the default), and "fixed" to use the same namespace everywhere. Using "--namespace-style=fixed" along with "--namespace=uri" forces the specified namespace to be used for all data model classes.

--namestyle=xxx method used for converting Java names to XML names. This can be: "camel-case" (initial capitals on words, except for first word), "upper-camel-case" (camel case with initial uppercase character, as with standard Java class names), "hyphenated" (hyphens between words), "dotted" (periods between words), or "underscored" (underscores between words). The default is "camel-case".

--property-access=true or false says whether to access data using fields ("false", the default), or JavaBean-style get/set methods ("true").

--strip-prefixes=xxx comma-separated list of prefixes to be stripped from field names when converting to XML.

--strip-suffixes=xxx comma-separated list of suffixes to be stripped from field names when converting to XML.

--use-nillable=xxx use xs:nillable for individual parameter values in wrapper element definition.

Status and bugs

Jibx2Wsdl does have a few limitations at present. One is that each type of exception thrown by any of your service methods needs to have a unique data object. This is really an Axis2 limitation rather than a Jibx2Wsdl limitation, but it does mean that you may need to structure your code to match this requirement if you want to use it directly as a web service. There's also another known exception issue, in that if the same exception is used by more than one service it currently won't be generated properly in the WSDL or binding.

Another limitation is that JiBX itself currently only supports schema polymorphism using substitution groups. Many other frameworks support type substitution as an alternative to substitution groups. There are benefits (and drawbacks) to each technique, but in the future JiBX will add support for type substitution and Jibx2Wsdl will add an option to chose which technique to use when converting class hierarchies into schema representations.

If you have issues or questions about Jibx2Wsdl please take them to the JiBX users list.

Here's a list of some major changes since the first public version:

Learning more

Want to learn more about Jibx2Wsdl, the tradeoffs of code-first vs. WSDL-first development, or Axis2 itself? I (Dennis Sosnoski) provide consulting and training services covering all these areas and more. My Axis2 training class has been especially popular with companies planning the development of Axis2 web services, while my SOA training class gives framework-agnostic guidance for developers in organizations moving to SOA. I'm going to be making a training trip to Australia in September, and another training trip to the U.S. in October-November. Contact me to enquire about arranging a class or consulting visit for your organization.