Web services tools - release notes

1.0 Introduction
2.0 Supported software and specifications
3.0 Changes from the previous release
4.0 Known problems
   4.1 Web Services Explorer
   4.2 TCP/IP monitoring server does not work on Linux
   4.3 Private UDDI Registry
   4.4 Interoperability with IBM SOAP runtime
   4.5 Generating a WSDL document from a DADX file
   4.6 Web tools JSP Generator
   4.7 Hospital Scenario
   4.8 Using the Universal Test Client
   4.9 Multiple output allowed in certain cases with DADX Web services
   4.10 JDBC driver preference is for use on Linux only
   4.11 Need to update DAD example files if XML extender is not installed in default directory
   4.12 DADX Web services issues
   4.13 Explorer pop-up dialogs may not display correctly if both Mozilla and Netscape are running
   4.14 DADX Generation Support
   4.15 WSDL errors after importing a Web services file from 4.0.x
   4.16 Problems when using Linux with GTK
   4.17 Using Tomcat server with AXIS runtime
   4.18 Problem with creating EJB Web services with the WebSphere v5.0.2 runtime
   4.19 Problems when using Web services command line
   4.20 Web service creation without an existing server
   4.21 Generating Web services sample application
   4.22 Importing WSDL files with HTTP basic Authentication
   4.23 Problems with using WebSphere v5.0.2 runtime
   4.24 Setting up a DADX group with datasource information
   4.25 Loading client locator using the Universal Test Client
   4.26 Resource preferences not observed
   4.27 Problems with using Apache Axis 1.0 runtime
   4.28 Web service sample JSP failed to compile
   4.29 Error with localhost not defined
   4.30 Permanent Limitations when using IBM SOAP runtime
   4.31 Web service and client using different runtime
   4.32 Clicking Finish in Web service client wizard
   4.33 Selecting router project when creating EJB Web services
   4.34 Creating EJB Web services or EJB skeleton using command line
   4.35 Web services cheat sheet

1.0 Introduction

The Web service tools feature enables you to discover, create, and publish Java bean, DADX, enterprise bean, and URL Web services. This readme file describes the known problems, limitations, and workarounds that are associated with the following Web service tools functions:

Generating a WSDL document from a Java bean, DADX document, enterprise bean, ISD file, and URL.

Generating a Java proxy or skeleton from a WSDL document.

Creating and deploying a Web service from a Java bean, DADX, enterprise bean, or URL.

Discovering and publishing Web services.

Generating a sample Web application from a Java proxy.

Interoperability issues.

2.0 Supported software and specifications

This release of the Web service tools generates code that complies with the following specifications:

Simple Object Access Protocol (SOAP) Version 1.1

Universal Description, Discovery, and Integration (UDDI) Version 2.0

Web Services Definition Language (WSDL) Version 1.1

Web Services Inspection Language (WSIL) Version 1.0

This release of the Web service tools supports:

the IBM WebSphere v5.0.2 Web services runtime

the IBM SOAP Version 2.2 and Version 2.3 runtime environments.
the Apache Axis 1.0 runtime

If you are launching the WORF test environment outside the workbench using Mozilla, a Mozilla version of at least 1.3.1 is recommended. Output from invoking your web service as well as description files may not be rendered correctly in earlier versions of the Mozilla browser.

The DADX runtime requires DB2 7.2 fix pack 6 or higher, or DB2 8.1 or higher.

3.0 Changes from the previous release

The following features are new in the Web services tools in v5.1:

Support the IBM WebSphere v5.0.2 Web services runtime. This is the strategic IBM Web services runtime that supports JSR-109 and JAX-RPC.

Support the Apache Axis 1.0 runtime. This runtime supports JAX-RPC and is for users who prefers to develop for the open Apache Axis platform.

Provide a Web services command line tool that enables the user to create Web services from a Java bean, EJB, or WSDL file, and to publish and unpublish business and services to UDDI registries.

Fully integrated the WSDL Explorer into the Web Services Explorer.

Provide Web services application assembly tooling including:

Web Services Editor and Web Services Client Editor to edit the JSR-109 and IBM WebSphere v5.0.2 deployment descriptors.

Pop-up action to call the EndpointEnabler function.

Pop-up action to call the WebServiceDeploy function.

Help guide the user in the creation of WS-I compliant Web services through preferences. The user can choose to have the Web services wizard require, suggest or ignore WS-I compliance when creating Web services.

Generate and consume per-proxy WSIL Web service reference documents.

Enable the user to update the WebSphere v5.0.2 deployment descriptors with sample security configurations.

Support SOAP over JMS as transport for SOAP messages when creating Web services from EJBs.

Support user-defined UDDI categories.

Support Web Service Validation. When that preference is set, the tool validates that an Enterprise Application and/or the modules within it comply with a set of rules proving compliance with JSR-109.

4.0 Known problems

4.1 Web Services Explorer

When using the Web Services Explorer with the Private UDDI Registry, the Manage Publisher Assertion Form of a business node will not load in the following situations:

You are not logged in to the registry node containing the business node.

You are logged in to the registry node containing the business node, but the business node is not owned by the User ID/Password that is used to log in to the containing registry.

You will not be able to use the Web Service Explorer to query or publish through a basic authentication enabled UDDI registry. An example of this kind of registry is a private registry that is deployed on a server with basic authentication turn on. Please note that all the public registries (IBM, Microsoft, SAP, NTT and XMethods) are not affected by this problem.

When an advanced search is used in Web Services Explorer to find businesses in a WAS private UDDI registry configured with a Cloudscape backend and one or more service interfaces are specified as parameters, the search will fail and the status window will show:

