Release Notes for iPlanetTM XML Adapter Designer (XAD)

Version 2.0

Updated March 2002




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:




General Information

This release is available to all supported iPlanet Integration Server (iIS) EAI customers through iPlanet's SubscribeNet service.

The XAD distribution contains:

Documentation

The XAD documentation is available at http://docs.iplanet.com/docs/manuals/xad.html. This documentation consists of the:

XAD License

Read your license for XAD version 2.0 carefully.

XAD Examples and Test Client

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:

XAD_ROOT/adapters

The iIS client application is an installation option that you can choose during the XAD installation procedure.

Example Documentation

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:

XAD_ROOT/readme.txt.

Detailed descriptions of the example adapters are provided as an appendix of the XAD User's Guide.




Supported Systems and Software

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:

http://docs.iplanet.com/docs/manuals/xad.html#matrix

Other combinations have not been tested—results using untested systems may vary.

Support for SOAP v1.1

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.




Installation Topics

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.

Uninstalling Previous Versions

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.

Unpacking the Distribution File

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.



Table 1    XAD Distribution Files

Distribution File

Platform

xad_2.0_sun_sol.tar.gz 

Solaris platforms 

xad_2.0_win.zip  

Windows platforms  

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.

To extract the contents of the distribution file for Solaris platforms

  1. Use the gunzip utility to uncompress the distribution file, for example:

    % gunzip xad_2.0_sun_sol.tar.gz

    This command produces the archive file, xad_2.0_sun_sol.tar.

  2. Use the tar utility to extract the contents of the archive file, for example:

    tar xvf xad_2.0_sun_sol.tar

To extract the contents of the distribution file for Windows platforms

  1. Double-click the distribution file, xad_2.0_win.zip.

  2. Use the associated utility that opens to extract the contents to a local directory.

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.

Choosing a JDK When Installing iWS

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.




Known Problems

This section describes known problems with this release of XAD and suggests possible workarounds.



Table 2    Known Problems With this Release of XAD 

Bug Number

Component

Details

55960
 

Test Client 

Problem: Highlighted buttons do not respond when the Enter key is pressed.

Workaround: Press the Spacebar key instead of the Enter key. 
56152
 

Interface Editor/ Generator 

Problem: Newly created operations do not have the focus. If you create a new parameter immediately after creating a new operation, the parameter will belong to the operation that was previously selected.

Workaround: Select your newly created operation before creating parameters for it. 
56273
 

Interface Editor/ Generator 

Problem: User is not prompted to save changes to the interface definition before exiting the Interface Editor.

Workaround: Ensure that you save any changes you make to the interface definition before exiting the Interface Editor. 
56285
 

Interface Editor/ Generator 

Problem: The Data Type drop down list in the Parameter Editor dialog box does not display previously defined group and group collection parameters.

Workaround: If you have defined a group or group collection parameter in one operation and want to define a group or group collection parameter of the same data type in another operation, use the copy and paste facility in the Interface Editor to copy the parameter from one operation to the other. 
56296
 

Interface Editor/ Generator 

Problem: In a generated sample XML request, the sample string generated for a parameter of type {Sized String} does not conform to the size specified.

Workaround: Edit the sample string in the generated XML request file according to the size specified in the interface definition. 
56298
 

Interface Editor/ Generator 

Problem: Duplicate operation names can occur if the user changes the name of an existing operation to be the same as another operation in the interface definition.

Workaround: If you edit the name of an operation, ensure that it is unique in the interface definition. 
56299
 

Java Adapter and User-Defined Data Types 

Problem: Members of a Java class used as a user-defined data type must be public for the adapter to access their values.

Workaround: If the class members of the user-defined data type are not public, create a wrapper class. In the wrapper class, use public get and set methods to access the members of the data class. Then use the wrapper class to generate the adapter. 
56390
 

Test Client 

Problem: If you attempt to open a file that doesn't exist with the XAD test client, no error message is displayed. (This can happen only if you type in the file name.)

Workaround: Use the file browse facility to locate the file. 
56426
 

Interface Editor/ Generator 

Problem: The Interface Editor does not provide the means to delete Function Parameter mappings in the Activity Definition window.

Workaround: Delete the corresponding entries in the <XSLT_INBOUND_MAPPING> element in the interface definition file. 
56473
 

Interface Editor/ Generator 

Problem: Elements of a group parameter do not reflect the INOUT/OUTPUT/RETURN mechanism correctly. The attributes inside a group parameter do not show the same mechanism value as that of the containing group parameter.

Workaround: You can ignore this problem. Only the display is incorrect. If you save the interface definition and reload it, the correct values are displayed. 
56484
 

C Adapter with iIS proxy 

Problem: Only one session at a time can be established with a C adapter instance.

Symptom 1: The iIS proxy attempts but fails to establish more than one session with the same adapter instance.

Workaround 1: Set the number of outbound sessions for the proxy to be less than or equal to the number of C adapter instances. The default setting is: SetSessionMaximum out 1. For information on load balancing and starting multiple instances of a C adapter, see the XAD User's Guide.

