Middleware Matters

Lately I've been writing about various aspects of WS-Addressing endpoint references (EPRs). (Well, actually, lately I haven't been writing in my blog much at all, due to work (over)load.) Those various articles explored why I believe creating a SOAP-only single-protocol-only EPR as a standard would be an unnecessary mistake.

Earlier this week a group of us -- IBM, IONA, and SAP -- submitted a proposal to the WS-Addressing Working Group (WG) to modify the endpoint reference by adding a single metadata element. The intent of the optional new element is, as its name implies, to allow EPR creators to include metadata "by value" directly in the EPR. It essentially replaces the policies element with a more general metadata element. The policies element would become an optional child element of the metadata element.

The proposal garnered some interest in the WG, but was deemed to be too incomplete for a solid discussion in last Monday's teleconference. Admittedly, it was incomplete, as the write-up itself was put together quickly to meet a WG action item deadline, despite the fact that a fair bit of thinking has gone into this over the past three months. I spent yesterday and today writing up a more complete proposal that we'll post to the public WG mailing list by the end of the week.

Not surprisingly, I like the approach, because it allows EPR creators to include as much or as little "by value" metadata in the EPR as they deem necessary. It also allows an easy way to optionally include WSDL service elements by value in the EPR, which among other things solves the multi-port problem. In addition, it provides a handy place to include policy information. I would think that any metadata retrievable via WS-MetadataExchange could be cached there as well, thereby potentially saving some network round trips. In short, it takes nothing away from the existing EPR and adds no required elements or attributes, thus keeping it just as lightweight as it is today, yet it adds significant flexibility and allows the EPR to solve more use cases. I honestly don't think there are any drawbacks to this proposed change.

IBM, IONA, Oracle, SAP, and Sun worked together over the past couple weeks to submit a detailed proposal for EPR metadata to the WS-Addressing Working Group (WG). Our proposal is to change the EPR slightly, to look like this:

<wsa:EndpointReference>
<wsa:Address<xs:anyURI</wsa:Address>
<wsa:ReferenceParameters>...</wsa:ReferenceParameters> ?
<wsa:Metadata>...</wsa:Metadata> ?
<xs:any/>*
</wsa:EndpointReference>

The difference with this approach is that WSDL, policy, and other metadata is specified within the <wsa:Metadata> property.

IMO this modified EPR is better than the existing approach for a few reasons:

1. It removes WSDL artifacts from the main EPR body. The two WSDL artifacts in the current EPR, the interface name and service name, are kinda out of place when you think about it. The basic EPR holds an address and reference parameters. Not all services are WSDL-based, so why should WSDL information, even optional information, be viewed as being just as fundamental as address and ref params? Even the current editors' drafts of WS-Addressing prove this out, given that those two WSDL properties are described in both the core spec and the WSDL binding spec. Shouldn't they be in just one or the other, rather than in both? This proposal moves the optional WSDL fields into the optional metadata property, where they belong.
2. It allows full use of WSDL, rather than the bare minimum that's currently allowed. The two existing WSDL properties in the current EPR are barely enough to use a WSDL-based service. With our metadata proposal, full WSDL service elements (both 1.1 and 2.0) can optionally appear directly in the metadata property, allowing services that use multiple ports and bindings to include that information within their EPRs.
3. It provides a perfect place for future extensions, such as policies. The original WS-Addressing submission included a policies property for WS-Policy information, but since WS-Policy isn't (yet) a standard, the WS-Addressing standard can't refer to it. If and when WS-Policy is standardized, the extensibility of the metadata property provides a perfect place to put EPR policy metadata, and any other metadata.
4. The proposal allows for choice. This proposal allows EPR creators to include or cache as much or as little WSDL addressing and other metadata in their EPRs as they deem necessary. Given that there is no single right WS addressing answer, but rather a range of correct answers depending on the problem at hand, choice is precisely what a fundamental standard like WS-Addressing should allow.

Check out the full proposal for all the details.

Hopefully this proposal will be discussed in the WG's upcoming teleconferences, and they'll adopt it. I honestly can't think of any technical reasons against it. I just hope it doesn't fall prey to standards politics.

Tim offers some extremely excellent advice (as usual) regarding what really matters when you write your services. If I may paraphrase what he says and perhaps embellish it a bit, starting from the implementation language and generating your contracts from it is just plain wrong, wrong, wrong, at least for systems of any appreciable magnitude, reach, or longevity. Instead, focusing on the contracts first is the way to go. I've written about this for many years now, starting well over a decade ago.

When you start with the code rather than the contract, you are almost certainly going to slip up and allow style or notions or idioms particular to that programming language into your service contract. You might not notice it, or you might notice it but not care. However, the guy on the other side trying to consume your service from a different implementation language for which your style or notions or idioms don't work so well will care.

