Hartmut's BoxHartmut Wilms’s Weblog

« Juli 2007 | Main | September 2007 »


Contract-first vs. Code-first Web Services Development

Dare Obasanjo is commenting on an InfoQ article entitled “Code First” Web Services Reconsidered. He states that the question shouldn’t be about whether you should prefer contract-first or code-first:

The only real consideration when deciding between “code first” and “contract first” approaches is whether your service is concerned primarily with objects or whether it is concerned primarily with XML documents [preferrably with a predefined schema]. If you are just moving around data objects (i.e. your data model isn’t much more complex than JSON) then you are better off using a “code first” approach especially since most SOAP toolkits can handle the basic constructs that would result from generating WSDLs from such types. On the other hand, if you are transmitting documents that have a predefined schema (e.g. XBRL or OOXML documents) then you are better off authoring the WSDL by hand than trying to jump through hoops to get the XML<->object mapping technology in your off-the-shelf SOAP toolkit to do a great job with these schemas.

According to Dare the main problem lies in the impedance mismatch between W3C XML Schema (XSD) and objects from your typical OO system. Every SOAP Web Service publishes a service contract, which described the document types based on XML Schema. The problem with XML Schema is that it offers a much more complex type system than any known OO language. Thus interoperability issues cannot be avoided when putting XML (De)Serialization to use, because simple types might be mapped correctly, but complex types often pose problems for the serialization engine.

Dare suggests to revert to RESTful Web Services, which omit the problem by simply doing without XML Schema based contracts:

One of the interesting consequences of the adoption of RESTful Web services is that these interoperability issues have been avoided because most people who provide these services do not provide schemas in the W3C XML Schema. […] That way XML geeks like me get to party on the raw XML which is in a simple and straightforward format while the folks who are scared of XML can party on objects using their favorite programming language and platform. The best of both worlds.

Although I have once rightly been put on the SOAP side of the Tilkov Scale, I’m starting to switch sides - for better or for worse …

Posted by Hartmut Wilms at 11:13 | Comments (2)

Dependency Injection - Good or Bad Practice?

Jacob Proffitt shares his musings about Dependency Injection on his blog. He gives an example of a data access pattern, which might be implemented by directly managing the data access provider or by injecting the provider or the connection via Dependency Injection. He conclude that

The benefit to this pattern is that the class is now disconnected from the data provider. The disadvantage is that now my calling code has to handle the provider.

In his opinion Dependency Injection has mainly been “hyped” by Unit Testing frameworks using mock objects:

The real reason that DI has become so popular lately, however, has nothing to do with orthogonality, encapsulation, or other “purely” architectural concerns. The real reason that so many developers are using DI is to facilitate Unit Testing using mock objects.

There are several mock object libraries making use of dependency injection, e.g. NMock and Rhino.Mocks. Jacob refers to TypeMock as an example of a “Superior .Net Mocking” solution, which “claims to allow you to mock objects used by your classes without having to expose those internal objects at all”. He closes by saying:

And why am I still hearing about the virtues of a pattern whose sole perceptible benefit is allowing mock objects in Unit Tests?

Nate Kohari disagrees and starts a rather lengthy discussion in the comments to Jacob’s post. He says that

The real benefits of DI appear when you use a framework (sometimes called an “inversion of control container”) to support it. When you request an instance of a type, a DI framework can build an entire object graph, wiring up dependencies as it goes.

He refers to two examples of IoC containers, namely Castle Windsor and his own framework Ninject. Jacob isn’t convinced and responds:

How can you say that dependency injection […] creates loosely coupled units that can be reused easily when the whole point of DI is to require the caller to provide the callee’s needs? That’s an increase in coupling by any reasonable assessment.

Nate responds to this argument on his blog by defending Dependency Injection:

This is why dependency injection frameworks like Ninject, Castle Windsor, and StructureMap exist: they fix this coupling problem by washing your code clean of the dependency resolution logic. In addition, they provide a deterministic point, in code or a mapping file, that describes how the types in your code are wired together.

He also responds to Jacob’s argument that the Factory Pattern already solves all the problem DI claims to address:

Factory patterns are great for small implementations, but like dependency-injection-by-hand it can get extremely cumbersome in larger projects. Abstract Factories are unwieldy at best, and relying on a bunch of static Factory Methods (to steal a phrase from Bob Lee) gives your code “static cling” — static methods are the ultimate in concreteness, and make it vastly more difficult to alter your code.

