|
|
Introduction Implementing Other Uses Parts Tutorial Glossary
WSDL (Web Service Description Language) is a language for creating formal descriptions of web services.
A WSDL document includes information, that makes it possible for a number of programming tools to generate the structures and calls needed to communicate with the web service, this includes:
This document describes the necessary steps for creating a WSDL document for a web service defined with TransacXML.
The WSDL files created by TransacXML conform to WSDL 1.1.
More information about WSDL can be found at http://www.w3.org/2002/ws/.
The Basic Profile contains clarifications and amendments concerning the WSDL specifications.
The generated WSDL files will typically be used by another tool to generate the calls to the web service described by the WSDL file. The WSDL and Schema specifications are very versatile and flexible and the same thing can be expressed in different ways, so there will rarely be an unique WSDL file for a given web service. This means that even though a WSDL file is valid and correct according to the WSDL specification it is not guaranteed that all tools will be able to import the WSDL file without modifications.
During the tests we have found some cases, where some tools have problems using, or are unable to use, the generated WSDL files. These problems are listed in this section.
The web services defined by TransacXML use the "document literal" binding. One of the consequences of this is that the input to one XmlHandler is only allowed to consist of one document (one top element).
However, it is possible to imagine a web service, which as input can receive different documents based on the reason for calling the XmlHandler. This would correspond to choosing more than one document for the input role for an XmlHandler in the Handle XMLHandlers grid described below.
CreateWSDL allows the creation of WSDL files based on the selection of multiple input documents for an XmlHandler.
However, we have found that some code generators (e.g. .NET wsdl.exe import) does not handle the generated schema structure and does not create the necessary classes in this case with multiple input documents. Other tools like XMLSpy handle this to some degree, but in general it is recommended to define only one input document per XmlHandler.
The Basic Profile recommends that all top elements of documents used as input or output has a namespace; as it is expressed in the profile: "this avoids the cases that are not as clearly defined as they might be". We have found that some tools (e.g. .NET wsdl.exe import) do not create any classes based on documents without namespaces.
Therefore we strongly recommend that all documents, which are to be used as input and/or output for an XmlHandler, is defined as belonging to a namespace, even though the CreateWSDL function is capable of creating valid WSDL files for documents, which does not belong to any namespace.
The handling of namespaces in TransacXML is described here.
As can be seen from the following implementation example, the CreateWSDL function creates several files - one WSDL file and one or more schema files. In one context, this has posed a slight problem. Calling the .NET wsdl.exe import function from a command prompt, we found it necessary to not only enter the WSDL file to be imported, but to also enter all of the schema files used; otherwise the wsdl.exe was unable to import the WSDL.
The following section will contain an example showing how to create a WSDL file for the DistributorA web service described in the Web Service Tutorial. In order to follow this implementation guide, it is necessary to first complete the Web Service Tutorial.
All of the XMLElement entities, which are part of the documents used by the web service, must inherit from XmlElementWithServiceFunctions.
| CommonXml.ItemList | is a ENT | XmlElementWithServiceFunctions |
| CommonXml.ItemList.Item | is a ENT | XmlElementWithServiceFunctions |
| CommonXML.ReturnOffer | is a ENT | XmlElementWithServiceFunctions |
| CommonXML.ReturnOffer.Item | is a ENT | XmlElementWithServiceFunctions |
This adds a CreateSchema function to each XMLElement entity.
The WSDL generation needs information about which documents the XmlHandler functions use as input and/or output.
The connection between an XmlHandler and the input/output documents used by the XmlHandler is specified by letting the XmlHandler comprise the CreateSchema function scoped by the top XMLElement entity for the input/output document (use the triple FNC comprises FNC).
In this example the ReturnList XmlHandler receives no input document and generates the ItemList document as output while the ReturnOffer XmlHandler receives an ItemList document as input and returns a ReturnOffer document as output.
This results in the following triples:
| DistributorA.Services.XMLHandlers.ReturnList | comprises | CommonXML.ItemList.CreateSchema |
| DistributorA.Services.XMLHandlers.ReturnOffer | comprises | CommonXML.ItemList.CreateSchema |
| DistributorA.Services.XMLHandlers.ReturnOffer | comprises | CommonXML.ReturnOffer.CreateSchema |
Whether the document is input or output is specified during the execution of the CreateWSDL function.
A number of service functions must be generated and built. Some of these service functions have already been built during the implementation of the web services example. If this is the case, it is not necessary to generate and build these objects again.
For general instruction on how to configure the Plex model and what objects to generate and build, please refer to this document.
Generate and build the functions contained in the library subject areas:
WSYDOM/DomObjectsToGenerateAndBuild
SDSTRING/SDStringObjsToGenerateAndBuild
WSYXML/SchemaObjectsToGenerateAndBuild
WSYSOAP/WSDLObjectsToGenerateAndBuild
The CreateSchema and GetName functions scoped by the XMLElement entities must be generated and built, as they are called during the execution of the CreateWSDL function.
Generate and build the CreateSchema and GetName functions scoped by the XMLElement entities, which are part of the involved documents.
The following functions should be generated and built:
The CreateWSDL function and the scoped HandleXMLHandlers function are the main functions for the WSDL creation.
Generate and build the CreateWSDL function scoped under the SoapProcessor and it's scoped HandleXMLHandlers function.
The functions are:
By default the CreateWSDL and HandleXMLHandlers functions are set to implement No. Before you can generate and build these functions you must override this by specifying an implement Yes triple on each function.
A bug in the Plex Java runtime means that if the CreateWSDL function is called directly, the panel functions will terminate without giving you the opportunity to enter any data. To avoid this you must make a function calling the CreateWSDL function:
| MyStartWSDL | is a FNC | StartWSDL |
| MyStartWSDL | replaces FNC
...by FNC |
HttpSoap.Services.SoapProcessor.CreateWSDL
DistributorA.Services.SoapProcessor.CreateWSDL |
Generate and build MyStartWSDL.
When running the CreateWSDL/MyStartWSDL function, the following panel will be shown:
Service Name:
The public name of the web service. According to the WSDL specification this name must be a NCNAME. This means that not all characters are allowed in the web service name; e.g. spaces and special characters.
Service URL:
The URL used for contacting the web service.
Path and Filename:
Enter the full path to the file where the WSDL document should be saved. The directory must exist, while the file is created if it does not exist. If the file does exist it will be replaced.
It is recommended to use the .wsdl file extension, as this identifies the file as a WSDL file to a number of applications.
Target Namespace:
The Target Namespace for the WSDL document. The default is the Service URL which will do fine in most cases - but you can overwrite it if you wish.
An example of a panel with values entered is shown below (the exact values to use depend on the setup):
The information entered on the panel above is common information for all of the XmlHandler functions (SOAPActions). After pressing OK, the handling of the XmlHandlerfunctions will start. For each XmlHandler the following panel will be shown twice:
The top of the panel shows the SOAPAction and the scoped name of the XmlHandler.
The Grid shows all of the documents, which are comprised by the XmlHandler.
This panel will be shown twice for each XmlHandler, once where the input documents are selected, and once where the output documents are selected. The role (input or output) to be selected is shown just above the grid. A document can be used as both input and output.
The three buttons gives the following results:
Select:
The selected documents from the grid are declared as input/output for the XmlHandler.
None:
There are no documents for the role (input/output).
Exclude:
The XmlHandler is excluded from the WSDL file.
(Please note that the text just above the grid specifies that it is the input documents, which must be selected).
The ReturnList function has no input document and therefore "None" should be pressed.
As mentioned, the panel is shown again:
The CommonXML.ItemList document should be selected, as this is the output document.
The panel will then be shown twice for the ReturnOffer XmlHandler. The ItemList document should be selected as input and the ReturnOffer document should be selected as output.
After this, the function will terminate and the WSDL file has been created and saved to the specified location.
In addition to the WSDL file, one or more files containing schemas are created (one for each selected input/output document). These schema files are placed in the same folder as the WSDL file.
For the example used here, the following files will be created:
MWS.wsdl
MyWebService001.xsd
The MWS.wsdl file contains the WSDL file describing the interface of the web service. The MyWebService001.xsd contains the schema definitions for the input and output documents.
The documents belong to the same namespace, which means that only one schema file is created. If the documents had belonged to different namespaces, a schema file would have been defined for each namespace.
The WSDL file and its corresponding schema files must be located in the same folder. If you want to change this, you will have to manually change the schema location attribute in the import elements found in the schema section of the WSDL file.
If a document used for input or output by an XMLHandler contains elements belonging to more than one namespace a further step occurs during the execution of the CreateWSDL function.
The CreateWSDL function calls the CreateSchema functions for the document selected in the Handle XMLHandler's Grid.
As described in the Create Schema Guide a schema can only contain information about one namespace, so whenever the CreateSchema function encounters additional namespaces, it shows a Prompt panel, where the location of the schema must be entered.
This functionality is described in detail in the Create Schema Guide
One additional schema file will be created for each namespace.
If errors occur during the execution of the CreateWSDL function, the program terminates without saving the WSDL file.
The field CreateSchemaErrorDescription in the variable Output/Error will contain information about the function, which has thrown the error and, if possible, a textual description of the error.
When the CreateWSDL function is executed from the generate and build window error messages can be seen by inserting the following code in the post point Start terminate in the called CreateWSDL function:
If
Output/Error<CreateSchemaErrorDescription> !=
<CreateSchemaErrorDescription.*Blank>
Cast Environment<*Message text>,
Output/Error<CreateSchemaErrorDescription>
Dialog Message Message: OBJECTS/Message
Online documentation - Websydian v6.5