Usage of an XML catalog in the XMLBeans-CXF integration

Introduction

Currently XML is largely used as an exchange format usable by different technologies between different systems hosted on several hosts. XML is so generic that it needs to be restricted to sub-languages that we need. In order to formally define such sub-languages, XSD has been defined. XSD allows to build a contract between message producers and consumers. Moreover, it allows automatic validation of incoming/outgoing messages, auto-completion in editors, etc.

An XSD contract can be defined into different files (an XSD file is also an XML file), possibly spread into different modules and locations (FTP, HTTP, local file system, etc). An XSD contract can be extended, or included into another one. In the following sample, we re-use the definition of a job defined in the XSD located in http://www…/execution-core.xsd in order to define a job chain. So, we only need to define that particular list that only containing jobs. That kind of list is called chainJobDetails.

This is a sample XML that satisfies this XSD contract. Two jobs (34 and 35) are defined.

As you can see, including the existing schema can be done easily, increasing our productivity and re-usability, complying with the “separation of concern”.

XMLBeans support in CXF, previous limitation

XSD contracts for web services define the type of the web service method arguments and their results. But, those XML elements have to be parsed to be usable by Java. For that, the XMLBeans generator parses XSDs and produces XMLBeans objects that will be used to parse and create the Java representation of XML elements. Those XMLBeans objects and their associated XSDs are placed in the classpath. XSD can be found in: schemaorg_apache_xmlbeans/src/X/schemaName.xsd where X is the target namespace of the XSD.

We were using XSDs importing other XSDs using fully qualified URL. For instance we had the following import in one of our XSDs:

We faced the following problem, the XMLBeans integration tried to load the upper schema from the location: schemaorg_apache_xmlbeans/src/http://www.myCompany.com/deployLocation/X/mySchema.xsd. Of course, the schema did not exist at that location, but was located in schemaorg_apache_xmlbeans/src/com/myCompany/X/mySchema.xsd. Our WSDLs were corrupted because some schemas were not included in them. The XMLBeans integration was resolving fully qualified location as being part of the XMLBeans schema location which was totally wrong.

Why using absolute paths instead of relative paths when referring XSDs ?

1. Modularity: defining XSDs in different independent modules means that if you have relative references, you have either cross-module relative references, or relative references depending on the deployment location. In the first case, you need the other modules on your hard drive. On the second case, when your are deploying your XSDs, you have to fix all the references in order to suit with that location.
2. Re-usability: using absolute path allows to easily copy schemas, integrate it in your projects while keeping its own references without changing them by absolute path.

Our solution

Relying on remote resources makes XML processing slow and unreliable (processing disconnected from the web, HTTP servers not available, etc). One way to avoid these problems is to use an XML catalog that contains a mapping between external entity references and locally-cached equivalents. Instead of fetching the external resource, the XML processing fetches the local resource. Further details on XML catalog on the OASIS project (in charge of its definition).

The JAX-WS specification mandates that all implementations must support XML catalogs. They allow you to specify mappings. CXF naturally supports such catalogs, but the XMLBeans integration did not use them. This is why we created a patch allowing to use the already-existing mechanism in the integration. The JAX-WS specification mandates that the catalog used to resolve WSDL and XML Schema documents is assembled using all available resources named META-INF/jax-ws-catalog.xml. Below, a sample XML catalog defined in META-INF/jax-ws-catalog.xml. All resources located in (the location starts with that prefix) http://www.myCompany.com/deployLocation/ can be found in the classpath under: schemaorg_apache_xmlbeans/src/com/myCompany/. For instance, if the XML processing resolves the resource http://www…/execution-core.xsd, it will fetch the local resource schemaorg_apache_xmlbeans/src/com/myCompany/execution/core/execution-core.xsd

As explained by this sample, every XSD from which XMLBeans object have been created, can be found in the classpath under the location: schemaorg_apache_xmlbeans/src/X/schemaName.xsd where X is the target namespace of the schema called schemaName.xsd. In order to facilitate the mapping between the deployment location and the classpath location, we suggest you to follow the namespace structure and deploy schemas to the same HTTP location. Like that the number of XML catalog entries will be reduced. For instance, deploy your schemas to the location http://www.bsb.com/xsdSchemas/.

Conclusion

This new feature, available as from CXF 2.2.11, provides an elegant way for dealing with advanced XSD contracts without requiring any changes on your existing ones. Only a simple XML catalog is needed which can be re-used by XSD editors such as XML Spy, or Eclipse. Note that thanks to the usage of catalogs, it is no more necessary to deploy XSDs to the location where they are supposed to be.

More links

• XML Catalog Definition
• XMLBeans integration in CXF
• JAX-WS Catalog Documentation