WSDL/XSD to textual gApp Model Conversion

The generator WSDL to gApp takes .wsdl and .xsd files as input and creates .gapp files that use the DSLs Function, Persistence, Basic and Rest. For every .wsdl or .xsd file a corresponding .gapp file is going to be created in the subdirectory gapp.

Object and Purpose¶

Assuming that there are some existing SOAP services or at least some XML data structures defined with XSD and you want to modernize your software stack by implementing web services that use pure HTTP/S as the data transfer protocol and that use JSON as the data format. These new web services then shall provide the same business logic as your existing SOAP services. The .gapp files that are generated by the WSDL to gApp generator are going to be used as input for other generators that create web service implementations and web service clients based on state-of-the-art technologies like for instance Jakarta EE (JAX-RS) or Eclipse Microprofile.

Libraries used for WSDL/XSD Parsing¶

Apache Woden and Apache XmlSchema are used in the generator to parse .wsdl and .xsd files. Any limitation of those libraries represents a restriction for the generator.

Main Mappings of Concepts¶

XSD Type or File	gApp Type or File
.wsdl or .xsd file	a .gapp file (in other words: a module)
`<xs:simpleType>`	type
`<xs:complexType>`	entity
`<xs:element>`	field
`<xs:enumeration>`	entry (member of enumeration)
`<wsdl:operation>`	function
`<wsdl:input>`	in (parameters of a function)
`<wsdl:output>`	out (parameters of a function)
`targetNamespace`	the gApp module/file’s namespace

Every generated function gets some REST-… options set:

...
function MyFunction {
    set REST-Operation = POST;
    set REST-Path = "myfunction";

   ...
}
...

These options are needed by other generators that generate web services for the given gApp model files.

Note

The options have the prefix REST-, but the input model doesn’t really define a RESTful webservice. On the internet you find dozens of discussions about what is RESTful and what isn’t RESTful . Please read these discussion if you want to know more about the difference. We won’t hold that discussion here.

Prerequisites and Limitations¶

WSDL Version 1.0/1.1 vs 2.0¶

The generator can only process WSDL 2.0 files. When you use WSDL 1.0/1.1 as input files, the generator automatically converts them to the 2.0 format first. If that conversion raises errors, the generation stops and the errors are displayed.

Unsupported Constructs¶

WSDL and XSD lets you define a great many of different data structures, restrictions and operations. The WSDL to gApp generator supports a growing number of scenarios but doesn’t claim to be complete. If you find unsupported definitions, please report them to us.

XSD Namespaces¶

Certain .xsd files won’t work, depending on their namespace settings. The following example won’t work:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
...
</xs:schema>

However, when you define a targetNamespace and a default namespace (xmlns=…), the generator runs successfully:

<schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://dummy"
        xmlns="http://dummy">
...
</schema>

Any .xsd file must have a targetNamespace defined, otherwise the generator will raise an error.

Note

The namespace definitions are only needed to parse the .wsdl and .xsd files. The targetNamespace attribute is an exception from this rule. Its setting becomes a gApp module/file’s namespace.

Unsupported WSDL Tags¶

When the .wsdl file contains a <wsp:Policy> tag, the generator will raise an error. Simply remove that tag from the input file prior to runing the generator.

Number of Input Files¶

Only one .wsdl file is allowed as input. If you provide more than one .wsdl file, the generator will raise an error. Multiple .xsd files are allowd, though. Imports of .xsd files work fine, too.

XSD Annotations¶

Certain usage of <xs:annotation> is not supported and lead to generation errors. Simply remove the <xs:annotation> or comment them in order to make the generation succeed. The following cases are not supported:

annotation on the top level of a .wsdl file¶

<wsdl:definitions 
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema" 
   ...>

<xs:annotation>
  <xs:appinfo>W3Schools Note</xs:appinfo>
  <xs:documentation xml:lang="en">
  This Schema defines a W3Schools note!
  </xs:documentation>
</xs:annotation>
...
</wsdl:definitions>

annotation within the `binding` tag in a .wsdl file¶

<wsdl:definitions 
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema" 
   ...>

...
    <wsdl:binding>
      <xs:annotation>
          <xs:appinfo>W3Schools Note</xs:appinfo>
          <xs:documentation xml:lang="en">
          This Schema defines a W3Schools note!
          </xs:documentation>
        </xs:annotation>
    ....
    </wsdl:binding>
</wsdl:definitions>

Location of multiple Input Files¶

When you have more than one input file, those input files have to be located in the same directory.