com.ibm.uddi4j.wsdl.client.UDDIWSDLProxyException: Could not list all service providers. ------------------------------------------------------------------------------ Nested exception is: E_fatalError (10500) Serious technical error has occurred while processing the request. : Fault code=Client Fault string=Client Error Fault actor=null Detail=null DispositionReport: ErrCode=E_fatalError ErrInfoText=E_fatalError (10500) Serious technical error has occurred while processing the request.

The XMethods registry has procedures in place to verify published Web services deleting those which are not accessible or not working. To prevent a published Web service from being deleted, ensure that all URL references inside the WSDL files are accessible on the internet.

The SAP UDDI Business Registry will return a E_fatalError for a find business by category request with findQualifier equals to "combineCategoryBags" (tModelKey equals to UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2). The following error message will be displayed in the status window. This is a problem unique to the SAP UDDI Business Registry.

com.ibm.uddi4j.wsdl.client.UDDIWSDLProxyException: Could not list all service providers. ------------------------------------------------------------------------------ Nested exception is:
A serious technical error has occurred while processing the request. : Fault code=Client Fault string=UDDI Error Fault actor=null Detail=null DispositionReport: ErrCode=E_fatalError ErrInfoText=A serious technical error has occurred while processing the request. at com.ibm.uddi4j.wsdl.client.UDDIWSDLProxy.findAllServiceProviders(UDDIWSDLProxy.java:1626) at FindBusWithQualifier.main(FindBusWithQualifier.java:35)

Publisher assertion reports return by the SAP UDDI Business Registry do not contain any status. As a result, the publisher assertion status column in the Web Services Explorer's Manage Publisher Assertion Form will be blanked out for reports returned by SAP. This is a problem unique to the SAP UDDI Business Registry.

When attempting to publish a business, service or service interface to the XMethods UDDI Registry, you will get an error message regarding an "SSL Handshake Failure". This is a known problem which IBM and XMethods are investigating.

4.2 TCP/IP monitoring server does not work on Linux

The TCP/IP monitoring server does not work on Linux. Any attempt to insert the monitoring server between a Web Service and a Web Service client (for example, the Web service sample JSPs, Web tools Java bean JSPs and Universal Test Client) will interfere with communications between the client and the service. In particular, the client will hang indefinitely on the first response from the service. To recover from this condition in the sample JSPs or the UTC, close all browsers, then launch a new browser from outside of WebSphere Studio and type in the appropriate URL for the generated sample JSPs or the Universal Test Client.
To monitor SOAP traffic on Linux, try another monitoring tool such as the TCP/IP tunnel included with the Apache SOAP runtime which can be downloaded from http://ws.apache.org/soap/index.html.tool. Start the tunnel and invoke a Web service client operation. The request and response traffic should appear in the tunnel, however, the client will appear to suspend. Stop the tunnel. This will cause the client to unblock and the operation to complete. Restart the tunnel before attempting the next call.

4.3 Private UDDI Registry

Publisher assertions of the Private UDDI Registry may be visible to all businesses in the registry. A business may see publisher assertions that are associated with the business itself, for example, the business's key is neither the from keys nor the to keys of the publisher assertions.

When the Unit Test UDDI registry is configured with the Cloudscape database backend, UDDI find by name methods will perform case-sensitive searches by default. This goes against the UDDI specification and is a limitation.

The Private UDDI Registry should only be configured with the Cloudscape backend for very basic testing purposes (That is, do not use this backend for production work as there are currently difficulties with actions such as complex queries). For more information on the private UDDI Registry, please refer to the Network Deployment documentation in the WAS V5 InfoCenter.

After creating or updating a Cloudscape-based Unit Test UDDI registry on Linux, you may get a red warning in the server console that states:

Cloudscape (instance <uuid>) is attempting to boot the database <UDDI DB location> even though Cloudscape (instance <uuid>) may still be active. Only one instance of Cloudscape should boot a database at a time. Severe and non-recoverable corruption can result and may have already occurred.

This warning is a false alarm. More details can be found at:
http://www-1.ibm.com/support/docview.wss?rs=636&context=SSCVRP&q=&uid=swg21051601&loc=en_US&cs=utf-8&lang=en+en

4.4 Interoperability with IBM SOAP runtime

When using the IBM SOAP runtime, generating WSDL with complex parameters may cause problems with Microsoft tools that consume WSDL. The Microsoft tools do not handle XSD include statements properly, so it may be necessary to inline XSD schemas into generated WSDL. This can be done by selecting
Windows > Preferences > Web Services > Code Generation > use inline schema.

When using the IBM SOAP runtime, the Web services wizard is now fully enabled to generate element-based mappings, in addition to any of the normal type-based mappings, if the "Enable element-based mapping" checkbox is checked. From the WSAD main menu, this checkbox is found on the following preferences page:
Windows > Preferences > Web Services > Code Generation.
If this preference is not enabled, which is the default, the Apache/IBM SOAP runtime may not interoperate with other vendors' Web service runtimes that send messages whose elements do not have "xsi:type" properties. Web service runtimes from other vendors follow various policies on the inclusion of xsi:type properties. Some always include them. Some never do. Some provide a configuration choice. Some omit xsi:types for certain types, like arrays.
The typical error produced by the IBM/Apache SOAP runtime is:

targetException=java.lang.IllegalArgumentException: No Deserializer found to deserialize a ':MyElement' using encoding style 'http://schemas.xmlsoap.org/soap/encoding/'.

When enabled, element-based mappings are generated into:

the deployment descriptor file for bottom-up Java bean/EJB scenarios and WSDL Skeleton scenarios

the Proxy in client scenarios

Element-based mappings are of the form:

<isd:map
encodingStyle="encoding style"
xmlns:x="some-namespace"
qname="x:some-local-name"
xml2JavaClassName="some-deserializer-class-name"/>
An element-based mapping is generated for:

Each part defined in each wsdl:message input.

Each part defined in each wsdl:message output, for Skeleton and Proxy scenarios only.

Each root element or local element in each complex type referenced by parts in the WSDL file

The WSAD Web services wizard follows the SOAP and XSD specifications to determine whether or not the element name in an element-based mapping should be qualified (that is, have a namespace) or unqualified.

The WSAD Web services wizard follows these rules for deciding between qualified and unqualified element names:

Part names in WSDL yield unqualified names.

Root elements in XSD yield qualified names.

Local elements in XSD yield unqualified names if the schema specifies elementFormDefault="unqualified", which is also the default if the schema has no elementFormDefault attribute.

Local elements in XSD yield qualified names if the schema specifies elementFormDefault="qualified".

Some runtimes are known to generate unqualified elements in SOAP messages despite a schema that specifies the use of qualified elements via the XSD schema's "elementFormDefault" attribute. In such cases, you may need to hand-edit a service's WSDL or XSD and change elementFormDefault to "unqualified".

An example of a non-namespace qualified element-based mapping is:

<isd:map
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x=""
qname="x:name"
xml2JavaClassName="org.apache.soap.encoding.soapenc.StringDeserializer"/>
An example of a namespace qualified element-based mapping is:
<isd:map
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x="http://www.ibm.com/"
qname="x:name"
xml2JavaClassName="org.apache.soap.encoding.soapenc.StringDeserializer"/>
Please note that only one element based mapping will be generated for a given element name. That is, if the schema uses the same element name more than once but with different types, only one of the elements will be selected, effectively at random, as the basis for one element-based mapping. The other identically-named elements of different types will fail to deserialize. The same is true if the schema uses the same name for an element and for a WSDL part.

When beginning with a service bean which returns an array of Map or an array of Hashtable, and the "element-based mapping" option is enabled, the generated SOAP Proxy will incorrectly map the return type to a java.lang.String[]. A ClassCastException will occur during run time. To work around this problem, run the Web service client wizard with the newly created WSDL and regenerate the SOAP proxy into the client project.

4.5 Generating a WSDL document from a DADX file

In order to improve interoperability with Microsoft Web services, the DADX runtime has been updated so that they can generate document style Web services. To enable this feature, use the DADX configuration wizard to open the property page for a DADX group that is to be used. At the bottom of the property page ensure that the "Use document style" entry field is set to true.

Generating a Java proxy for DADX call operations with multiple output parameters is not supported.

When creating a DADX web service, occassionally the message "IWAB0177E Error generating WSDL from a DADX file." will appear. In most cases this message is an indication of some database related problem and the server console log should be consulted for details on the problem. Also, check the following:
The DAD (*.dad) files need to be located in the DADX group directory. This is how the WORF runtime locates DAD files.

If you are trying to generate a DAD file from a RDB to XML Mapping file (.rmx), make sure the DAD file is located in the same folder as the DADX file.

The DADX schema no longer uses the WSDL document tag for documentation. This tag is now a part of the DADX schema. This may cause validation problems with old DADX files that have not been migrated to using the updated schema. For example, if your old DADX file contained the following XML:
<wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> Provides queries for part order information at myco.com. </wsdl:documentation> the new document entry would be: <documentation> Provides queries for part order information at myco.com. </documentation>

4.6 Web tools JSP Generator

The generated Web tools Java bean JSPs do not support special types BigDecimal, Date, GregorianCalendar, BigInteger and URL. Also not supported are maps, collections, arrays and complex types. You may hand-edit the JSPs to support these types, or you may generate the Web service Sample JSPs instead, which do support these types. Visit Windows > Preferences > Web Services > Dialogs to choose your preferred style of generated Sample JSPs.

4.7 Hospital Scenario

The DB2 driver db2java.zip must be added to the WebSphere ws.ext.dirs class path. To add db2java.zip, do the following:
Switch to the Server perspective (Window > Open Perspective > Server).

In the Server Configuration pane, expand Server.

Double-click WebSphere v.4.0 Test Environment. The Instance editor opens.

In the Instance editor, click the Paths tab, then click Add External JARs in the WebSphere specific class path (ws.ext.dirs) section to add /home/db2inst1/sqllib/java12/db2java.zip to the WebSphere path.

Select File > Save (name of file) to save your changes, then exit the Instance editor.

For updates to the Hospital scenario documentation, go to the WebSphere Developer Domain and click Library.

4.8 Using the Universal Test Client

When launching the Universal Test Client from the Web Services wizard, the JNDI Provider URL is set to the default WebSphere v5 port of 2809. If you are using a WebSphere v4 server or if you have changed the port number, you would not be able to search the JNDI directory. If you try to access the JNDI directory, you will get the following error:

IWAD0403E Could not construct the JNDI tree: Caught CORBA.COMM_FAILURE when resolving initial reference=WsnNameService
The workaround is:

Double-click the server you are using. This will bring up the server properties.

Select the ports tab.

Copy the Orb bootstrap port.

Open the JNDI properties window in the Universal Test Client.

Paste the bootstrap port into the Provider URL text iput box.

4.9 Multiple output allowed in certain cases with DADX Web services

Normally, multiple outputs in a Web service is not supported by our tools. However, in the case of DADX Web services, multiple outputs are allowed if the Use Document Style group property is set to true. In this case, when document style is true, multiple outputs are combined together into a single XML document.

4.10 JDBC driver preference is for use on Linux only

A new Web services Preferences (Windows > Preferences > Web Services) category called JDBC drivers has been added. Although this preference is available on all platforms, it is intended for use only on Linux. On Linux, it can be difficult to determine the location of the JAR file containing JDBC drivers. Therefore, this preference page was added so that you can specify which JAR file to use. Currently, only the DADX validation code uses this JAR file information.

