29.3. Using a JAX-WS Catalog
Overview
The JAX-WS specification mandates that all implementations support:
a standard catalog facility to be used when resolving any Web service document that is part of the description of a Web service, specifically WSDL and XML Schema documents.
This catalog facility uses the XML catalog facility specified by OASIS. All of the JAX-WS APIs and annotation that take a WSDL URI use the catalog to resolve the WSDL document's location.
This means that you can provide an XML catalog file that rewrites the locations of your WSDL documents to suite specific deployment environments.
Writing the catalog
JAX-WS catalogs are standard XML catalogs as defined by the OASIS XML Catalogs 1.1 specification. They allow you to specify mapping:
- a document's public identifier and/or a system identifier to a URI.
- the URI of a resource to another URI.
Table 29.1, “Common JAX-WS Catalog Elements” lists some common elements used for WSDL location resolution.
| Element | Description |
|---|---|
uri | Maps a URI to an alternate URI. |
rewriteURI | Rewrites the beginning of a URI. For example, this element allows you to map all URIs that start with http://cxf.apache.org to URIs that start with classpath:. |
uriSuffix | Maps a URI to an alternate URI based on the suffix of the original URI. For example you could map all URIs that end in foo.xsd to classpath:foo.xsd. |
Packaging the catalog
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. If your application is packaged into a single JAR, or WAR, you can place the catalog into a single file.
If your application is packaged as multiple JARs, you can split the catalog into a number of files. Each catalog file could be modularized to only deal with WSDLs accessed by the code in the specific JARs.
