|
|
This document introduces examples of the different SOAP
messaging formats that can be described in WSDLs, where to find the
information in the WSDL, and the use of these formats in Websydian
TransacXML applications.
This is a non-exhaustive introduction. If you need the normative
and elaborate descriptions, you will need to go through the SOAP
and WSDL standards. If you do that, we recommend that you also get
familiar with the Basic Profile which clarifies a lot of
inconsistencies in the standards.
The WSDL standard describes a concept called “style”. The style
indicates whether the message contains parameters and return values
(RPC style messages) or whether the message contains documents
(document style messages)
The RPC style is meant to be used for remote procedure calls.
The idea is to use this format when an existing function is to be
provided as a web service.
It is important to notice that the payload of the SOAP message
still is a valid XML document – the RPC style just provides a
connection between the format of the interface and the structure of
the XML document.
The top element (FunctionName) will be named after the function
that is being provided as a web service. Each child element of the
top element (Parameter1 – Parametern) is a parameter
for the function.
In many cases, the name of the parameters are non-essential, the
sequence determines which function parameter will be mapped with
the specified value. See examples below.
The idea of the RPC style is to make it straight-forward to provide
a function as a web service – and ultimately make it possible for
development tools to do so automatically.
Where the RPC style messages can be mapped directly to a
function interface, the document style messages have no such
restrictions. This makes more complex messages possible.
The document style message offers more freedom in the selection of
the document format than the RPC style. At the same time, it hides
the interface of the function that is being made available as a
service – thus making it easier to change the function without
having to change the existing service.
In addition to the style concept, the WSDL standard also describes a “use” concept. This indicates whether the message parts are encoded, or whether the parts are defined by a schema.
Literal messages simply means that the format of the message is
described in an external schema – often as part of a WSDL. It also
means that the message itself does not contain any specifications
of the message content.
The WSDL standard itself does not mandate the format of the schema
describing the message, but the de-facto standard is to use W3C
XML-schemas. Using W3C XML-schemas as the external description of
the document format makes it easy to check whether the documents
that are exchanged are valid.
Encoded messages contain information about the content of the
message itself. The normal use for this is for RPC documents, where
the encoding describes the data-type of each parameter.
As encoded messages don’t refer to any external schema, it can be a
problem to validate whether the document is correct according to
the decided contract of information exchanged.
The messaging format is the combination of the use and the style used by the service. By combining the use and style, you get the following four formats:
This format is used when a service is to be called with a
document that is described externally. The document can have any
complexity and it does not have any relation to a function
interface.
We recommend that you always use document/literal when possible,
and that you encourage other parties to do the same, as
document/literal ensures superior interoperability e.g. for
services which are to be used by several clients/partners.
Example – SOAP document/literal request:
This format is not used.
This format is rare, but it does occur.
This format is used when the message relates to a parameter
interface. Each part (parameter) of the message is described in an
external schema.
The name of the top element of the body document specifies the
function to call, while each child of this element specifies a
parameter for the function.
All RPC/literal services can be implemented as document/literal
services without changing the message itself.
Example – SOAP RPC/literal request:
The format is quite widely used.
This format is used when the message relates to a parameter
interface. Each part of the message contains a “type” attribute
that describes the content.
The name of the top element of the body document specifies the
function to call, while each child of this element (parts)
specifies a parameter for the function.
The format is disallowed by the Basic Profile. The Basic Profile
describes best practices and recommendations for developing
interoperable web services.
We recommend that you only use this format when you absolutely have
to, typically when you have to consume an existing service from
another party who has decided on this format.
One of the issues with the RPC/encoded format is that the SOAP
standard describes a “SOAP-encoded array” to handle the case where
one or more parameters are multi-occurrence structures. Use of
these arrays compromises interoperability as some tools don’t
handle these structures – and the tools that do seem to implement
the arrays in different ways.
Example – a simple SOAP RPC/encoded request:
The use and style attributes for a service can be found in the
binding section of the WSDL.
The example below defines two different operations (functions)
ReturnList and ReturnOffer, the style attribute (document) is
defined in the soap:binding element – so it is valid for both
operations. Both operation has an input and an output message –
both messages are specified as having the “literal” use.
The style can also be defined for each operation (in the
soap:operation element). This means that you can described both
document and rpc operations in the same binding.
The use can also be defined for each operation (in the
soap:operation element). This means that you can define that all
the messages used for the operation is either literal or
encoded.
When working with web services, you always have to distinguish
between being the provider and being the consumer of the web
service.
When you provide the web service, you have to be able to make the
service available for the consumers, and you must be able to
generate a WSDL file that enables the consumers to call the
service.
As a provider, you will normally have the option to determine which
format the service should have.
When you consume the web service, you should be able to import the
WSDL file, and based on these definitions call the service. As a
consumer you will normally not be able to determine the format of
the service. Usually you will have to just implement the format
defined for the service by the provider.
Document/literal
All services provided using TransacXML are document/literal
services. TransacXML can generate WSDL files for these services
based on the Plex definitions – all WSDL files generated by
TransacXML describes the services as being document/literal.
RPC/literal
As all messages used for RPC/literal services can be defined as
document/literal messages, TransacXML is capable of providing
services that has been defined as RPC/literal services. However, if
you generate a WSDL for the service, it will describe the service
as a document/literal service.
RPC/encoded
TransacXML is capable of providing most RPC/encoded services –
but it will take often take some effort to get the definitions
right in the Plex model.
TransacXML cannot generate RPC/encoded WSDLs.
You should only try to use this if you absolutely have to (if you
need to provide a service to a consumer who has defined the format
of the service).
Document/literal
TransacXML can create the Plex document definitions based on a
document/literal WSDL.
Plex can call a document/literal service.
RPC/literal
TransacXML can create the Plex document definitions based on an
RPC/literal WSDL.
Plex can call an RPC/literal service.
RPC/encoded
TransacXML can create Plex document definitions based on an
RPC/encoded WSDL. However, SOAP-encoded arrays are not fully
handled. You should be able to create the rest of the definitions
manually – but this can be quite complex.
TransacXML can call RPC/encoded services.
Note that the SOAP standard allows encoding using other encoding
methods. TransacXML only supports SOAP-encoding.
Online documentation - Websydian v6.1