4.11 Need to update DAD example files if XML extender is not installed in default directory

The DAD files located in the WSinstall_dir\wstools\eclipse\plugins\com.ibm.etools.webservice_<version>\samples\DADX_examples directory may need to be modified to reflect your particular system configuration.

Near the top of the file is a line similar to the following:

<!DOCTYPE DAD SYSTEM "c:\dxx\dtd\dad.dtd">

If the XML extender has been loaded into a different location than c:\dxx then this string needs to be updated to reflect the actual location. This applies to Linux machines as well, where the location is usually /usr/IBMdb2xml.

4.12 DADX Web services issues

On the Web service DADX group property page of the Web services wizard, changes may not take effect immediately. Therefore, we recommended that changes to DADX group properties be done using the DADX Group Configuration Wizard.

After editing and validating a DADX file, you may get a message in the Tasks view that states that the project needs to be rebuilt. If this situation arises, right-click the appropriate project and click Rebuild project. You may need to do this a second time to remove the message from the Tasks view.

4.13 Explorer pop-up dialogs may not display correctly if both Mozilla and Netscape are running

The Web services Explorer's pop-up dialogs may not display correctly if both Mozilla and Netscape are running at the same time. Pop-up dialogs include the Browse WSDL dialog and the Browse Category dialog. To work around this, use either Mozilla or Netscape, but not both at the same time.

4.14 DADX Generation Support

Although user defined functions are listed in the Generate DADX wizard, there is currently no support for generating DADX from user defined functions. Support is only available for DADX generation from DAD files, stored procedures and SQL statements. Selecting a UDF will cause a simple DADX skeleton file to be generated.

4.15 WSDL errors after importing a Web services file from 4.0.x

If you have imported a Web services file from 4.0.x, you may receive the following error messages:

Error The part 'result' has an invalid value 'anyElement' defined for its type. Type declarations must refer to valid values defined in a schema. Error The part 'return' has an invalid value 'findPatientResult' defined for its element. Element declarations must refer to valid values defined in a schema. Error The part 'response' has an invalid value 'findPatientResponse' defined for its element. Element declarations must refer to valid values defined in a schema.

The workaround is:

Delete the WSDL files.

Regenerate your Web services by rerunning the Web Services wizard.

4.16 Problems when using Linux with GTK

When running WebSphere Studio on Linux with GTk, the web service creation wizard always default the Web service type to "Skeleton Java Bean Web Service" regardless of what the selection in the workbench is. The user should override the default and pick the desired Web service type.

4.17 Using Tomcat server with AXIS runtime

The problem happens on Linux with Tomcat 4.1 and 4.0 servers that have webapp with Axis installed. If the server was started and requires restart somewhere in WebServices wizard, wizard may hang because Axis blocks Tomcat server from stopping.
This could be work around by stopping the server before starting Web Service wizard and unchecking "Run on Server" on the wizard's page that generate test Web Service application.

4.18 Problem with creating EJB Web services with the WebSphere v5.0.2 runtime

When creating EJB skeleton Web service, hitting Finish on the Service Deployment Configuration page may result in a Publishing Status Error message when an EJB Project needs to be created by the wizard. This error message may be hidden under the "Repair Server Configuration" dialog. To proceed, click OK for both Dialogs and hit Finish again. To avoid the problem, hit Next on the Service Deployment Configuration page or create the EJB project before creating EJB Skeleton Web Service.

When generating skeleton EJB from WSDL file, if the WSDL file uses SOAP over JMS as transport, ensure that the router project is an EJB project, not a Web project. Otherwise, you will get an error message when go though Web service creation wizard.

When generating EJB skeleton, if a J2EE level 1.2 Web project is chosen as the Router project in the Service Deployment Configuration page, make sure an existing level 1.1 EJB project contained in the same EAR as the Web project is chosen as the EJB project before proceeding any further into the wizard. If you rely on the wizard to automatically create the EJB project, the wizard will create a level 2.0 EJB project, which is incompatible with a level 1.2 EAR and level 1.2 Web project.

When running Web Service creation wizard to create a SOAP/JMS web service more than once with the same router project, you will get multiple instances of the WebServiceJMSRouter MDB, which will cause error when starting the server. The workaround is to delete the old WebServiceJMSRouter MDB before re-run the creation wizard if the same router project is going to use again.
Fellow the steps below to delete old MDB:

Expand JMS router project, and find ejb-jar.xmi file under <project>/ejbModule/META-INF.

Right click ejb-jar.xmi, then open with "EJB Deployment Descriptor".

Click "Beans" tab, and remove the old MDB.

Save the changes.

When using the test client to test EJB SOAP/JMS Web Service, invoking desired method returns expected results. However you will get the following JMS exceptions in the server console (which does not affect the result):
[6/21/03 10:11:43:183 EDT] 2bdfe48e ConnectionEve A J2CA0056I: The Connection Manager received a fatal connection error from the Resource Adaptor for resource JMS$WebServicesReplyQCF$JMSManagedConnection@1980540041. The exception which was received is javax.jms.JMSException: MQJMS2000: failed to close MQ queue [6/21/03 10:11:43:214 EDT] 2bdfe48e ConnectionEve A J2CA0056I: The Connection Manager received a fatal connection error from the Resource Adaptor for resource JMS$WebServicesReplyQCF. The exception which was received is javax.jms.JMSException: MQJMS2000: failed to close MQ queue [6/21/03 10:11:43:224 EDT] 2bdfe48e ConnectionEve A J2CA0056I: The Connection Manager received a fatal connection error from the Resource Adaptor for resource JMS$WebServicesReplyQCF$JMSManagedConnection@1980540041. The exception which was received is javax.jms.JMSException: MQJMS2000: failed to close MQ queue [6/21/03 10:11:43:544 EDT] 2bdfe48e JMSListenerMD E WSWS3406E: Unexpected exception caught while sending reply message: javax.jms.JMSException: MQJMS2000: failed to close MQ queue

