Attempt #3 at WSDL binding, and commentary

[Eric Johnson <eric@tibco.com>]

My apologies to those who aren't getting at least an hour to review this before the call.  I've been meaning to get to this for several days now.  The following rolls up a bunch of edits, and I've inserted editorial comments to answer questions.

4 Transport Binding

The binding.ws element provides numerous ways to specify exactly how messages ought to be transmitted from or to the reference or service. Those ways include references to WSDL binding elements from the @wsdlElement attribute, policy intents, and even vendor extensions within the binding.ws element. However, all of those ways to indicate how messages get carried happen to be optional. This section describes the defaults that ought be used if the specific transport details are not otherwise specified.

4.1 Intents

So as to narrow the range of choices for how messages are carried, the following policy intents affect the transport binding.

• soap
  This indicates that messages MUST be transmitted using SOAP. One or more SOAP versions can be used.

• soap.1_1
  Messages MUST be transmitted using only SOAP 1.1.

• soap.1_2
  Messages MUST be transmitted using only SOAP 1.2.

4.2 Default Binding

In the event that the transport details are not otherwise determined, a conforming implementation SHOULD enable the following configuration:

[Eric note: Anish asks why is the above "SHOULD", not "MUST"?  In short, because there is a slight change of meaning I've performed here. I've not specified that this is restricted to just "<binding.ws/>".  To "defeat" a "MUST" criteria on this representation, all the vendor has to do is introduce an attribute of any kind.  In this sense, I've broadened the applicability of this section.  That is, even if a vendor does introduce additional attributes, they SHOULD still make this configuration available, unless those attributes are specifically about changing this configuration.  To clarify this, I changed it to read "not otherwise determined."]

• HTTP-based transfer protocol
  

• Except when policy mandates the use of only SOAP 1.2, support SOAP 1.1

[Eric note: Anish asks: "Shouldn't we say that if there is no soap 1.2 policy/intent then it must be soap 1.1?"  This comes back to the multiple ports question.  If a vendor decides that SOAP 1.2 is a good default, they can generate a SOAP 1.2 port, but they SHOULD still also generate a SOAP 1.1 port.]

• “literal” format as described in section 3.5 of [WSDL11]

• For messages that have a single part, the message uses “document” style, as per section 3.5 of [WSDL11].

• For messages that have multiple parts, the message uses “rpc” style, as per section 3.5 of [WSDL11]. In this case, the child elements of the SOAP Body element must be namespace qualified with a non-empty namespace name.

[Eric note: Anish asks whether the above are redundant with stating BasicProfile compliance?  I don't think so, because this section is about a default binding, there is no implication here that WSDL is ever generated.  Also, I think rolling up the requirements here, rather than forcing developers to wade through the different (three?) versions of basic profile, and figure out whether they all say the same thing, eliminates the possible ambiguities.  Anish's second question is whether this section implies a requirement of WSDL 1.1, and in case it wasn't clear, nothing here is meant to imply anything about the WSDL generation, rather it is specifying a binding, and of course that should be reflected in the WSDL.]

• For SOAP 1.1 messages, the SOAPAction header described in section 6.1.1 represents the empty string, in quotes (“”).

• For SOAP 1.2 messages, the optional SOAP Action feature described in section 6.5 of [SOAP12Adjuncts] does not appear.

• All message parts are carried in the body of the message

4.2.1 SOAP versions

Where no specific version of SOAP has been dictated, an SCA runtime might generate bindings for both of SOAP 1.1 and SOAP 1.2.

[Eric note: Anish thinks we should say that the SCA runtime MUST support SOAP 1.1.  I agree, but I don't think that this is the place to state that.  I changed the wording to reflect that this section is about the bindings that might be generated.]

4.3 WSDL portType or interface

An SCA service has a single interface description. For the Web Services binding, this interface description MUST be converted into one or both of a WSDL 1.1 portType or a WSDL 2.0 interface.

[Eric note: Anish asks whether we should mandate WSDL 1.1.  That's a broader question.  I don't think we should, and haven't indicated that above.]

B. Appendix - WSDL Generation

Due to the number of factors that determine how a WSDL might be generated, including compatibility with existing WSDL uses, precise details cannot be specified. For example, policy implementation decisions can affect the way WSDL might be generated. For reference, and consistency, this section suggests non-normative choices for some of the various details involved in generating WSDL.

• wsdl:definitions/@name = <componentName> + "." + <serviceName>
  

• wsdl:definitions/@targetNamespace = <HTTP Base URI> + “/” + <componentName> + “/” + <serviceName>

• import each WSDL 1.1 portType or WSDL 2.0 interface, rather than putting them inline

[Eric note: Anish asks - if the user employs interface.java, must the generated WSDL representation be put into a separate file, or could it be inlined?  Since this section is non-normative, I'm not sure it matters, but I believe the recommendation still stands.]

• wsdl:binding/@name = <name of binding> + <SOAP Version> + “Binding”

• wsdl:service/@name = <name of the service>

• wsdl:port/@name = <name of binding> + <SOAP Version> + “Port”

In the above, "<SOAP Version>" should be either "SOAP11" or "SOAP12" as appropriate.

---

Commentary:

1. The current spec says that a separate WSDL document is generated for each SCA service.  The new text is silent on this.  Do we want to say anything about whether the WSDL document should correspond to the SCA service (possibly with multiple SCA bindings), or whether there should be a WSDL document for each binding on that service?

Eric: My take is to say nothing here.  Guessing at or suggesting the useful granularity of generated WSDL files seems like a tricky business.

2. The current spec says that WSDL binding elements may be imported from existing WSDL documents specified on <binding.ws>.  The new text only mentions importing portTypes or interfaces.  Should the new text also mention importing WSDL bindings?

Eric: I don't particularly care.  If others think that this is a useful recommendation to add to appendix B, then we can add it.  Seems tricky, though, because the actual binding of the resulting service could be affected by vendor provided custom WSDL annotations, or any number of other good reasons a vendor might have for inlining the binding information.

3. What is the HTTP base URI?

Eric:  Hmmm - that's a good question.  I thought when I was first looking at this that it would be URI defined in section 9.2.1 (of course there is no reference here), but looking at it now, that doesn't seem appropriate.  I believe I took this from the original version, so the intent there is now lost on me.  Can someone else chime in?

4. The current spec says that the name of the <wsdl:definitions> element should be "componentName.serviceName".  The new spec says nothing about naming the <wsdl:definitions> element.  Should it?

Eric: Added.

5. (Raised previously on a call).  What is the syntax of <SOAP Version>?  I'm guessing it's "SOAP11" or "SOAP12".  This should be stated explicitly.

Eric: I added a line above.  Do you agree with it?

-Eric.