Re: revised fault proposal

Sanjiva Weerawarana wrote:
> This is a revised proposal based on the discussion on the mailing
> list the last few days. I would appreciate if you say +1 if you
> are ok with this etc. and give concrete suggestions rather than 
> general comments. I'd like to get this written up ASAP so that
> we can close on much of part1 functionality.
> 
> ==================
> 
> The current draft [1] has fault reference components [2] as unfinished 
> business. The status quo is:
> 
> <definitions>
>   <interface>
>     <operation>
>       <infault
>             name="xs:NCName" 
>             messages="list of xs:QName" >
>         <documentation />?
>       </infault>
>       <outfault
>             name="xs:NCName" 
>             messages="list of xs:QName" >
>         <documentation />?
>       </outfault>
>     </operation>
>   </interface>
> </definitions>
> 
> I propose we use the following instead:
> 
> <definitions>
>   <interface>
>     <operation>
>       <input ../>*
>       <output ../>*
>       <fault messageReference="xs:NCName" details="xs:QName"/>*
>     </operation>
>   </interface>
> </definitions>
> 
> where fault/@messageReference indicate the message in the pattern 
> that this fault element is declaring concrete detail information
> for, and @details indicates the XML element which represents 
> all the data that is available if/when this fault occurs. The
> direction of the fault (inbound vs. outbound) is implied by
> the value of @messageReference (see my messages about how 
> operation/input and operation/output are redundant for further
> details). Note that we allow multiple <fault> elements with the
> same @messageReference value - this is the mechanism to indicate
> the multiple faults that may occur in the same message role played
> by @messageReference.
> 
> In component model-speak, I propose that a fault reference
> component have two properties:
>     - a {message reference} property, ala that of message references
>     - a {details} property indicating an element defining the contents
>       of the fault message
> The constraints on {message reference} would have to be written
> up as per the above paragraph.
> 
> The binding message reference components [3] for referring to faults
> from inside a binding would also need to change to be consistent with
> this approach. Basically, instead of:
> 
> <definitions>
>   <binding>
>     <operation>
>       ...
>       <infault
>             name="xs:NCName" >
>         <documentation />?
>       </infault>
>       <outfault
>             name="xs:NCName" >
>         <documentation />?
>       </outfault>
>     </operation>
>   </binding>
> </definitions>
> 
> I propose:
> 
> <definitions>
>   <binding>
>     <operation>
>       ...
>       <fault messageReference="xs:NCName" details="xs:QName"?>
>         <code>...</code>
>         <subcode>...</subcode>
>         <documentation />?
>       </fault>
>     </operation>
>   </binding>
> </definitions>
> 
> Note that the optional fault/@details attribute would allow one
> to disambiguate between mutiple occrurences of 
> interface/operation/fault with the same @messageReference value.
> 
> Faults defined as above would have a natural default SOAP 
> binding: the details element goes inside the <details>
> element of a SOAP fault and Other bindings can define suitable
> binding rules. 
> 
> ISSUES:
> ------
>     - Roberto & Tom have expressed a preference to using <infault>/
>       <outfault> instead of what I wrote above. Can you guys live with
>       my writing this up with an issue for this?

No, I can't. I find the syntax you proposed disturbingly inconsistent
and a step back from the status quo. I also don't think that we should
rush changes just to meet the publication deadline for the next working draft.

Let me try to split the issue up and explain what my preferred solution
would be.

The first sub-issue is that we currently allow a list of QNames under the
infault/outfault messages attribute. Your proposed solution is to
change rename it to details and have its value be a single QName; WSDL authors
would then have to use multiple fault elements,
e.g.

<interface name="foo">
   <operation name="this-is-irrelevant"
              pattern="http://mypatterns.org/pattern1">
     <input messageReference="M1" headers=".." body=".."/>
     <output messageReference="M2" body=".."/>
     <outfault messageReference="M2" details="F1"/>
     <outfault messageReference="M2" details="F2"/>
     <outfault messageReference="M2" details="F3"/>
   </operation>
</interface>

I'm +1 on this.

