RE: Proposed resolution: issues 78, 16

This email outlines what I believe to be the simplest solution to issues 78
and 16. This solution corresponds roughly to solution "c" suggested by Noah.
Both Noah and Jacek are unhappy with this solution, but it is one logical
possibility, so we should consider it. It solves issues 78 and 16, it does
the least violence to the current spec, and it offers backwards
compatibility to a large number of current implementations.

Briefly, this solution consists of 4 parts:

1.) Explicitly acknowledge that Section 7 MUST be used in conjunction with
Section 5.
2.) Rewrite Section 5.6 to improve its clarity.
3.) Rewrite the last paragraph of Section 7 to prohibit "boxcarring" and to
provide explicit instructions on how to handle RPC calls with 0 out params
and void return type.
4.) Add definitions for RPC terms to glossary.

I discuss each part in more detail below.

1.) Explicitly acknowledge that Section 7 MUST be used in conjunction with
Section 5.
Section 7 uses terms like "struct" and "accessor," which are defined in
Section 5. Consequently, Section 7 is implicitly dependent on the default
encoding defined in Section 5. Yet, Section 7 also states that it can be
used in conjunction with other encodings:

"Although it is anticipated that this representation is likely to be used in
combination with the encoding style defined in section 5, other
representations are possible. The SOAP encodingStyle attribute (see section
4.3.2) can be used to indicate the encoding style of the RPC invocation
and/or the response using the representation described in this section.
...
As noted above, RPC invocation and response structs can be encoded according
to the rules in section 5, or other encodings can be specified using the
encodingStyle attribute (see section 4.1.1)."

It is clearly a contradiction for Section 7 to be based on terms defined in
the default encoding and at the same time to state that other encoding
styles can be used. To eliminate this contradiction, we should delete the
two paragraphs quoted above and add the following text somewhere in Section
7:

<FranksVersion1ofRewriteToMakeSection7DependentOnSection5>
The RPC representation defined in section 7 MUST be used in conjunction with
the encoding style defined in Section 5. The use of an encoding style other
than the one defined in Section 5 MUST be interpreted to mean that an RPC
representation other than the one defined in Section 7 is being used.
</FranksVersion1ofRewriteToMakeSection7DependentOnSection5>

2.) Rewrite Section 5.6 to improve clarity.
Once Section 7 has been made explicitly dependent on Section 5, it becomes
possible to use the "root" attribute defined in Section 5.6 to distinguish
the serialization root in the Body of an RPC message from other elements
(such as multi-ref elements) that may also appear in the Body. I have
already proposed this rewrite of Section 5.6 in another email. I repeat it
here:

<ProposedRewriteOfSection56>
The SOAP root attribute MAY be used to divide independent elements at the
same nesting level into 2 categories: those that are serialization roots and
those that are not. The purpose of marking an element as a serialization
root is to distinguish it as a starting point for processing. This is
similar to the way the "start" parameter in the MIME multipart/related media
type "points, via a content-ID, to the body part that contains the object
root."

When not explicitly forbidden, there may be multiple serialization roots at
the same nesting level (for example, in the SOAP Header).

The root attribute can have one of two values, "1" or "0". The value "1"
indicates that an element is a serialization root. The value "0" indicates
that an element is not a serialization root. The attribute does not have a
default value. All independent elements without the root attribute MUST be
assumed to be non-roots except in the case where no element has the root
attribute with a value of “1”. In that case, the first independent element
at that level without the root attribute MUST be considered to be the single
serialization root at that level. If no such element exists, it is an error.
</ProposedRewriteOfSection56>
A comment is in order on the "except" clause in the 5th sentence in the
third paragraph and the sentence that follows it in the proposed rewrite.
Some implementations have been using order to determine which element in the
body is the request/response element (in spite of the fact that SOAP 1.1
doesn't provide any support for this). Namely, some implementations
interpret the first lexical element as the request/response element and all
subsequent elements as multi-reference elements, while others interpret the
last lexical element as the request/response element and all preceeding
elements as multi-reference elements. The "except" clause and the sentence
that follows are intended to provide backwards compatibility for the first
category of implementations. Unfortunately, AFAIK, there's no way to
accomodate both categories.

I have attached a table of possible distributions of the root attribute on
various elements in a nesting level to demonstrate that the proposed rewrite
covers all possible cases. I ask members of the WG to examine this table
carefully to make sure I haven't made any errors or overlooked anything.

3.) Rewrite the last paragraph of Section 7 to prohibit boxcarring and to
provide explicit instructions for handling RPC calls with 0 out parameters
and void return type.
There seems to be general consensus among WG members that boxcarring ought
to be prohibited in the RPC representation defined in Section 7. There also
seems to be general consensus among WG members on how to handle RPC calls
with 0 out parameters and void return type. The consensus of the WG on these
two issues is summarized in the following rewrite of the last paragraph of
Section 7.1:

<FranksVersion7OfSection71>
The Body of an RPC message MUST contain one and only one serialization root.
In the case of an RPC request message, this root is the RPC request element.
In the case of an RPC response message, this root is the RPC response
element (when the RPC succeeded) or an RPC fault element (when the RPC
failed).

In the case of successful execution of an RPC with a void return type and no
[out] parameters, the Body of the RPC message MUST contain only the RPC
response element and that element MUST be empty.
</FranksVersion7OfSection71>

4.) Add definitions for RPC terms to glossary.
Members of the WG tend to use terms inconsistently when referring to RPC.
For example, the term "response" is used to refer to the entire SOAP message
(envelope), to the Body of the message, or to the element inside the Body
representing the out parameters. I propose that we add the following
definitions to the glossary and stick to them when discussing RPC.

<FranksVersion3OfRPCTerms>
RPC message: a SOAP message (SOAP Envelope) containing an RPC request
element, an RPC response element, or an RPC fault element in its Body.

RPC response message: a SOAP message (SOAP envelope) containing an RPC
response element or an RPC fault element in its Body.

RPC request message: a SOAP message (SOAP Envelope) containing an RPC
request element in its Body.

RPC element: inside the Body of an RPC message the serialization root that
represents the RPC request element, the RPC response element, or the RPC
fault element.

RPC request element: inside the Body of an RPC request message the
serialization root that represents the [in] part of the RPC.

RPC response element: inside the Body of an RPC response message the
serialization root that represents the [out] part of the RPC.

RPC fault element: inside the Body of an RPC response message the
serialization root that consists of the SOAP Fault element resulting from an
RPC fault.
</FranksVersion3OfRPCTerms>
Frank DeRose
TIBCO Software Inc.
3165 Porter Dr
Palo Alto, CA 94303
650-846-5570 (vox)
650-846-1267 (fax)
frankd@tibco.com
www.tibco.com