Working with SOAP Services · WaveMaker Docs

SOAP (Simple Object Access Protocol) is a standard XML protocol for exposing and calling web services. A SOAP service is described by a Web Services Definition Language (WSDL) document, often available through a URL from the service itself.

In order to import a SOAP service into your WaveMaker application, you need the .wsdl file that describes the service. You can see here for some free web services.

Once you have located the WSDL file, follow these steps to import the same:

SOAP Service Setup

From Resources, choose Web Service and click +

From the Web Service dialog, click the SOAP icon
Give the Soap Service details.
Provide the WSDL source in one of the following ways:
- URL: Toggle WSDL Source to URL and enter the URL of the WSDL, for example: http://www.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL
- File: Toggle WSDL Source to File and click Choose File to upload the .wsdl file from your local machine. The file can be an individual file or a group of files packaged into a zip file.
Advanced Settings include the optional items:
- option to import bindings .xjb file to map Java classes to XML representations.
- service name, if not entered it will be generated by the platform
- package name, if not entered it will be set to the project package

See here for more on the Import Settings.

note

Only Doc - Literal and DOC-Encoded communication style models are supported within WaveMaker.

SOAP Service Settings

Clicking Import will create a new service which is displayed under Web Services.
Select the service name listed under the SOAP Service section and you can access the WSDL File and Service Settings.
You can choose to edit, save or delete the service.

The HTTP Basic Auth settings for the service can be configured by providing the Username and Password.
Connection Timeout is a value specified in milliseconds used when opening a connection to a resource. If the timeout expires before the connection is established, then java.net.SocketTimeoutException is thrown. The default value is 10000. Zero indicates infinite timeout value.
Request Timeout in milliseconds specifies the timeout when reading from an input stream after the connection is established to a resource. If the timeout expires before data is read, then java.net.SocketTimeoutException is thrown. The default value is 10000. Zero indicates infinite timeout value.
You can view the WSDL code from the WSDL File tab.

Generated REST APIs

For each method defined by the SOAP service, a REST API is generated. You can view the API definition, request and response formats and even test the same before using it within the app. You can achieve all this from the API Designer.

SOAP Service Usage

To use the Service data within the app, you need to create Variable.

We have seen how SOAP service can be imported and used within a WaveMaker app. Learn more about Variables for the Web Services from here.

Reimport of SOAP Service

There might be a need when the SOAP Service you have been using has undergone some changes which you need to incorporate in your app. To cater for such situations, Re-import of SOAP Service has been introduced.

Using this option, you can achieve the following:

Change the WSDL Source
Remove the Bindings File, if provided
Upload a new Bindings File, if provided
Modify the Package Name
Download a previously uploaded WSDL File and Bindings File

SOAP Import Settings

Zip File import

While importing the SOAP service you can upload the zip file that contains the WSDL file along with all its dependent schema files. The contents of the zip file should be:

One WSDL at the root level folder.
Optional external dependent schema files at the same level or in child folders which are relatively referred in WSDL file.
Optionally xjb bindings file which helps in avoiding the model class collisions in code generating by separating the packages/altering the class names. Explained more in below sections.

Package Name Customization

By default package name is set to the project base package name by the platform as <project-base-package-name>.services.<service-id-of-soap-being-imported>. You can provide an optional package name so that the generated sources will be created in that package.

Avoiding Name Collisions

Name collisions happen while code generation when there is more than one schema definition with the same name that can be from two different external schema files.

Following example depicts the collision of element “root”, because this element is defined twice in two different namespaces:

<wsdl:types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns="http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd" 
      **targetNamespace="http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd"** 
      elementFormDefault="qualified" attributeFormDefault="unqualified">
        <xs:element name="advFormat" type="xs:string"/>
        **<xs:element name="root">**
         <xs:complexType>
          <xs:sequence>
            <xs:element ref="ns0:advFormat" minOccurs="0"/>
          </xs:sequence>
         </xs:complexType>
        </xs:element>
        </xs:schema>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd2"
           **targetNamespace="http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd2"** 
           elementFormDefault="qualified" attributeFormDefault="unqualified">
          <xs:element name="path" type="xs:string"/>
          **<xs:element name="root">**
           <xs:complexType>
            <xs:sequence>
             <xs:element ref="ns1:path" minOccurs="0"/>
            </xs:sequence>
           </xs:complexType>
          </xs:element>
        </xs:schema>
</wsdl:types>

These collisions can be avoided either by implicit handling by the platform or manual handling using an xjb file.

Implicit handling of name collisions

In implicit handling, the system automatically resolves the bindings by providing the unique package name for each namespace, this package name is prefixed with service package name. However, there is a limitation in implicit handling that is it cannot handle the collisions that happen with definitions within (inline) the WSDL file.

Manual handling of name collisions

In manual handling, you have to write an xjb file which defines the customization of packages/class names while code generation. This xjb file can be included while importing the soap service using the following options (in the order of their priority):

Upload through the Bindings XML option from UI
As a part of the uploaded zip file

Writing XJB files

XJB bindings can be customized by defining separate <jaxws:bindings> element for each namespace, which selects the node with given targetNamespace within the WSDL document.

<jaxws:bindings node=">wsdl:definitions/wsdl:types/xs:schema[@targetNamespace='http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd'"

Inside the <jaxws:bindings> element should define which describes customization of package names/class names in code generation for selected node:

Suffixing all the classes generated from the schema

  <jaxb:schemaBindings>
     <jaxb:nameXmlTransform>
       <jaxb:elementName suffix="Foo"/>
     </jaxb:nameXmlTransform>
  </jaxb:schemaBindings>

Changing the package name for generated classes from the schema

  <jaxb:schemaBindings>
       <jaxb:package name="com.services.test.custom"/>
  </jaxb:schemaBindings>

Example

Custom xjb file

<?xml version="1.0" encoding="UTF-8"?>
<jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
       xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" version="2.1"
       xmlns:xs="http://www.w3.org/2001/XMLSchema">
       <jaxws:bindings
         node="wsdl:definitions/wsdl:types/xs:schema[
            @targetNamespace='http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd']">
        <jaxb:schemaBindings>
         <jaxb:nameXmlTransform>
          <jaxb:elementName suffix="Foo"/>
         </jaxb:nameXmlTransform>
        </jaxb:schemaBindings>
       </jaxws:bindings>
       <jaxws:bindings
         node="wsdl:definitions/wsdl:types/xs:schema[
            @targetNamespace='http://www.xyz.com/schemas/CustService/Services/Schemas/Schema.xsd2']">
        <jaxb:schemaBindings>
          <jaxb:nameXmlTransform>
           <jaxb:elementName suffix="Bar"/>
          </jaxb:nameXmlTransform>
        </jaxb:schemaBindings>
       </jaxws:bindings>
</jaxws:bindings>