The second issue is whether infault/outfault should be replaced by
fault. Logically, we should treat input/output and infault/outfault
similarly. I don't buy the argument that we should treat faults
differently because they're special, or are more frequently used
as outfaults. Also, I don't buy the argument that we should keep
input/output distinct because then we can do smart things in
the syntax for in-only and in-out operation (this is going to be the
third and last issue below).

If we decide to eliminate the direction of a message from the syntax
because it's redundant, here's what I see as the natural solution:

(1)

<definitions>
   <interface name="xs:NCName">
     <operation pattern="xs:anyURI">
       [ <message name="xs:NCName"
                  body="xs:QName"
                  headers="list of xs:QName"/>
       |
         <fault name="xs:NCName" details="xs:QName"/>
       ]*
     </operation>
   </interface>
</definitions>

No special treatment for input/output messages or faults.

Incidentally I don't buy the argument that the direction should be
taken out of the syntax either: I think that it's natural to the WSDL author
to spell out the direction a message flows in, which will be later *checked*
against what the pattern prescribes. This is analogous to having the
interface attribute on service; it could be inferred by looking at the
bindings, but that simply reverses the mental process the WSDL author goes
through.

So if we decide to keep the direction apparent (and this is my preference), we
get:

(2)

<definitions>
   <interface name="xs:NCName">
     <operation pattern="xs:anyURI">
       [ <input name="xs:NCName"
                  body="xs:QName"
                  headers="list of xs:QName"/>
       |
         <output name="xs:NCName"
                  body="xs:QName"
                  headers="list of xs:QName"/>
       |
         <infault name="xs:NCName" details="xs:QName"/>
       |
         <outfault name="xs:NCName" details="xs:QName"/>
       ]*
     </operation>
   </interface>
</definitions>

(Here I'd be in favor of making the name attribute on
input/output/infault/outfault
optional and default it to e.g. "in" for input/infault and "out" for
output/outfault. But this is yet another separate issue.)

The message ref and fault message ref components would keep the existing
{direction} property. Its value would be checked against what the pattern
specification says, provided the tool knows about the pattern in use, of
course.

The third issue, completely separate from your current proposal, is how
to simplify the syntax for common patterns like in-only our in-out. The
scheme we discussed at the f2f, whereby a tool would rely on the order
and number of occurrences of the input and output elements, is by no means
the only way to do this, so the desire for simplification cannot be used
as an argument to keep <wsdl:input/> and <wsdl:output/> around.

As an example, here's a different idea in this space: define an extension
for each pattern that we feel should have special syntax. E.g., here's an
in-out extension:

(3)

<definitions>
   <interface name="xs:NCName">
     <operation pattern="xs:anyURI"?>
       <pattern:in-out wsdl:required="true">
         <in body="xs:QName" headers="list of xs:QName"/>
         <out body="xs:QName" headers="list of xs:QName"/>
	<fault details="xs:QName"/>*
       </pattern:in-out>
     </operation>
   </interface>
</definitions>

The pattern attribute on operation becomes optional. As part of the
specification of the pattern:in-out extension, we'd say that it has
to set the {pattern} property on the operation and build all the appropriate
message reference and fault message reference components.

Notice also that these extensions can be defined today (provided we make the
pattern attribute on wsdl:operation optional) by any pattern author. They are
*not* syntactic sugar because they are outside of the WSDL namespace. Of
course, if we so desired, we could turn these extensions into syntactic sugar
pretty easily (and get rid of the wsdl:required="true" attribute in the
process).

I should also add that the names in/out/fault for the children of
<pattern:in-out/> have been arbitrarily chosen. Those elements are governed by
governed by the extension, so any other naming choice will do. Not that I'm
arguing against reusing message/fault or input/output/infault/outfault
in that context, that's not my intention. (3) can easily be made visually
compatible with either (1) or (2).

In conclusion, I'm in favor of adopting (2), which is the status quo with some
minor changes, and opening an issue for better syntax for some common
patterns (if we don't already have one), then considering proposals such as
(3) alongside the one you presented in Palo Alto.

Roberto

Received on Friday, 3 October 2003 14:58:15 UTC