When generating EJB skeletons from a WSDL file that uses types without any default JAX-RPC mappings, a runtime exception will be returned when the user tries to invoke the Web service. The problem is that the run-time has difficulties deserializing javax.xml.soap.SOAPElement. java.xml.soap.SOAPElement is used when a type does not have any mappings associated with it, as a result, is mapped as a document fragment.

When generating EJB skeletons from a WSDL file with an operation that has inout parameters, errors will surface when generating deployment codes for the EJB. The problem is that inout parameters are mapped to javax.xml.rpc.holders.Holder classes. Since java.xml.rpc.holders.Holder do not implement java.io.Serializable, they cause EJB deployment errors.

4.19 Problems when using Web services command line

FileNStoPkg option: The -fileNStoPkg option for WSDL2WebService in command line is currently not working. Please use -NStoPkg and type out each mapping in the command line. Another option is to use the Web Service wizard if namespace to package mapping is required.

Directory with space: Avoid running WSDL2WebService from a directory containing a space in the directory name. Otherwise, the compile.bat (or compile.sh on Linux) that is generated does not compile.

Client deployment descriptors and WSDL files: After running Bean2WebService, EJB2WebService, WSDL2WebService, the client side deployment descriptors (webservicesclient.xml, ibm-webservicesclient-bnd.xmi, ibm-webservicesclient-ext.xmi, and the _mapping.xml) are under client-side/META-INF. If the user intends to create a managed client application, they should follow the following procedures:

To run the managed client in the form of an EJB or J2EE Application Client, the user must package all the deployment descriptors under META-INF of the archive plus copying the wsdl from the service side (under WEB-INF/wsdl if service is in Web container or META-INF/wsdl if service is in EJB container) to META-INF/wsdl of the client project.

To run the managed client inside the Web container, the user must package all the deployment descriptors to WEB-INF of the client archive (usually in the form of a WAR or a Web Project in WebSphere Studio). The WSDL file must also be copied from the service side to WEB-INF/wsdl. The user also needs to manually edit webservicesclient.xml (using a text editor or if in WebSphere Studio, xml editor) by replacing every occurance of META-INF to WEB-INF.

Class name with underscore: When creating Web service from Java bean or EJB, if the class name of the service bean has an underscore in it and the following character is lower case (for example test.Simple_bean), the service cannot be started on the WebSphere Application Server. The workaround is to either use a service bean name without underscore or use a capital letter after the underscore (for example, test.Simple_Bean).

4.20 Web service creation without an existing server

When going through a Web service creation scenario without an existing Web server in the workspace, hitting Back on the third page will cause the Next button to be disabled. The workaround is to cancel from the wizard and re-start the wizard. To avoid this problem, create the server and configuration prior to starting the Web service scenario or avoid hitting Back on the third page when there is no existing Web server.

4.21 Generating Web services sample application

When a user right clicks on a Java file in the workbench, the Generate Sample Application popup action under the Web Services menu generates Web services sample JSPs for an IBM SOAP proxy. To generate Web services sample JSPs for the other Web service runtimes (IBM WebSphere 5.0.2 and Apache Axis 1.0), right click on a WSDL file and choose the Generate Client popup action under the Web Services menu. When going through that wizard, select Test the generated proxy

4.22 Importing WSDL files with HTTP basic Authentication

When generating skeletons or clients from a WSDL file that has relative imports and is HTTP Basic Authentication protected, the user will see an error message indicating that the WSDL file cannot be resolved even if the correct user ID and password are entered. The problem is that the user ID and password are only used to retrieve the original WSDL file, and not the files that it imports.
To overcome this problem, the user can download the WSDL file and all the files that it imports to the workbench first, and then generate skeleton or client from the downloaded WSDL file.

4.23 Problems with using WebSphere v5.0.2 runtime

No support for WSDL: Adding WSDL to the endpoint URL of a Web service deployed to the WebSphere v5.0.2, running in the Test Environment or remote server environment, to get the WSDL file for the deployed Web service is not supported. The generated WSDL file can be found under WebContent/WEB-INF/wsdl of the Web project for Java bean Web service and under ejbModule/META-INF/wsdl of the EJB project for EJB Web service. If WSDL serving from a Web project is required, the user can either reference to the copy of WSDL file under WebContent/wsdl of the Web project or create their own location under WebContent and serve the WSDL from the Web project.

Having utility JAR or more than one source folder: When creating Web service from Java bean or EJB, unnecessary files might be generated in the module if there are more than one source folder in the Web project or if the beans are in a utility JAR within the EAR file. Since these generated files already exist in the module (either in the utility JAR or in another source folder), they need to be deleted for the project to compile and for the Web service to function properly. The other workaround is to merge the source folder into one or copy the beans from the utility JAR into the source folder.

Array not supported in RPC/literal: When creating a RPC/literal service, the method signature cannot contain an array in it. If it does, the service cannot be invoked with the generated client code. There is currently no workaround for this problem. Please try to use document/literal or RPC/encoded if possible.

Methods overloading not supported in document/literal: Methods overloading (same method name, different input parameters) is not supported when creating a document/literal service. There is currently no workaround for this problem. Please try to use RPC/literal or RPC/encoded if possible.

WSDL import: WSDL import statement can only have absolute URLs or relative URLs in the same directory. For example, relative import in the following form is not supported:
<import namespace="http://someNamespace/" location="../someFile.wsdl"/>

Binding element before portType element: You will get a "Error in generating Java files and deployment descriptors from WSDL file (detail: duplicate operation name)" when generating client proxy or skeleton from a WSDL file containing binding element before portType element.

