6.8.1 Serialization as
"application/x-www-form-urlencoded"This serialization format is designed to allow a
client or Web service to produce an IRI based on the instance data of
a message. It may only be
used when binding Interface Operation whose {style} property has a value of
"http://www.w3.org/@@@@/@@/wsdl/style/iri" as defined in 4.2 IRI Style, i.e. this serialization
format may only be used to serialize the initial message of an interface
operation.the instance data
in parts of the HTTP request
Specifically, for the HTTP binding defined in this
section (In HTTP binding, part of the instance data MAY be serialized
in the HTTP request IRI, and another part MAY be serialized in the HTTP message
body. If the Binding Operation),
"application/x-www-form-urlencoded" MAY be used as a value for the {
component uses the IRI style, and the value of the {http location} property of the Binding Operation component, but MUST NOT be
is present, this value is used as a value as a value fortemplate
which is combined with the {http address} or {property
of the endpoint element to form the full IRI to be used in an HTTP request, as
specified in section 6.5.2 Relationship to WSDL Component Model.}
properties.
The address='http://ws.example.com/service1/' />
will serialize the message in the IRI as follow:
http://ws.example.com/service1/temperature/Fr%C3%A9jus?date=2004-01-16&unit=C
In this serialization, the value of the {http location} property of the Binding Operation component, if present, is
used as a template which is combined with the {address} property of the endpoint
element to form the full IRI to be used in an HTTP request, as specified in
section 6.5.2 Relationship to WSDL Component Model.
Thisresulting
IRI MUST be mapped to an URI for use in the HTTP Request as per section 3.1
"Mapping of IRIs to URIs" of the IRI specification [IETF RFC 3987].
6.8.1.1 Case of elements cited inConstruction
of the request IRI using the {http location} property
|
Editorial note: URIPath Feedback Requested |
|
|
The inclusion of elements of the instance data in the path of the request URI, whilst supported by WSDL 1.1, is not supported by XForms 1.0. Hence this mechanism MAY be removed in a future version of this specification. Feedback on this issue from users and implementers is highly encouraged. |
|
The {http location} property, if present, MAY cite local names
of elements from the instance data of the input message
to be serialized in the path component of the request IRI ("Syntax
Components", [IETF RFC 3987], Section 3) by
enclosing the element name within curly braces (e.g. "temperature/{town/}"):
An element MUST NOT be cited more than once within the {http location} property.
An element name MAY be followed by a slash (i.e.
"/") inside curly braces (e.g. "temperature/{town/}") to
indicate that no other element must be serialized in the request IRI (see 6.8.1.2 Case elements NOT cited in the {http location} property).
Strings enclosed within single curly braces MUST be element names from the instance data of the input message, possibly followed by a slash; any other strings enclosed within single curly braces are a fatal error.
6.8.1.2 Case elements NOT Serialization of
content of the instance data not cited in the {http location}
property
If not all elements from the instance data are cited in the {http location} property, or if the property is not present on the Binding Operation component, then additional serialization rules apply.
IfThe remainder of
the {instance
data is serialized as a query string as defined in http location6.8.1.3.1 Construction of the
query string} property exists and if an element name appears
followed by a slash in its value, then the instance data must be serialized in
the message body (see .
If the HTTP method used for the request, as specified
by the {6.8.1.2.2 Serialization in the message bodyhttp method), otherwise the elements},
does not cited must beallow a message
body, then this query string is serialized as parameters in the
request IRI (see 6.8.1.3.2.1 Serialization in the request IRI).
), otherwise it is serialized in the message body (see 6.8.1.3.3 Serialization in the message body).
6.8.1.2.1 Construction of the query string
For elements of the instance data not cited in the
{http location} property, a
query string is constructed as follows.
Non-nil elements with a possibly empty single value
of the instance data not cited are
serialized as query parameters in the order they appear in the instance data.
It is an error for the instance data to contain
elements with an xs:nil
attribute whose value is "true".
Each parameter pair is separated by the value of
the {http query parameter separator} property.
Example 6-1. Query string generation
The following instance data of an input message
<data>
<town>Fréjus</town>
<date>@@@@-@@-@@</date>
<unit>C</unit>
</data>
with the following value of the {http location}
property:
'temperature/{town}'
and the following value of the {http query
parameter separator} property:
'&'
will produce the following query string:
date=@@@@-@@-@@&unit=C
6.8.2 Serialization as
"application/x-www-form-urlencoded"
This serialization format is designed to allow a
client or Web service to produce an IRI based on the instance data of a message and
serialize a query string in the HTTP message body as application/x-www-form-urlencoded.
It may only be used when binding Interface Operation whose {style} property has a value of
"http://www.w3.org/@@@@/@@/wsdl/style/iri" as defined in 4.2 IRI Style, i.e. this
serialization format may only be used to serialize the HTTP request
corresponding to the initial message of an interface operation.
Because the IRI Style constrains the instance data
not to contain multiple children elements declared with the same local name,
elements can be serialized in the request IRI with their local names
unambiguously.
For the HTTP binding defined in this section (6. WSDL HTTP Binding Extension),
"application/x-www-form-urlencoded" MAY be used as a value for the {http input serialization} property of the Binding Operation component, but
MUST NOT be used as a value as a value for the {http output serialization} or {http fault serialization} properties.
6.8.2.1 Serialization in the request
IRI
Non-nil elements with a possibly empty single value of the instance data from the input message NOT cited by the {http location} property are serialized as query parameters appended to the request IRI (e.g. Example 6-1) in the order they appear in the instance data.
It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".
If the {http location} property is not present, or if it is present and its value does not contain a "?" (question mark) character, one is appended. If it does already contain a question mark character, then the value of the {http query parameter separator} property is appended. Each parameter pair is separated by the value of the {http query parameter separator} property.
6.8.1Finally, the query string computed in 6.8.1.2.1 Construction of the query string
is appended.
6.8.2.2 Serialization in the message
body
In addition to the serialization in the request IRI of the elements cited in the {http location} property, the entire instance data is serialized in the message body following the rules of the "application/xml" (see 6.8.2 Serialization as application/xml ).
Finally, the query string computed in 6.8.1.2.1 Construction of the query string is used as the value of the HTTP message body.
Example 6-2. Instance data serialized in a IRI and in a message
body
The following instance data of an input message
<data>
<town>Fréjus</town>
<date>2004-01-16</date>
<unit>C</unit>
<value>24</value>
</data>
with the following operation element:
<operation ref='t:data'
whttp:inputSerialization='application/x-www-form-urlencoded'
whttp:location='temperature/{town/}'
whttp:method='POST' />
and the following endpoint element
<endpoint name='e' binding='t:b'
address='http://ws.example.com/service1/' />
will serialize the message in an IRI as follows:
http://ws.example.com/service1/temperature/Fréjus
which will be %-encoded as a URI as follows:
http://ws.example.com/service1/temperature/Fr%C3%A9jus
and in the message as follow:
Content-Type: application/xml
Content-Length: xxx
<data>
<town>Fréjus</town>
<date>2004-01-16</date>
<unit>C</unit>
<value>24</value>
</data>
6.8.23
Serialization as "application/xml"
The instance data of the input, output or fault message is
serialized as an XML document in the message body of the HTTP request,
following the serialization defined in [Canonical XML].],
including the serialization of a query string in the HTTP message body.
The Content-Type
HTTP header MUST have the value application/xml,
or a media type compatible with application/xml.
Other HTTP headers, such as Content-Encoding
or Transfer-Encoding,
MAY be used.
If the HTTP request method used, specified in the {http method} of the Binding Operation component bound, does allow an HTTP message body (e.g. "POST" and "PUT"), then the following rules apply.
The Content-Type HTTP header field
must have the value application/xml.
Example 6-4. Instance data serialized in the
message body
The instance data defined in Example 6-1 with the
following operation
declaration:
<operation ref='t:data'
whttp:inputSerialization='application/xml'
whttp:location='temperature/{town/}'
whttp:method='POST'
/>
and the following endpoint declaration:
<endpoint name='e' binding='t:b'
address='http://ws.example.com/service1/'
/>
will serialize the message in the HTTP request as
follow:
POST http://ws.example.com/service1/temperature/Fr%C3%A9jus
HTTP/1.1
Host: ws.example.com
Content-Type: application/xml
Content-Length: …
date=@@@@-@@-@@&unit=C
6.8.34
Serialization as "multipart/form-data"
This format is for legacy compatibility to permit the use of XForms clients with [IETF RFC 2388] servers. This serialization format may only be used when binding Interface Operation whose {style} property has a value of "http://www.w3.org/@@@@/@@/wsdl/style/multipart" as defined in 4.3 Multipart style, i.e. this serialization format may only be used to serialize the initial message of an interface operation.
Specifically, for the HTTP binding defined in this section (6. WSDL HTTP Binding Extension), "multipart/form-data" MAY be used as a value for the {http input serialization} property of the Binding Operation component, but MUST NOT be used as a value as a value for the {http output serialization} or {http fault serialization} properties.
Each element in the sequence is serialized into a part as follows:
1.
The
Content-Disposition header MUST have the value form-data, and its name parameter is the local name of the element.
2.
The
Content-Type header MUST have the value:
o
application/xml (or a media type compatible
with application/xml) if the element has a complex
type;
o
application/octet-stream if the element is of type xs:base64Binary, xs:hexBinary, or a derived type;
o
text/plain if the element has a simple
type; The charset MUST be set appropriately. UTF-8 or UTF-16 MUST be at least
supported.
3.
If
the type is xs:base64Binary, xs:hexBinary, xs:anySimpleType or a derived type, the content of the part is the
content of the element. If the type is a complex type, the element is
serialized following the rules defined in the 6.8.2 Serialization as application/xml
.
It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".
If the HTTP request method used, specified in the {http method} of the Binding
Operation component bound, does allow an HTTP message body (e.g. "POST"
and "PUT"), then the following rules apply.
The Content-Type HTTP header field
must have the value multipart/form-data.
Example 6-3.5.
Example of multipart/form-data
The following instance data of an input message:
<data>
<town>
<name>Fréjus</name>
<country>France</country>
</town>
<date>2004-01-16</date>
</data>
with the following operation element
<operation ref='t:data'
whttp:location='temperature/{town/}'
whttp:method='POST'
whttp:inputSerialization='multipart/form-data'/>
will serialize the message as follow:
Content-Type: multipart/form-data; boundary=AaB03x
Content-Length: xxx
--AaB03x
Content-Disposition: form-data; name="town"
Content-Type: application/xml
<town>
<name>Fréjus</name>
<country>France</country>
</town>
--AaB03x
Content-Disposition: form-data; name="date"
Content-Type: text/plain; charset=utf-8
2004-01-16
--AaB03x--