|
|
The WSDL import tool models the XML structures that are necessary for connecting to a web service.
The most common structures are naturally the documents used as input and output when calling the service.
However, the WSDL can also describe other structures, such as fault and header structures.
The WSDL import is basically an extension of the W3C schema import - with added functionality to parse the WSDL and extract the schema definitions contained in the WSDL.
Run the WSDLImportGUI.exe file to import a WSDL file. This launches this panel:
Specify the location of the file containing the W3C schema in the input field "WSDL file".
Either specify a file location or specify a URL containing the location of the file on a web server.
If you use the Browse button to select the file, the tool processes the WSDL automatically.
Press the "Process" button to parse the WSDL if you have not used the Browse button to select the file.
In some cases, the WSDL import must extract a schema file from the WSDL and save it to a file to be able to load it correctly for the schema import.
Specify where the tool must save these temporary file in the setting "Folder for temporary files".
To be able to handle RPC-encoded WSDLs, the import tool needs access to the W3C-schema for schemas and for SOAP-encoding.
The schemas are delivered as part of the installation. The default settings for the two schema locations points to these delivered schemas.
If you want to use the schemas the W3C organization makes available instead, specify the URLs shown below. (The schemas should be the same - so to get the best performance we recommend that you do not change the default locations).
Shows basic information about the tool - it also provides a link to the current version of the documentation.
After parsing the WSDL, the tool shows the content of the WSDL as a tree-structure:
The topnodes (E.g. WebsydianDemo) correlates to a URL (hover the mouse over the servicename to show the URL).
The childnodes are the operations you can access for this service. These operations correlates to SOAPActions (hover the mouse over the operationname to show the SOAPAction).
Press the "+" shown for an operation to see the messages used by the operation (hover the mouse over the message to show the type of the message):
Each operation can use the following message types:
In most cases, only input, output and possibly fault will occur.
You must import each message in a separate step. You start the import simply by double-clicking the message node.
This launches the schema import for the schema definitions referred by the WSDL message.
This panel shows the name of the topelement that will be imported (Element to import as...). This will become the name of the top XMLElement entity created in Plex.
The "Save file to" field defaults to the folder that has been specified as the temporary files folder and the filename defaults to pleximport.xml.
If you want to specify another folder/file, you can do so.
The tool generates a "FLD limits all" triple for each field it creates if you leave the "Create Limits All triples" checkbox checked.
If you uncheck the checkbox, the tool does not assign any "limits all" triples.
Keep the "Use inheritance specific for input messages" checkbox checked, to specify a separate inheritance for each message type (one set of settings is stored for input, another for output, etc.).
When the checkbox is checked, the tool loads and saves a set of settings for each messagetype.
Press the "Generate" button to create the Plex import file.
In some cases, you want to specify inheritance specific to each messagetypes.
For example if you are going to call a web service, you will normally only create the input documents - and only read the output documents.
By creating your own abstract entities MyXMLElementInput, MyXMLRepeatingElementInput , MyXMLElementOutput, and MyXMLRepeatingElementOutput in your Plex model, you can control which of the functions scoped by the XMLElement entity to generate and build.
For MyXMLElementIntput and MyXMLRepeatingElementInput, you can set InsertRow and InsertRowDangling to implement No, as you are not going to create these documents.
For MyXMLElementOutput and MyXMLRepeatingElementOutput, you can set GetFirstOccurrence and SingleFetch to implement No, as you are not going to read these documents.
When you work with large/complex documents, this can save quite a lot of generation/build time.
To make the import use these new abstract entities, do the following:
Open the inheritance grid on the schema import panel when importing the first input message you are going to handle. Change the values as shown below:
After changing the settings, press "Save Settings". This inheritance will be assigned to all the entities created for the input messages will have (as long as the "Use specific inheritance for input messages" are checked).
Do the same when importing the first output message.
You can of course do the same for the other messagetypes (fault, input header, input header fault, output header, output header fault).
Uncheck the "Use inheritance for..." checkbox and specify the inheritance in the grid if you do not want to use specific inheritance for each message type, but still want to use your own abstract Plex objects. As long as the checkbox is unchecked, the import will use these settings. (Remember to press "Save Settings" to avoid having to define the settings for each message.)
The WSDL used in example above is a document/literal service.
Version 2 of the import tool also provides import of RPC-based services.
The import itself is performed in much the same manner as when you are importing a document-based service - but there are some slight differences.
The information shown when the WSDL has been processed is a bit different:
In addition to the information about the service/URL, the operation and the message, the tool shows an additional level showing the parts of the messages. The additional information is the name of the part and the declared type of the part.
Hover the cursor over a part to show the namespace the part belongs to.
You trigger the import itself by double-clicking the message node - just as for document/literal services.
This opens the same panel as for document/literal services - and the further handling is exactly the same.
The one difference you will see is that is the message scopes a lot of parts, the time necessary for generating the Plex import file will be significantly longer - as each part has it's own schema that must be opened and parsed.
Just as for the document/literal services, the generated Plex import file will contain the Plex definitions for a XML-document.
The definitions follow these rules:
The name of the request document is set to the name of the operation.
The name of the response document is set to the name of the operation followed by "Response".
For each part, the corresponding structure is created as a child of the document.
Just as for the document/literal services, the generated Plex import file will contain the Plex definitions for a XML-document.
The definitions follow these rules:
The name of the request document is set to the name of the operation.
The name of the response document is set to the name of the operation followed by "Response".
For each part, the corresponding structure is created as a child of the document - the structure will contain encoding information based on the definitions from the WSDL.
For each part, that refers a simple type, the resulting Plex field will inherit from EncodedField, and the source codes are populated based on the definition of the part in the WSDL.
For each part that refers a complex type, the resulting Plex field will inherit from EncodedElement, and the source codes will be populated based on the definition of the part in the WSDL.
The limitations described for the schema import are also valid for the WSDL import.
The import only supports WSDL 1.1.
The WSDL standard defines the possibility to import other wsdl files using an import element belonging to the wsdl namespace (http://schemas.xmlsoap.org/wsdl/). The tool does not support this.
Please note that the import statement in the schema namespace (http://www.w3.org/2001/XMLSchema) is supported.
In general, the tool handles import elements found inside a <schema>...</schema> nodes while it does not handle import elements found outside the schemas.
The tool only supports the SOAP 1.1 binding.
If other bindings (e.g. HTTP, SOAP 1.2) are used in the WSDL, the operations will not be shown in the tree-structure.
The tool only supports http as transport.
If any other transport is specified, the operations will not be shown in the tree-structure.
The import supports document/literal, rpc/literal and to some extent rpc/encoded messages.
The soap-encoding scheme describes an array structure as an extension to the normal W3C schema definitions.
The tool resolves the array structure itself, but as the array structure is not part of the standard W3C schema definitions, the content of the array will not be resolved based on the WSDL.
In most situations many cases, the arrays only contain simple elements of one specific type. To make it as easy as possible to handle this situation, the tool adds an encoded field to the array.
If the array contains more that one type of simple element or contains complex elements, you must add the modeling for these array elements manually in the imported Plex definitions.
The WSDL standard allows a reference from a message part to a schema definition using the element attribute of the part element. However, it is not clear exactly how this should be interpreted for a rpc/literal message.
The tool will import this structure, but it can't be guaranteed that the interpretation of the WSDL is the same as the service providers. However, we have chosen to make a "best guess" import anyway, as the imported structures should be useable - even if they might need some manual changes before calling the service.
Example:
In one special case, this construct will lead to an error when the generated schema is imported using the schema import.
This error occurs when the name of the part is the same as the name of the referred element - and the namespace of the element is the same as the target namespace.
The reported error is:
The global element '[Namespace]:[Name]' has already been declared.
(Where [Namespace] will be the namespace of the element and [Name] will be the name of the element).
This will make it impossible to import the generated schema.
However, there is an easy workaround.
In the WSDL-file change the name of the referred element in the part declaration and in the schema.
So if you have the following situation (where the Request
message contains an part named MyElement that refers an element
named MyElement - both in MyNamespace):
You can change the name of the referred element in the message/part definition and in the schema:
After this, you will be able to perform the import.
The tool only supports import of types using the W3C schema format.
The WSDL standard does not limit how you can describe the data content of the messages. You could actually invent your own "schema-language", use this to describe the data - and still claim to be compliant with the WSDL standard.
However, all real-life applications we have encountered use W3C schemas to describe the data-content.
The WSDL standard contains a number of unclear points. There are even some cases where the textual descriptions and the schemas describing the WSDL and SOAP formats are different. In the cases where these inconsistencies have relevance for this tool, we have followed the clarifications made in the WS-I Basic Profile.
Online documentation - Websydian v6.5