Abstract elements: When generating skeletons from a WSDL file with operation that uses abstract elements or types, the generated JavaBeans will not compile.

Types without default JAX-RPC mappings: When generating skeletons from a WSDL file with operations that have inout parameters of types that do not have any default JAX-RPC mappings, the generated implementation bean will not compile. The problem is that when javax.xml.soap.SOAPElement is created from the javax.xml.soap.SOAPFactory, it throws a javax.xml.soap.SOAPException. The implementation bean does not catch or re-throw this exception, therefore, it will not compile.

Same schema type for input and output: When generating skeletons from a WSDL file that uses the same XML schema type for its input/output messages, and fault messages, the generated artifacts do not work at run time. To overcome this problem, do not share XML schema type definitions between input/output messages and fault messages.

XSD element references with minOccurs and maxOccurs: When generating skeletons from a WSDL file, do not use XSD element references with user specified minOccurs and maxOccurs values (<element ref="..." minOccurs="0" maxOccurs="unbounded"/>). Use of such element will result in a java.util.MissingResourceException during server startup.

Emitted bean having different APIs than the service bean: If the emitter generated beans have a different APIs than the service bean when creating a Web service from a Java bean or EJB, you may run into runtime error such as the following:
The method is undefined. Couldn't find a matching Java operation.

Examples of service bean that has different APIs than the generated beans are:

beans with public fields,

boolean fields with getter named getBooleanValue rather than isBooleanValue,

method name with upper case method name

Document literal with wrap on: When creating bottom-up Web service using document literal, by default, the wrap option is turned on. You might run into interoperability problem if you have more than one input with different types or no input at all. The workaround is to use RPC/literal.

Java bean with lower case name or underscore: When you create Web service from a Java bean with lower case file name or underscore followed by a lower case letter, you will get the error:
Error in generating Java files and deployment descriptors from WSDL file with details of getOutputStream() IOException.

Different security configuration: Do not generate Web services with different security configurations into the same module/project. Use separate projects for each Web service.

4.24 Setting up a DADX group with datasource information

If the WebSphere Application Server V5.0 is being used to host a DADX Web service, then the group.properties file for the DADX group should use the following initialContextFactory property:

initialContextFactory=com.ibm.websphere.naming.WsnInitialContextFactory
Also, the web.xml file for the project containing the DADX group needs to have the following added. (Given that the datasource JNDI name is jdbc/hospital.)
       <resource-ref id="ResourceRef_1058550453092">
              <res-ref-name>jdbc/hospital</res-ref-name>
              <res-type>javax.sql.DataSource</res-type>
              <res-auth>CONTAINER</res-auth>
              <res-sharing-scope>Shareable</res-sharing-scope>
       </resource-ref>

4.25 Loading client locator using the Universal Test Client

When the Universal Test Client is unable to preload the client locator class generated by the WebSphere v5.0.2 or Axis runtime, this is because the name of the Java bean class in the service Web project is the same as the name of the SEI class in the client Web project. To workaround this problem:

Remove the client Web project from the workspace

Right click on the client Web project and click "Delete".

Locate the application.xml in the EAR project and double click the file to open up the Application Deployment Descriptor editor. Select the client Web project module and click "Remove". Close the editor and save the changes.

Create the client Web project under a different EAR, where the EAR project name has to be alphabetically ahead of the service EAR project name. For example, if the service EAR project name call "DefaultEAR", create the new EAR project name call "ClientEAR".

Re-run the Web Service wizard.

4.26 Resource preferences not observed

The file overwrite, folder creation and automatic file checkout preference are not observed when creating Web services using the WebSphere v5.0.2 and Axis runtime. Folder creation is always allowed and automatic file checkout is never enabled.
When using the WebSphere v5.0.2 runtime, the WSDL file, SEI and deployment artifacts (serializers and deserializers) are always overwritten. The development artifacts (service bean, complex type beans, holder and helper class) are never overwritten. However, the user will get a warning about overwriting the deployment descriptors if they exist. The user can choose OK to overwrite the deployment descriptors and continue with the scenario, or Cancel to avoid having the descriptors overwritten.

When using the Apache Axis 1.0 runtime, the Axis emitters re-generate every time all the server/client Java files, deploy.wsdd and undeploy.wsdd. WSDL2Java for the service generation scenario will only generate the skeleton implementation file if it does not already exist. If this implementation already exists, it will not be overwritten.

4.27 Problems with using Apache Axis 1.0 runtime

Creating Web services using the Apache Axis 1.0 runtime relies on the Java2WSDL and WSDL2Java emitters provided in Axis 1.0. Support for document/literal and document/literal (wrapped) is problematic in Axis 1.0, therefore the user should use RPC/encoded when creating Web services using the Apache Axis 1.0 runtime.

When defining custom mapping between package and namespace, the wrong default package and namespace appears in the table after clicking theAdd button, the user should overwrite these defaults and enter their own package and namespace mapping.

4.28 Web service sample JSP failed to compile

When generating Web service skeletons or proxies from WSDL that uses the same name for one of its <service> element and <port> element, do not use sample JSPs as the test client. The generated sample JSPs contain errors and will not compile. Any attempt to run the sample JSPs on server will result in an ERROR 500 in the browser indicating that the sample JSPs cannot be loaded, and exceptions in the server console indicating that the servlet container was unable to compile the sample JSPs.

4.29 Error with localhost not defined

The Web Service creation wizard may fail during generation of WSDL if the hostname "localhost" is not defined on the computer. The UTC may also fail to launch successfully if "localhost" is not defined.
In Windows, the following entry must be present in the [INSTALL-DRIVE]\WINNT\system32\drivers\etc\hosts file:
127.0.0.1 localhost
In Linux, the following entry must be present in the /etc/hosts file:
127.0.0.1 localhost

