29 Using XML Catalogs

This chapter describes how to use XML catalogs with WebLogic web services using Java API for XML Web Services (JAX-WS).

This chapter includes the following sections:

• Overview of XML Catalogs

• Defining and Referencing XML Catalogs

• Disabling XML Catalogs in the Client Runtime

• Getting a Local Copy of XML Resources

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.

Table 29-1 Support for XML Catalogs in WebLogic Server Ant Tasks

Ant Task	Description
clientgen	Define and reference XML catalogs in one of the following ways: Use the catalog attribute to specify the name of the external XML catalog file. For more information, see Defining an External XML Catalog. 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. You can disable the jax-ws-catalog.xml file from being copied to the client runtime environment, as described in Disabling XML Catalogs in the Client Runtime.
wsdlc	Define and reference XML catalogs in one of the following ways: Use the catalog attribute to specify the name of the external XML catalog file. For more information, see Defining an External XML Catalog. Use the <xmlcatalog> child element to reference an embedded XML catalog file. For more information, see Embedding an XML Catalog. When you execute the wsdlc Ant task, the XML resources are copied to the compiled WSDL JAR file or exploded directory.
wsdlget	Define and reference XML catalogs in one of the following ways: Use the catalog attribute to specify the name of the external XML catalog file. For more information, see Defining an External XML Catalog. Use the <xmlcatalog> child element to reference an embedded XML catalog file. For more information, see Embedding an XML Catalog. When you execute the wsdlget Ant task, the WSDL and imported resources are downloaded to the specified directory. Note: The contents of the XML resources are updated to reference the resources defined in the XML catalog(s).

The following sections describe how to:

• Define and reference an XML catalog to specify the XML resources that you want to redirect. See Defining and Referencing XML Catalogs.

• Disable XML catalogs in the client runtime. See Disabling XML Catalogs in the Client Runtime.

• 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.

For more information about XML catalogs, see the Oasis XML Catalogs specification at http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html.

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.

  Note:

  If you use the catalog option, you cannot define the catalog element in the catalog file using a relative path that starts with "../". If you do so, the element file cannot be copied to the client class directory and it may cause an unexpected exception in the client runtime.

• 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.

Note:

You can use the wsdlget Ant task to get a local copy of the XML resources, as described in Disabling XML Catalogs in the Client Runtime.

Defining an External XML Catalog

To define an external XML catalog:

1. Create an external XML catalog file that defines the XML resources that you want to be redirected. See Creating an External XML Catalog File.
2. Reference the XML catalog file from the clientgen or wsdlc Ant task in your build.xml file using the catalogs attribute. See Referencing the External XML Catalog File.

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:

• The <catalog> root element defines the XML catalog namespace and sets the prefer attribute to system to specify that system matches are preferred.

• The <system> element associates a URI reference with a system identifier.

• The <public> element associates a URI reference with a public identifier.

For a complete description of the XML catalog file syntax, see the Oasis XML Catalogs specification at http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html.

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:

1. Create an embedded XML catalog in the build.xml file. See Creating an Embedded XML Catalog.
2. Reference the embedded XML catalog from the clientgen or wsdlc Ant task using the xmlcatalog child element. See Referencing an Embedded XML Catalog.

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

Note:

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 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 at http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html.

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>