Programming Advanced Features of WebLogic Web Services Using JAX-WS

Using XML Catalogs

The following sections describe how to use XML catalogs:

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.

The following sections describe how to:

For more information about XML catalogs, see the Oasis XML Catalogs specification.

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:

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

Defining an External XML Catalog

To define an external XML catalog:

Each step is described in more detail in the following sections.

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.

The following provides a sample XML catalog file:

<catalog xmln="urn:oasis:names:tc:entity:xmlns:xml:catalog"   
    prefer="system">
    <system systemId="http://foo.org/hello?wsdl" 
            uri="HelloService.wsdl" />
    <public publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN" 
            uri="wsdl/myApp/myApp.wsdl"/>
</catalog>

In the above example:

For a complete description of the XML catalog file syntax, see the Oasis XML Catalogs specification.

Referencing the External XML Catalog File

To reference the XML catalog file from the clientgen or wsdlc Ant task in your build.xml file, use the catalogs attribute.

The following example shows how to reference an XML catalog file using clientgen. Relevant code lines are shown in bold.

<target name="clientgen">
<clientgen 
     type="JAXWS"
     wsdl="${wsdl}"
     destDir="${clientclasses.dir}"
     packageName="xmlcatalog.jaxws.clientgen.client"
     catalog="wsdlcatalog.xml"/>
</clientgen>
</target>

Embedding an XML Catalog

To embed an XML catalog:

Each step is described in more detail in the following sections.

Creating an Embedded XML Catalog

The <xmlcatalog> element enables you to embed an XML catalog directly in the build.xml file. The following shows a sample of an embedded XML catalog in the build.xml file.

<xmlcatalog id="wsimportcatalog">
     <entity publicid="http://helloservice.org/types/HelloTypes.xsd"
             location="${basedir}/HelloTypes.xsd"/>
</xmlcatalog>

For a complete description of the embedded XML catalog syntax, see the Oasis XML Catalogs specification.

Referencing an Embedded XML Catalog

The <xmlcatalog> child element of the clientgen or wsdlc Ant tasks enables you to reference an embedded XML catalog. To specify the <xmlcatalog> element, use the following syntax:

<xmlcatalog refid="id"/>

The id referenced by the <xmlcatalog> child element must match the ID of the embedded XML catalog.

The following example shows how to reference an embedded XML catalog using clientgen. Relevant code lines are shown in bold.

<target name="clientgen">
<clientgen 
     type="JAXWS"
     wsdl="${wsdl}"
     destDir="${clientclasses.dir}"
     packageName="xmlcatalog.jaxws.clientgen.client"
     catalog="wsdlcatalog.xml"/>
     <xmlcatalog refid="wsimportcatalog"/>
</clientgen>
</target>
<xmlcatalog id="wsimportcatalog">
     <entity publicid="http://helloservice.org/types/HelloTypes.xsd"
             location="${basedir}/HelloTypes.xsd"/>
</xmlcatalog>

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:

<clientgen
type="JAXWS"
wsdl="${wsdl}"
destDir="${clientclasses.dir}"
packageName="xmlcatalog.jaxws.clientgen.client"
catalog="wsdlcatalog.xml"
genRuntimeCatalog="false"/>

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.

<target name="wsdlget"
     <wsdlget 
          wsdl="http://host/service?wsdl"
          destDir="./wsdl/"
     />
</target>