4.30 Permanent Limitations when using IBM SOAP runtime

The IBM SOAP runtime should be use mainly for backward compatibility reasons. It is strongly suggested that you use the Web services wizard with the IBM WebSphere 5.0.2 runtime for all production purposes. When using the Web services wizard with the IBM SOAP runtime, the user may run into the following permanent limitations:

Generating a WSDL document from a Java bean

char and java.lang.Character require you to enter custom mappings since default mappings from char or java.lang.Character to WSDL XSD do not exist.

The primitive wrapper types, java.lang.Boolean, java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float, and java.lang.Double, cannot co-exist with their corresponding individual primitive types boolean, byte, short, int, long, float, and double, across all the input parameters of a service bean. For example, a service bean in which java.lang.Integer and int both appear anywhere as input parameter types cannot be turned into a complete Web service. When an attempt is made to use the Web Service wizard to create a Web service from this type of service bean, a warning message will occur unless the methods containing the primitive types or wrapper types are not selected in the Web Service Java Bean Methods Page of the wizard. However, you must ensure these methods are not selected the first time the Web Service Java Bean Methods page is encountered. Going back to this page and clearing the problematic methods after having seen the warning may produce an incomplete Web service. In this case, the wizard should be restarted so that the proper method selections can be made the first time the Web Service Java Bean Methods page is encountered.

Multi-dimensional arrays are not supported. An alternative in Java is to insert Java beans in between the dimensions. For example, instead of MyType[][], the pattern MyArray[] where MyArray has a property of type MyType[] will work.

A method with an input argument list containing a mixture of DOM Element and simple bean types requires the entry of one or more custom mappings. The Web Services Definition Language (WSDL) Version 1.1 specification supports one encoding style for all input parts (parameters). The Simple Object Access Protocol (SOAP) Version 2.2 runtime does not have default mapping support for DOM Element with SOAP encoding for primitive types and beans with Literal XML encoding.

When configuring a custom mapping, if you try use serializer or deserializer class from the SOAP runtime (that is, classes from package org.apache.soap.encoding.soapenc) and receive the error "the selected serializer/deserializer class cannot be loaded from this project", then soap.jar is most likely not on your Web project build path. To correct the problem, cancel the wizard, use the Web project properties dialog to add WS_installdir\wstools\eclipse\plugins\com.ibm.etools.webservice\runtime\soap.jar to the build path of the web project, then retry the Web service wizard.

Custom mapping is not supported for nested complex types. Although nested types will appear in the mapping page of the wizard, custom mappings for those types will be ignored.

When creating a Web service from a Java class whose interface contains an abstract Java type, the Web service Java to XML Mappings page may incorrectly set the deserializer field for the abstract type to org.apache.soap.encoding.soapenc.BeanSerializer. This will fail at runtime since the deserializer code in the BeanSerializer class will be unable to construct an instance of the abstract type. To avoid this, choose the Custom mapping option for the type if necessary, and change the deserializer field to the name of a class written to deserialize the abstract type.

The Web service tools currently do not support the creation of Web services from Java Beans containing nested inner classes (that is, inner classes defined within a top level class). To work around this problem, you should move the inner classes to top level classes in seperate Java files.

When creating a Web service from a Java bean that uses other Java Beans with properties of type Vector, Hashtable or Map, XSD will be generated with complexTypes containing types "Vector" and "Map" from the namespace "http://xml.apache.org/xml-soap". Because no schema currently exists for this namespace, the XSD Validator will produce errors and warnings like the following:

Error src-resolve: Cannot resolve the name 'xsd2:Vector' to a(n) type definition component.
Warning src-import.0: Failed to read imported schema document 'null'.
These errors and warnings will not interfere with the correct processing of the WSDL and XSD by the Web Services wizards. The "Map" and "Vector" types will be correctly mapped to their Java counterparts. Note that other vendors may have difficulties processing WSDL or XSD containing these types because http://xml.apache.org/xml-soap is not a namespace recognized by the WSDL 1.1 or SOAP 1.1 specifications. To improve interoperability, consider adapting Java collection classes to arrays and beans, and then building Web services from the adapters.

Generating Java artifacts from a WSDL document

Support is limited to one part per input or output element. Multiple logical parts in an input or output message are not supported. The first such part will be processed and the remaining ones will be ignored.

