Overview of XML Catalogs

An XML catalog enables your application to reference imported XML resources, such as WSDLs and XSDs, from a source that is different from that which is part of the description of the Web Service. Redirecting the XML resources in this way may be required to improve performance or to ensure your application runs properly in your local environment.

For example, a WSDL may be accessible during client generation, but may no longer be accessible when the client is run. You may need to reference a resource that is local to or bundled with your application rather than a resource that is available over the network. Using an XML catalog file, you can specify the location of the WSDL that will be used by the Web Service at runtime.

The following table summarizes how XML catalogs are supported in the WebLogic Server Ant tasks.

Use the <xmlcatalog> child element to reference an embedded XML catalog file. For more information, see Embedding an XML Catalog.

When you execute the clientgen Ant task to build the client (or the jwsc Ant task if the clientgen task is embedded), the jax-ws-catalog.xml file is generated and copied to the client runtime environment. The jax-ws-catalog.xml file contains the XML catalog(s) that are defined in the external XML catalog file(s) and/or embedded in the build.xml file. This file is copied, along with the referenced XML targets, to the META-INF or WEB-INF folder for Enterprise or Web applications, respectively.

Note: The contents of the XML resources are not impacted during this process.

Get a local copy of the WSDL and its imported XML resources using wsdlget. These files can be packaged with your application and referenced from within an XML catalog. See Getting a Local Copy of XML Resources.

Defining and Referencing XML Catalogs

You define an XML catalog and then reference it from the clientgen or wsdlc Ant task in your build.xml file in one of the following ways:

Define an external XML catalog - Define an external XML catalog file and reference that file from the clientgen or wsdlc Ant tasks in your build.xml file using the catalogs attribute. For more information, see Defining an External XML Catalog.

Embed an XML catalog - Embed the XML catalog directly in the build.xml file using the <xmlcatalog> element and reference it from the clientgen or wsdlc Ant tasks in your build.xml file using the <xmlcatalog> child element. For more information, see Embedding an XML Catalog.

In the event of a conflict, entries defined in an embedded XML catalog take precedence over those defined in an external XML catalog.

Creating an External XML Catalog File

The <catalog> element is the root element of the XML catalog file and serves as the container for the XML catalog entities. To specify XML catalog entities, you can use the system or public elements, for example.

Disabling XML Catalogs in the Client Runtime

By default, when you define and reference XML catalogs in your build.xml file, as described in Defining and Referencing XML Catalogs, when you execute the clientgen Ant task to build the client, the jax-ws-catalog.xml file is generated and copied to the client runtime environment. The jax-ws-catalog.xml file contains the XML catalog(s) that are defined in the external XML catalog file(s) and/or embedded in the build.xml file. This file is copied, along with the referenced XML targets, to the META-INF or WEB-INF folder for Enterprise or Web applications, respectively.

You can disable the generation of the XML catalog artifacts in the client runtime environment by setting the genRuntimeCatalog attribute of the clientgen to false. For example:

In this case, the jax-ws-catalog.xml file will not be copied to the runtime environment.

If you generated your client with the genRuntimeCatalog attribute set to false, to subsequently enable the XML catalogs in the client runtime, you will need to create the jax-ws-catalog.xml file manually and copy it to the META-INF or WEB-INF folder for Enterprise or Web applications, respectively. Ensure that the jax-ws-catalog.xml file contains all of the entries defined in the external XML catalog file(s) and/or embedded in the build.xml file.

Getting a Local Copy of XML Resources

The wsdlget Ant task enables you to get a local copy of XML resources, such as WSDL and XSD files. Then, you can refer to the local version of the XML resources using an XML catalog, as described in Defining and Referencing XML Catalogs.

The following excerpt from an Ant build.xml file shows how to use the wsdlget Ant task to download a WSDL and its XML resources. The XML resources will be saved to the wsdl folder in the directory from which the Ant task is run.