He continues in the (absolutely worth to read) comments of his post:

 Now, let’s consider the DI vs. provider model argument. The real benefit of DI over a provider model (abstract factory) is the ability to wire up multiple levels of the object graph at once. With an abstract factory, you can get different implementations for a specific dependency. However, wiring the dependencies of the dependencies (and so on) is not part of the equation, unless you have a bunch of abstract factories.

I generally have to agree with Nate. But I would suggest to use dependency injection sparingly. You don’t have to (or you mustn’t) describe every dependency between types in a central mapping file. Although your dependencies are then described in one place and may be changed at deployment, the remaining code gets very generic and difficult to understand (the inner workings, which are injected at runtime, are missing). Some dependencies are implementation details and should remain within your code. Others are on an “upper” level and good candidates for DI.

Posted by Hartmut Wilms at 10:28 | TrackBack


The Four Tenets and XML Messaging with WCF

Don Box has responded to my post on Harry Pierson’s discussion about retiring the four tenets. I would like to respond to some of  his statements:

Harmut states “WCF Contracts are still CLR-Classes, not Schema or Contract.” This isn’t quite right. The in-memory representation for WCF contracts is a DOM-ish tree that can be cons’ed up using any number of techniques, not just writing C# interfaces with [ServiceContract] (go look at Sys.SvcModel.Description.ContractDescription if you care to spelunk). ContractDesc is neither CLR reflection data nor WSDL – rather it’s the optimized in-memory rep used throughout our runtime. FWIW, we’re actively investing in other ways to write ContractDescs down (honestly I’m not a big fan of CLR interfaces or WSDL – please God tell me we can do better).

I know about WCF’s representation of Service Contracts. What I meant was that concerning the Service Design WCF Contracts are still CLR classes annotated with WCF attributes. As a service developer or designer I don’t care about the internal representation, I’m using the “API” representation. In the WCF case this is - at least in the Service Model - a CLR interface or class.

Before continuing I want to express my deep respect for the design of WCF, especially its channel model layer and XML messaging framework.  The service model layer serves as a mapping between the XML (WSDL, XSD) world and the CLR world. In some cases this is the right approach, in the case of service-oriented principles it’s not. WCF serves two main purposes: a) consolidating the former .NET APIs  for distributed computing and b) providing a web service stack for implementing services according to service-oriented tenets (here we go again).

Doesn’t WCF live up to the second purpose, then? Well, no and yes. As Ben Kloosterman points out in the comments to Don’s post “the biggest problems is people have no experience with SOA so they fall back on remote object tecniques but using an SOA tool like WCF”. I would change this to “SOA tool like the WCF service model”. That’s the first and maybe most important argument against the service model (when implementing SOA services!):

  1. Developers and designers tend to fall back to traditional remote object techniques.
  2. The “schema and contract” mentioned in the four tenets are reduced to generated artifacts, which aren’t even part of your code basis. A contract has to be designed, not generated!
  3. X-O-Mapping will never satisfy all your needs. WCF Contracts and XML Serialization won’t either.
  4. Loose coupling is what all tenets (to some extend) are all about. The need to (re)generate proxies when a provider or consumer changes even in the smallest degree is not what I would call loosely coupled. This is a weak argument, which should be examined in greater detail. Granted.
  5. Mark Seeman states in the comments to Don’s post: “It’s easy to understand”. I would say that C# interfaces that are cluttered with C# attributes are as easy to understand as XSD schemas or even more difficult.

Let’s have a look at this example of a data contract taken from “Designing Service Contracts with WCF:

