Introducing ICommunicationObject

In the Windows Communication Foundation, there are a few classes that are so fundamental that they are a supertype of almost every other class you have to deal with.  For the world of WCF channels, ICommunicationObject is that class.

 public interface ICommunicationObject : IDisposable
{
   CommunicationState State { get; }

   event EventHandler Closed;
   event EventHandler Closing;
   event EventHandler Faulted;
   event EventHandler Opened;
   event EventHandler Opening;

   void Abort();
   IAsyncResult BeginClose(AsyncCallback callback, object state);
   IAsyncResult BeginClose(TimeSpan timeout, AsyncCallback callback, object state);
   IAsyncResult BeginOpen(AsyncCallback callback, object state);
   IAsyncResult BeginOpen(TimeSpan timeout, AsyncCallback callback, object state);
   void Close();
   void Close(TimeSpan timeout);
   void EndClose(IAsyncResult result);
   void EndOpen(IAsyncResult result);
   void Open();
   void Open(TimeSpan timeout);
}

The role of a communication object is to implement a particular state machine we use to model communication resources.  It isn't really intuitive looking at ICommunicationObject what that state machine is, how to use it, or how to implement it.  That's unfortunate.  Those of you working with channels directly will need to know how the state machine works.  At the higher levels of service and abstraction in WCF though, some of these details are hidden.

The three main states to worry about are Created, Opened, and Closed.  A communication object starts in the Created state where you can fiddle with its settings to configure the resource.  Once a communication object leaves the Created state, it's too late to be changing settings or modifying the channel stack.  At this point the object is said to be immutable.  The most common way to leave the Created state is to engage the communication resource by calling the synchronous Open() method or the asynchronous BeginOpen() method.  Long time Windows programmers will recognize this common synchronous/asynchronous pattern; everyone else will have to wait a few weeks until I have time to cover this pattern and our asynchronous helper classes.  When you're done with the resource, you can clean it up by calling the Close() method, again in both synchronous or asynchronous versions.

Common pitfall: The IDisposable implementation will typically delegate to calling the Close() method.  It's generally better if you close network resources explicitly when you're done using them.  You might create a race condition if you defer cleaning up resources until some arbitrary point in the future.

Tricky point: Although we've just covered everything but the Abort() method and Faulted state, the two are not connected.  Calling Abort() is just a more impatient way of telling the resource to close.  The Faulted state indicates that something has gone wrong with the resource and it can no longer be used.

Extra tricky point: The method overloads without a timeout do not mean that the timeout is infinite.  They instead should timeout after some reasonable default.  This is very, very important.  Getting this wrong in an implementation can break many of our Denial of Service mitigations for slow or resource hogging clients.

Life gets better if you use the corresponding base class, CommunicationObject.  This will help take care of running the state machine.  For the rest of the week, I'll be looking at the state machine and support classes in more detail to show off all of the states and transitions.

Next time: Don't Like it? Throw it Out!

Comments

• Anonymous
  February 22, 2006
  Every time you want to send someone a message, that message first has to make its way through something...
• Anonymous
  February 24, 2006
  Yesterday, I introduced the ICommunicationObject state machine and mentioned that we had a base class...
• Anonymous
  February 24, 2006
  In the original post introducing ICommunicationObject I claimed that the abstract base class helps you...
• Anonymous
  February 27, 2006
  I kind of glossed over the subject of timeouts before although I did call them out as an extra tricky...
• Anonymous
  March 14, 2006
  Last week I introduced the different kinds of channel shapes that are available with WCF.  This...
• Anonymous
  March 21, 2006
  The final player in the drama between IRequestChannel and IReplyChannel is the link connecting requests...
• Anonymous
  June 29, 2006
  One of the biggest changes, although hard to recognize as such, is that we had to change the behavior...
• Anonymous
  August 15, 2006
  It's hard to believe that I introduced the ICommunicationObject state machine six months ago but never...
• Anonymous
  September 11, 2006
  The stream upgrade model consists of four abstract base classes.  We looked at the StreamUpgradeBindingElement...
• Anonymous
  October 08, 2006
  The stream upgrade model consists of four abstract base classes. We looked at the StreamUpgradeBindingElement
• Anonymous
  October 08, 2006
  The stream upgrade model consists of four abstract base classes. We looked at the StreamUpgradeBindingElement