Last summer a customer told me that he had read and heard my advice about starting with contracts, not code, but that he didn't understand it at all until others from elsewhere in his large corporation started trying to use his contracts to write new services or new service consumers. It wasn't until then, he said, that he was able to see how many idioms and assumptions and implementation details had crept into his contracts. His new approach is to still generate his WSDL contracts from code or IDL, but to then take the generated WSDL and go over it in detail to try to remove all those unwanted assumptions and implementation details. He says this approach results in simpler, cleaner, and much better abstracted service contracts. That result doesn't surprise me at all.

Also, I'd like to add a third piece of advice to Tim's list:

3. "SOA" does not stand for "Special Object Annotations."

Which is better: implementation code polluted with a bunch of weird square bracket annotations that inextricably (and also inexplicably) hard-wire your code to what goes on the wire, or nice, clean service contracts that keep implementation details separate? I prefer the angle brackets to the square ones, thanks.

Dare Obasanjo takes issue with my previous blog posting:

Although Steve Vinoski's argument sounds convincing, there is one problem with it. It is actually much easier to make an uninteroperable Web service if one starts with the service contract instead of with object oriented code. The reason for this is quite simple and one I've harped on several times in the past; the impedance mismatch between XSD and objects is quite significant. There are several constructs in W3C XML Schema which simply have no counterpart in traditional object oriented languages which cause current XML Web service toolkits to barf when consuming them.

Given that I've been writing and talking about the impedance mismatch in distributed programming language mappings for awhile now, I'm afraid Dare is preaching to choir here, at least about the problem. I did, after all, help write the OMG IDL C++ Mapping, which, thanks to the ever-wonderful politics of standards, is probably the most hated language mapping ever produced. Dare's solution, however, is exactly the opposite of what I'd recommend.

An impedance mismatch always forces you to choose one side or the other as the "primary" side. Those new to the game, or those who need to get something done quick and dirty, invariably choose the programming language side, because it's more comfortable. Unfortunately, if the system they develop becomes important enough or lives long enough that it becomes used outside of its original design context, the result is pain. Always. I explained why in my previous post. Chris, Stefan, Steve, and others have also shared their sound advice on this matter.

I also talked quite a bit about the impedance mismatch problem in my "It's Just a Mapping Problem" column from Internet Computing back in the May/June 2003 issue. I also touch on the issue somewhat in my latest column, "A Time For Reflection." Good developers know and can apply a wide variety of techniques and languages so as to be able to properly avoid impedance mismatches, while the not-so-good ones try to force-fit everything into their own limited little worlds.

Judging from this article, though, Dare seems to already know about the limitations that languages can impose when used as he advocates. While I don't think the solution he talks about there is the answer, I do believe that stepping outside the realm of traditional popular programming languages is a move in the right direction.

Today in the W3C WS-Addressing working group face-to-face meeting here in Boston, the group adopted the metadata proposal into the draft specification. The most recent full proposal was co-submitted by IBM, IONA, Oracle, SAP, and Sun, and last week Microsoft submitted a well-designed friendly amendment that was acceptable to all the original co-submitters. Modulo a few details, this amendment is essentially what the group adopted today.

This proposal specifies a new spot in the endpoint reference (EPR) where information such as policies and service descriptions can be stored. This allows creators of EPRs to put as much or as little metadata about the endpoint directly into their EPRs (including none at all, of course). It provides a solution for a number of issues, including those I've mentioned previously here:

• It allows a service to advertise multiple means to access it, just as your business card does for you.
• It avoids the need to create an additional structure or collection just to associate groups of related single-address-only EPRs.
• It allows services to support formats and protocols other than just SOAP, as real-world services often need to do.
• It allows applications to relatively easily deal with EPR failures and failover scenarios.

As shown in the amended proposal, an EPR might include WSDL 1.1 information in the following fashion:

<wsa:EndpointReference
     xmlns:wsa="http://www.w3.org/@@@@/@@/addressing">
   <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
   <wsa:Metadata>
     <wsdl11:definitions targetNamespace="http://example.com/fabrikam"
          xmlns:fabrikam="http://example.com/fabrikam"
          xmlns:abc="http://www.abccorp.com/"
          xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
          xmlns:iiop="http://www.iiop.org/"
          xmlns:wsdl11="http://www.w3.org/@@@@/@@/wsdl">
        <wsdl11:import namespace="http://example.com/fabrikam"
            location="http://example.com/fabrikam/fabrikam.wsdl"/>
        <wsdl11:import namespace="http://www.abccorp.com/"
           location="http://www.abccorp.com/abc.wsdl"/>
      <wsdl11:service name="InventoryService">
         <wsdl11:port name="ep1" binding="abc:soap-http-binding">
            <soap:address location="http://example.com/fabrikam/acct"/>
         </wsdl11:port>
         <wsdl11:port name="ep2" binding="abc:iiop">
            <iiop:address location="..."/>
        </wsdl11:service>
    </wsdl11:definitions>
  </wsa:Metadata>
</wsd:EndpointReference>

It took a great deal of discussion and analysis to get to this point. Many thanks to the WG for their objective consideration of this proposal and their attention to getting it right.