[DataContract(Namespace = "", Name = "LinkItem")]
    public class LinkItem {
        [DataMember(Name = "Id", IsRequired = false, Order = 0)]
        private long id;
        [DataMember(Name = "Title", IsRequired = true, Order = 1)]
        private string title;
        [DataMember(Name = "Description", IsRequired = true, Order = 2)]
        private string description;
        [DataMember(Name = "DateStart", IsRequired = true, Order = 3)]
        private DateTime dateStart;
        [DataMember(Name = "DateEnd", IsRequired = false, Order = 4)]
        private Nullable<DateTime> dateEnd;
        [DataMember(Name = "Url", IsRequired = false, Order = 5)]
        private string url;
        [DataMember(Name = "LinkType", IsRequired = false, Order = 6)]
        private string linkType;

The corresponding XSD schema looks like this:

<xs:schema elementFormDefault="qualified" 
  <xs:complexType name="LinkItem">
      <xs:element minOccurs="0" name="Id" type="xs:long"/>
      <xs:element name="Title" nillable="true" type="xs:string"/>
      <xs:element name="Description" nillable="true" type="xs:string"/>
      <xs:element name="DateStart" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="DateEnd" nillable="true" type="xs:dateTime"/>
      <xs:element minOccurs="0" name="Url" nillable="true" type="xs:string"/>
      <xs:element minOccurs="0" name="LinkType" nillable="true" type="xs:string"/>

The namespace declarations within the schema element are a little bit confusing when you’re not accustomed to XML. But all the rest isn’t really more difficult than the C# interface, is it?  In my opinion every service designer and developer has to have a profound understanding of XML. Hey, you are developing SOAP Web Services. You should have a basic understanding of your published contracts/interfaces, don’t you?? When you do have a good understanding of XML, XSD isn’t that difficult anymore (regarding interoperability you should stick to simple type definitions).

But what do you gain from incorporating XSD (and WSDL) as first-class citizens into your implementations?

  1. A good understanding of your published interfaces. This is a must!
  2. Very expressive contracts. For instance if you include a zip code in your type definitions, its contents should be of type string and limited to the zip code format of your country. This restriction could easily be integrated in your human- and machine-readable contract by the XSD concept of “inheritance by restriction”. A concept unknown to the CLR (type system). When using WCF contracts these restrictions have to be written down in a separate API docs that are likely to be ignored by the majority of developers. Contracts cannot be ignored, they are validated by your service (at least they should be - see below).
  3. We could implement a very forgiving validation thereby enhancing the loose coupling of our services. We’ll come to that in a moment. 
  4. Flexibility.

The sad thing about WCF is, that it doesn’t provide real schema validation. It provides XML Serialization, which partly does the same. Luckily there is a nice way of adding schema validation to WCF. The good thing is that WCF supports XML messaging out-of-the box.

Don asks me (and others) to “sketch out a concrete example of what they would rather write assuming a “traditional” imperative programming language (static or dynamically typed)”. Here is my answer:

1. Model your data types with XSD and your contracts with WSDL. It is no fun to write a complete WSDL on your own, but there are ways of simplifying this task. You might use a modeling tool (such as the one to be published with v3 of the Web Service Software Factory) or you might model your messages in your schema and generate the WSDL with a template based code generation approach.  

2. Register and publish your contract (WSDL & XSD) in your service registry/repository. There isn’t any real (or state of the art) repository/registry solution provided by Microsoft. But there are other solutions, which might be used. After all we are living in a service world, which is independent of vendors and platforms …

3. Take the “untyped services” approach of WCF:

[OperationContract(Action = "CreateLink")]
Message CreateLinkItem(Message aLink);

The Message objects represents the SOAP envelope and provides access to its headers and the complete XML contents. Although this approach is called “untyped”, your contracts are strictly typed. So “untyped” only refers to the generic CLR interface. Type-checking is provided by:

4. Validate incoming messages via the custom Behavior/Inspector mentioned above or even better via Schematron. This approach is beyond the scope of this post. I’ll cover this topic in one of my future posts. There is no Schematron implementation for .NET (save an abandoned project)? No problem, just revert to the reference implementation :-).

Schematron allows your services to be very forgiving concerning changes in your consumer’s logic. Your service might expect a purchase order. This purchase order has to conform to a certain structure. If your consumer extends this structure, you’re not supposed to break! After all, everything you request is still provided. As already mentioned above, I’ll provide an example for this approach in one of my future posts. 

5. Access the payload of the message by using XPath expressions. You might also use the XmlDictionaryReader or LINQ to XML (or LINQ to XSD).

So, I don’t want an alternative to WCF. I only want to use what’s already there. It is either incorporated into WCF already or can be added via WCF extension points. In my opinion XML messaging with WCF is the best approach for developing services that adhere to the four tenets.

Posted by Hartmut Wilms at 19:18


Retire the Tenets?

