Creating Web services with the IBM SOAP run-time environment

This run-time environment was the only Web service run-time environment supported in previous releases of WebSphere Studio (version 5.0 and earlier). This run-time environment supports Apache SOAP 2.3. It should only be used for backward compatibility reasons.

 

Limitations

Limitations of using the IBM SOAP run-time environment with Web services are listed below. For a complete list of limitations, refer to Limitations.

• Interoperability with the IBM SOAP run-time environment
  • If the "Enable element-based mapping" preference is not enabled (this preference can be found at Windows > Preferences > Web Services > Code Generation), which is the default, the Apache/IBM SOAP run-time environment may not interoperate with other vendors' Web service run-time environments that send messages whose elements do not have "xsi:type" properties. For more information, refer to Setting Web services preferences

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

• Bottom-up Web services development
  • After using the Web services wizard to create an IBM SOAP 2.2 Web service bottom-up from Java, you may get the message Duplicate key value [...] declared for identity constraint of element "definitions". This occurs when the tools for IBM SOAP 2.2 generate two WSDL files, one importing the other, with the same targetNamespace.

  • Java bean properties must have both getters and setters in order to work properly as a Web service using the IBM SOAP run-time environment. Without all getters and setters, properties may not be generated into the schema resulting in runtime serialization and client generation issues. Ensure that all properties contain getters and setters.

  • 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, 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 run-time environment 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 run-time environment (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\run-time environment\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 run-time environment 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.

• Top-down Web service development
  • 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 run-time environment 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 run-time environments 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 Window > 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 run-time environment, 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 run-time environment 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 you create a bean which uses two different complex types from the same package, when you create a SOAP-based Web service from this bean, an XSD file is created for each complex type and is given the same namespace. This results in validation errors in both the Task list and the Web Services Explorer.

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

Creating a Web service from a Java bean using the IBM SOAP run-time environment
The Web Service wizard assists you in creating a new Web service, configuring it for deployment, and deploying the Web service to a server. Once your Web service is deployed, the wizard assists you in generating the client proxy and sample application to test the Web service. When you have completed testing, you can publish your Web service to a UDDI Business Registry using the Export wizard.

Creating a Web service from a DADX file using the IBM SOAP run-time environment
Document Access Definition Extension (DADX) is an XML document format that specifies how to create a Web service using a set of operations that are defined by DAD documents and SQL statements. A DADX Web service enables you to wrap DB2 extender or regular SQL statements inside a standard Web service. The DADX file defines the operations available to the DADX run-time environment, and the input and output parameters for the SQL operation.

Creating a Web service from a URL using the IBM SOAP run-time environment
The Web Service wizard assists you in creating a new Web service, configuring it for deployment, deploying the Web application, testing your new Web service, creating a sample application, and publishing the Web service to a UDDI Business Registry.

Creating a Web service from a Web service deployment descriptor (ISD) using the IBM SOAP run-time environment
An ISD file is a Web service deployment descriptor. A deployed ISD file provides information to the SOAP run-time environment about the services that should be made available to clients for example URI, methods, classes, serializers, and deserializers.

Creating a Java bean skeleton from a WSDL document using the IBM SOAP run-time environment
The Web Service wizard assists you in creating a skeleton bean from an existing WSDL document. The skeleton bean contains a set of methods that correspond to the operations described in the WSDL document. When the bean is created, each method has a trivial implementation that you replace by editing the bean.

 

Related Concepts

Web services
Tools for Web services development

Related Tasks
Developing Web services