These release notes contain important information available at the time of the release of iPlanet XML Adapter Designer (XAD), version 2.0. General information about this release, known problems, and other information are addressed here. Read this document before you begin using XAD.
These release notes contain the following sections:
This release is available to all supported iPlanet Integration Server (iIS) EAI customers through iPlanet's SubscribeNet service.
The XAD distribution contains:
The XAD documentation is available at http://docs.iplanet.com/docs/manuals/xad.html. This documentation consists of the:
Read your license for XAD version 2.0 carefully.
The XAD distribution provides example adapters that were generated with XAD. It also provides the API implementations for which the adapter examples were generated. The XAD documentation explains how to configure and run these example adapters and test them by sending XML requests with the XAD test client.
The test client is a universal client for XAD adapters. You can use it to test any adapter generated by XAD. The test client can send requests using HTTP or Java Messaging Service (JMS).
The XAD distribution also provides an example iIS client application that you can use to send requests to the example adapters. The XAD documentation explains how to configure and run the iIS client with the example adapters. Running this example will help you gain an understanding of how to configure XAD adapters and iIS clients to communicate with each other.
The example adapters are installed at the following location in your XAD installation:
The iIS client application is an installation option that you can choose during the XAD installation procedure.
Refer to Appendix A of the iPlanet XAD User's Guide for information on configuring and running an example adapter with the example iIS client. Refer to Appendix B for information on configuring and running the example adapters with the test client. These appendixes also provide information on configuring the examples to run over different transports.
An overview of the example adapters is provided in the readme file located at:
Detailed descriptions of the example adapters are provided as an appendix of the XAD User's Guide.
XAD version 2.0 has been certified for specific combinations of hardware, operating systems, and third party software, as described in the platform matrix available at:
Other combinations have not been testedresults using untested systems may vary.
XAD version 2.0 conforms with SOAP v1.1, as defined by the W3C (http://www.w3.org/TR/2000/NOTE-SOAP-20000508), with the following limitations:
The SOAP support in XAD has been verified only with iIS EAI 3.0 SP1 SOAP. For more information about SOAP support in iIS refer to Chapter 3 of the iPlanet iIS Backbone System Guide.
Before installing XAD version 2.0, read these Release Notes and the iPlanet XAD Installation Guide carefully. The installation guide contains important information about uninstalling previous versions and about configuring your environment before beginning the installation. The section "Documentation" explains where to find these documents.
Before you install XAD version 2.0, uninstall any previously installed releases of XAD. To uninstall the XAD Version 2.0 Early Access release, simply delete the distribution from your system. To uninstall the XAD Version 2.0 Beta release, follow the instructions provided in the XAD Installation Guide that was provided with the Beta release distribution.
The XAD distribution files available from iPlanet's SubscribeNet service require special preparation before you begin the installation procedure. This section describes how to prepare the downloaded distribution files for installation.
Table 1 lists the distribution files available with this release.
Distribution File
Platform
After downloading the appropriate distribution file for your platform, extract its contents to a local directory. The procedure for doing this depends on your platform.
The structure and contents of the extracted distribution are described in the readme.txt file located in the distribution's root directory.
After you have extracted the contents of the distribution file, proceed with the installation as described in the XAD Installation Guide.
iPlanet Web Server (iWS) is the supported runtime environment for the XAD listener servlet, (which provides HTTP transport services to XAD Java adapters). If you are using iWS in this capacity, ensure that it uses the Java Development Kit (JDK) 1.3.1, for optimum compatibility with XAD.
During installation of iWS, the installer requires you to either point to an existing JDK installation or install the JDK bundled with the iWS distribution. The JDK bundled with the iWS distribution is version 1.2.2. You should not use this older version. Instead, you should install JDK 1.3.1 before iWS and then provide the iWS installer with the path to the JDK 1.3.1.
This section describes known problems with this release of XAD and suggests possible workarounds.
This section provides corrections to significant errors or omissions in the documentation provided for XAD Version 2.0.
On Solaris platforms, you must source the fortedef.sh or fortedef.csh file located in the top-level directory of your iPlanet Unified Development Server (UDS) installation prior to:
The reason you need to source this file is to set the LD_LIBRARY_PATH and FORTE_ROOT variables.
If you send large XML documents to a Java adapter using JMS, you might need to allocate more memory to the JVM in which the XAD JMS listener is running. Check the JMS listener error log file located at XAD_ROOT/log/jms_adapterName_err.log file, where adapterName is the name of your adapter. If you find java.lang.OutOfMemoryError entries in the log file, this indicates that you need to allocate more memory.
On Solaris platforms, this line looks like this:
${JAVA_HOME}/bin/java -DXAD_ROOT=${XAD_ROOT} -Xmx64m com.iplanet.xad.jms.XADJMSRouter -properties ${XAD_JMS_PROP_FILE}
On Windows platforms, this line looks like this:
%JAVA_HOME%\bin\java -DXAD_ROOT=%XAD_ROOT% -Xmx64m com.iplanet.xad.jms.XADJMSRouter -properties %XAD_JMS_PROP_FILE%
By default, this argument is set to -Xmx64m, which allocates 64 Mb of memory. A memory allocation of 64 Mb is generally sufficient for requests of 80Kb. If your requests are larger than that, increase the memory allotment accordingly. Note, however, that the amount of memory required is also dependent on the system load.
This edit takes effect the next time you run the script.
XAD is based on iPlanet UDS, Java, and C/C++. In many cases the code relies on the supported operating systems and frameworks provided by these environments to handle character set determination and conversion, locale determination, character parsing, string parsing, and general input methods.
All XAD components (the Interface Editor/Generator, test client, generated adapters, transport drivers, and iIS example application) provide locale support and character encoding support for XML documents that is equivalent to UDS 5.0 SP1 and iIS EAI 3.0 SP1 (except that XAD does not support UTF-16).
The XAD components that are based on UDS or iIS (namely, the XAD Interface Editor/Generator and iIS example application) use the internationalization support provided by the UDS and iIS platforms as described in the following subsections.
For information about localizing XAD Generator messages, refer to the UDS guide, Building International Applications. The source file for the message catalog is installed in FORTE_ROOT/userapp/xad_gene/cl0/msg/c/xad_gene.msg, where FORTE_ROOT denotes your UDS installation directory.
For information on locale support in UDS and iIS, refer to the iPlanet Knowledge Base article 7737 located at:
For information on character encoding support in XML, refer to the iPlanet Knowledge Base article 7717 located at:
XAD components that are based on Java (test client, JMS/HTTP listener, adapter engine) use the internationalization support provided by the J2EE 1.3 Platform.
The message catalog (resource bundle) for all Java XAD components is located at:
These components select which properties file to use according to the system locale setting.
To localize Java XAD messages, make a copy of the properties file in the same directory and name it according your system locale setting. For example if the system locale is set to German/Germany, name the properties file XADi18N_de_DE.properties.
All XAD components based on Java can use the locales and encodings supported by the J2EE1.3 Platform.
Locales supported by J2EE1.3 are listed at:
Encodings supported by J2EE1.3 are listed at:
XAD XML parsing conforms to the XML Version 1.0 as specified by the W3C at:
XAD components that are based on C/C ++ (XAD C Adapter Framework) support internationalization through the open source, IBM International Components for Unicode (ICU) Version 1.8.1.
The message catalog source file for these components is located at XAD_ROOT/install/c/common/icu/msg/root.txt. The C/C++ adapters select the message catalog file based on the system locale setting of your operating system. To localize messages for these adapters, perform the following steps:
For more information on how to use the genrb utility, refer to the ICU documentation provided by IBM at:
For information on ICU support for locales and character encoding, refer to the ICU documentation provided by IBM at:
http://oss.software.ibm.com/icu/download/1.8.1/index.html
If an XAD Java adapter receives a request that doesn't specify an encoding, the adapter defaults to the UTF-8 encoding. In the same circumstance, XAD C adapters default to the encoding of the operating system locale.
If you are using the XAD test client for i18n testing, ensure that the encoding used by the system the test client runs on and the encoding specified in the XML documents passed by the test client match.
If your adapter's client is not an iIS proxy or the XAD test client, ensure that the XML request header:
If you have problems with XAD, contact iPlanet customer support at:
This URL provides access to the iPlanet Knowledge Base and other tools for tracking problems. It also provides information on contacting technical support and customer service.
So that we can best assist you in resolving problems, please have the following information available when you contact support:
The following URLs are useful sources of information on iPlanet products:
Last Updated March 01, 2002