Harry Pierson states: “Retire the Tenets”.  John Heintz agrees by dismissing the Four Tenets as useless:

There is one other thing about SOA that drives me bonkers. I’m hooked on architecture by constraint - limit the system in certain key areas to promote certain use and benefits. The four tenets of SOA don’t do it to me at all.

Well, tenets are just that: tenets. Don Box and many others explained these tenets. Just “google” for the “four tenets” and see for yourself. Principles, guidelines and best practices might be drawn from the tenets. Granted the tenets may not be used as a map to solid service oriented design, but they started a different way of looking at distributed computing (in the MS world and in others, too). They started a discussion about service oriented principles, which all to some extend are based on the ideas expressed by the tenets.

Harry Pierson concludes that the four tenets had been “designed to help the Windows developer community wrap their heads around some of the implications of messaging and service orientation”. In a way the four tenets just expressed, what “almost” everybody outside the MS world knew already. Their only use was to impress that single truth in the brains of “DCOM, MTS and VB” developers. Now, that’s been done:

I would say that the tenets’ job is done and it’s time to retire them. Once you accept the service-oriented paradigm, what further guidance do the tenets provide? Not much, if any.

In a perfect (service oriented) world maybe I would agree. But has this paradigm shift taken place? Are “Platform vendors […] falling over themselves to ship service/messaging stacks like WCF” and do “most developers […] look at these stacks for the next systems they build”? Most important: do these platforms and stacks (fully) adhere to the principles, which are based on a truth almost everybody knew already?

I don’t think so! WCF might be used in a fully service-oriented way: message-oriented, document-based, contract and policy driven. The common guidance looks different, though. Have a look at ASMX, WCF, Axis 2 and all other SOAP stacks:

Just write the classes, we’ll generate your contract and policy and throw in some XML (De)Serialization for good.

WCF Contracts are still CLR-Classes, not Schema or Contract. There isn’t even a standard procedure for validating the message against the schema (just an XML Deserialization, which does the job, well, at least for the most simple cases).

John and Harry, do you really think that every developer has adopted to the message-oriented paradigm and that “service orientation is mainstream”? I’m afraid not. As long as the CLR/JVM/…-First approach is proclaimed by the vendors and the masses listen and follow, the four tenets are far from retirement!

Posted by Hartmut Wilms at 20:36 | TrackBack


John Devadoss about Big SOA, Little SOA

John Devadoss wrote a post on “Big SOA, little SOA”. He is advocating a - what Microsoft calls the middle-out approach - instead of a top-down or bottom-up approach.

This middle-out approach starts on a small business case and “build out the entire use case end-to-end, from the data through to the consumption”. All the time you should have “the big picture” in mind, as if you were building a “Big SOA”, i.e. stick to the right tenets, build highly adaptable and reusable services and start to setup a SOA Governance  along the way:

You don’t learn by planning – you learn by doing. Partitioning your functionality helps you track changing business needs much more effectively.

I’m especially fond of his “snowball” metaphor:

Last, but not the least, successful customers use what we call a “snowball” approach. How do you build a big snowball? You start with a small snowball.

Posted by Hartmut Wilms at 21:23 | TrackBack


GTD@Outlook with Jello.Dashboard

I’ve been looking for an efficient way of organizing tasks, contacts and mails in Microsoft Outlook for some time. After using Jello.Dashboard for more than 3 months, I think I’ve found what I was looking for.

Jello.Dashboard is a Homepage for Outlook that adds GTD like functionality at no cost. Go and have a look for yourself.

The only thing I missed from Jello.Dashboard was a keyboard shortcut for activating the Outlook Homepage (the Dashboard). After searching the Internet (Outlook Help didn’t help at all) I came upon KC Lemson’s blog and her post “Outlook 2003 tip o’ the day”. She explains how to customize the Outlook toolbar, add a clickable action, and assign a keyboard shortcut.

So I added the “Outlook Today” action from the “Advanced” group, changed the icon to “Text only (always)” (context menu), and finally assigned a shortcut by renaming the icon/action in the context menu. I ‘ve chosen Alt-q. Why? I renamed the action to “inno&q Today”. The “&” does the work of assigning an Alt-Key-Combination to a character with the action’s name. The choice of “q” is obvious for two reasons: a) “innoQ” and b) Alt-q is easily accessible. 

Posted by Hartmut Wilms at 16:43