When generating Web service skeletons or proxies from WSDL that uses the type base64Binary from the xsd (http://www.w3.org/2001/XMLSchema) namespace, the Web service runtime will actually use the xsi:type base64 from the soapenc (http://schemas.xmlsoap.org/soap/encoding/) namespace. In general, the two types are freely interchangeable. However, it is possible the difference between the type in the message and the type in the schema will cause some SOAP protocol runtimes to reject the message. Should this occur, you may hand-craft a serializer similar to Apache SOAP's Base64Serializer but that writes xsd:base64binary instead of soapenc:base64.

Java bean skeletons will not compile if they are created from WSDL documents containing operation and part names that are not valid Java identifiers. The WSDL operation and part names must be valid Java identifiers in order for successful creation of a Java bean skeleton.

The Web services wizards use "http" URIs by default when generating WSDL, however, some WSDL documents from other tools may occasionally employ Web service, SOAP Action or Target Namespace URIs that employ schemes other than "http", such as "urn". When generating proxies or skeletons from WSDL that contain non-http URIs, the Web service wizards may map the URIs to the Java package "com.example" rather than to a more meaningful package. In some cases, the Web service wizards may fail to handle such URIs entirely and produce the error "IWAB0234E An internal error occured."

When generating Java proxies and Java skeletons from WSDL, you now have the option of mapping the XSD intrinsic types boolean, byte, short, int, long, float and double to the "java.lang" wrapper types (eg. java.lang.Integer) instead of to the Java primitives (for example, int). By default, the Web service wizards will map to the Java primitives. To instead have the wizards map to the "java.lang" wrapper classes, open Windows -> Preferences -> Web Services -> Code Generation and check "Map simple XML data types to java.lang wrapper classes."

When specifying a custom mapping from a Java type to an XSD type in when creating a Web service from a Java bean or EJB, the Bean class field is automatically set to the full name of the Java type and cannot be edited. When custom mapping a Java array, the Bean class name will be in array form, for example, "java.lang.String[]", and will be emitted as such into the ".isd" and "dds.xml" deployment descriptor files. This form of class name is not processed correctly by the SOAP runtime, and will result in an error similar to the following:
Deployment error in SOAP service http://tempuri.org/webservice.AddressBook: class name java.lang.String[] could not be resolved: java.lang.String[]
As a result, it is not possible to custom map the serializer for a Java array on the service side. A partial workaround is to leave the Serializer class field empty for the custom mapping. This will suppress the generation of the array class name into the deployment descriptor and permit the service to work. Note that the Deserializer class, and the ability to custom map the deserializer, is not affected by this problem and workaround.

Run time considerations

If you select the Web services code generation preference "Enable element-based mapping" and you selected to deploy to a WebSphere Application Server V4, you may get the following entry in the ISD file and dds.xml:
<isd:map
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x=""
qname="x:some-name"
xml2JavaClassName="some-serializer"/>
The XML editor may flag the following error:
The value of the attribute "xmlns:x" is invalid. Prefixed namespace bindings may not be empty.
This is harmless for the WebSphere Application Server V4. However, do not attempt to deploy this dds.xml to other server which uses Xerces 2.x (XML4J 4.x) or higher such as WebSphere Application Server V5. Otherwise, you will get similar Xerces parse error when the server loads the dds.xml file. You should regenerate dds.xml by going through the Web service scenario and selecting the right server type. This will generate the correct dds.xml for that server type.
Also, you would get similar Xerces parse error when attempting to deploy Web service from that ISD file. The workaround is to manually edit the file to the following format:
<isd:map
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
qname="some-name"
xml2JavaClassName="some-serializer"/>

When invoking a Web service created from a Java bean or EJB, if you get a SOAPException with a targetException such as:
"java.lang.IllegalArgumentException: Unable to instantiate ..."
the problem may be that the method exposed as a Web service contains a Java bean without a public default constructor as a parameter and/or return type. A public default constructor is required in order for the SOAP runtime to construct the object as part of the deserialization process.

The security file, cl-ver-config.xml and sv-ver-config.xml, currently deployed into the Web project are the files from WebSphere version 4.0 and do not precisely match the DTDs. But the files will work on both WebSphere version 4.0 and WebSphere version 5.0 despite the validation errors complaining that "xmlns:ds" or "xmlns:SOAP-SEC" must be declared.

If the Server Configuration is opened in an editor, Web service wizard may fail to start the server due to Web Service Web project not added to the Server Configuration. Closing the Server Configuration editor will resolve the problem.

ISD Web services

After filling in a custom mapping when creating Java or EJB Web services, the custom mapping information, except the XSD Location URL, is stored in the ISD file. The information is retrieved when creating Web services from that ISD file. Therefore, when creating Web services from an ISD file, in the Web Service Java to XML Mappings page of the wizard, you need to fill in the XSD location URL manually.

4.31 Web service and client using different runtime

If you create Web service from a Java bean or EJB, choosing the IBM SOAP for the service runtime and Apache Axis 1.0 as the client runtime, you may get the error:
WSDL Not found

To avoid the problem, create the Web service first without choosing to generate a proxy. Then create a Web service client from the generated WSDL file.

4.32 Clicking Finish in Web service client wizard

When going through the Web service client wizard, if the user clicks Finish on the Client Environment Configuration page, they'll get the error:
"null" is not resolvable

The workaround is to hit Next in that page and the following page, then hit Finish.

4.33 Selecting router project when creating EJB Web services

When creating Web service from EJB, in the Service Deployment Configuration page, ensure that the Router Project is in the same Enterprise Archive (EAR) as the EJB project. Otherwise, you will not be able to invoke the Web service. For example, if you use the WebSphere 5.0.2 runtime, when you try to invoke the Web service, you will get the error:
Could not find Webservices engine.

4.34 Creating EJB Web services or EJB skeleton using command line

After running EJB2WebService to create an EJB Web Service, the generated EAR cannot be run on Unit Test Environment or remote server in WebSphere Studio if the splitWsdl option is used. The workaround is to copy the whole WSDL directory under META-INF of the EJB project to WEB-INF of the router Web project.

After running WSDL2WebService to create an EJB Web Service with a WSDL that has local import in it, the generated EAR cannot be run on Unit Test Environment or remote server in WebSphere Studio. The workaround is to copy the whole WSDL directory under META-INF of the EJB project to WEB-INF of the router Web project.

4.35 Web services cheat sheet

In the Create,test and validate a WS-I compliant Web Service Cheatsheet and Create a Web Service from a WSDL file CheatSheet, if you are using the HelloService.wsdl file from the wsad_install/wstools/eclipse/plugins/com.ibm.etools.cs.wsdl.content_5.1/examples, please modify the service port location according to the different runtime as follow:
For IBM Soap:
location="http://localhost:9080/HelloWorldSample/servlet/rpcrouter"
For Apache Axis or WebSphere 5.0.2 runtime
location="http://localhost:9080/HelloWorldSample/services/Hello_Port"
If you are importing your own wsdl file, please make sure that the location is set properly according to the runtime selected as mentioned above.

Return to the main readme file