Symptom 2: Unable to use the XAD test client to access the administration interface of a C adapter that is being used with an iIS proxy. The test client hangs, waiting for the adapter to service the socket connection request.

Workaround 2: Shut down the proxy before using the test client to administer the C adapter. 
56492
 

Installer 

Problem: If the installer detects an existing XAD installation, all of the installation options are disabled on the Select Components page and the Next button does not function, although it is enabled. The user is not prompted to uninstall the existing installation.

Workaround: The Help button displays the instructions on what to do. Uninstall the existing installation and then perform the new installation. 
56515
 

Example iIS Client  

Problem: The Close Window button is disabled in the example iIS client. When a plan exported from uds5 repository is imported into 3n1 repository, the window loses its properties. This problem occurs only in a UDS 3.5 environment.

Workaround: Open the StartCondProcess class in XADDemoClient plan and change the window property System Close Policy to Post Shutdown. 
56519
 

Interface Editor/ Generator 

Problem: The Name field for New Parameter definition and all other definitions accept invalid characters. User is able to name a parameter using any set of characters, for example: ! @ # $ % ^ & * ( ) _ + :; " ' < > ? ?/. Doing so can cause compilation and runtime errors because these characters are not allowed as C, Java, or XML identifiers.

Workaround: Ensure you don't use invalid characters. 




Documentation Errata

This section provides corrections to significant errors or omissions in the documentation provided for XAD Version 2.0.

Setting LD_LIBRARY_PATH

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.

Sending Large XML Documents With JMS

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.

To allocate more memory to the JVM in which the JMS listener runs

  1. Open the xad_run_jms script located in the XAD_ROOT/install/bin directory.

  2. Locate the line that starts the JMS listener.

    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%

  3. Increase the value of the argument that controls the memory allocation.

    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.




Internationalization/Localization

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

XAD Components Based on UDS and iIS

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.

XAD Generator Message Catalog

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.

Locale and Character Encoding Support for XML Documents

For information on locale support in UDS and iIS, refer to the iPlanet Knowledge Base article 7737 located at:

http://knowledgebase.iplanet.com/ikb/kb/articles/7737.html

For information on character encoding support in XML, refer to the iPlanet Knowledge Base article 7717 located at:

http://knowledgebase.iplanet.com/ikb/kb/articles/7717.html

XAD Components Based on Java

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.

Message Catalog

The message catalog (resource bundle) for all Java XAD components is located at:

XAD_ROOT/install/java/props/i18n/XADi18N.properties

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.

Locale and Character Encoding Support for XML Documents

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:

http://java.sun.com/j2se/1.3/docs/guide/intl/locale.doc.html

Encodings supported by J2EE1.3 are listed at:

http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

XAD XML parsing conforms to the XML Version 1.0 as specified by the W3C at:

http://www.w3.org/XML/

XAD Components Based on C/C++

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.

Message Catalog

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:

  1. Navigate to XAD_ROOT/install/c/common/icu/msg.

  2. Make a copy of the en_US.txt file in the same directory and name it according to the setting of your system locale using the form language_TERRITORY. For example if the system locale is set to German/Germany, name the file:

    XAD_ROOT/install/c/common/icu/msg/de_DE.txt

  3. Edit the file and change the first line from en_US to your locale setting, for example, de_DE.res.

  4. Translate the messages into the desired language.

  5. Run genrb on your message catalog file, for example:

    genrb de_DE.txt

    This command creates a compiled message catalog, for example, de_DE.res.

For more information on how to use the genrb utility, refer to the ICU documentation provided by IBM at:

http://oss.software.ibm.com/icu/download/1.8.1/index.html

Locale and Character Encoding Support for XML Documents

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



Note

Ensure that the documents you send to the adapter and the characters that your implementation API produces are in the encoding expected by the adapter.

For example, assume you want to send a UTF-8 encoded XML document using the XAD test client on a Japanese operating system. The XML document header is:

<?xml version="1.0" encoding="UTF-8"?>

If you edit the XML document using a text editor on your native Japanese system and then save the document, it will be saved in the default locale encoding of the operating system, which might be different than the encoding specified in the document header.

For example, the default locale encoding of the operating system might be euc_JP. In this case, the document cannot be transferred correctly since the encoding declaration in the document header (UTF-8) and the saved encoding euc_JP are different. In this circumstance, you would have to save the document explicitly in UTF-8 encoding. To do this, you need a special utility or a text editor with this utility built in.



Default Encodings

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.

Using the Test Client for i18n Testing

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.

Setting the Encoding for Non-iIS clients

If your adapter's client is not an iIS proxy or the XAD test client, ensure that the XML request header:




How to Report Problems

If you have problems with XAD, contact iPlanet customer support at:

http://www.iplanet.com/support/

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:




For More Information

The following URLs are useful sources of information on iPlanet products:

Use of iPlanet XML Adapter Designer is subject to the terms described in the license agreement accompanying it.
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated March 01, 2002