This chapter includes the following sections:
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:
When you execute the Note: The contents of the XML resources are not impacted during this process. You can disable the |
wsdlc |
Define and reference XML catalogs in one of the following ways:
When you execute the |
wsdlget |
Define and reference XML catalogs in one of the following ways:
When you execute the 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.
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.
To define an external XML catalog:
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.
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.
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>To embed an XML catalog:
build.xml file. See Creating an Embedded XML Catalog.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.
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.
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>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.
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>