Part 1, Part 2, Part 3

The SuffixFilter that I have shown in Part 3 of this little series interacts with the Indigo dispatch internals to figure out which endpoint shall receive an incoming request. If the filter reports true from it’s Match() method, the service endpoint that owns the particular filter is being picked and its channel gets the message. But at that point we still don’t know which of the operations on the endpoint’s contract shall be selected to handle the request.

We’ll take a step back and recap what we have by citing one of the contract declarations from Part 1:

If we implement this contract on a class and host the service endpoint for it at, say, http://www.example.com/myapp this particular endpoint will only accept requests on http://www.example.com/myapp/customers/* (whereby ‘*’ can really be any string) because our suffix filter that’s being hooked in my the HttpMethodOperationSelectorAttribute and populated with “/customers/*” suffix won’t let any other request pass. Only those requests for which a pattern match can be found when combining an operation’s suffix pattern with the endpoint URI are positively matched by the suffix filter. For a more complex example I’ll let you peek at a (shortened) snippet of one the contracts of the TV server I am working on:

If you look at the individual operations in the above contract, you’ll see that the suffix filter would – given a base address of http://www.example.com/TV – match requests made on the URIs  http://www.example.com/TV/logo,  http://www.example.com/TV/now, and http://www.example.com/TV/media to name just a few. A special case is the GetRss() operation, which does not have an explicit suffix defined and therefore causes the suffix filter to match on the base address. An important aspect of the suffix filter is that it does not consider the HTTP method (GET, POST). Matching the HTTP method to an operation is the job of the HttpMethodOperationSelectorBehavior, which acts higher up on the endpoint level and picks out the exact method that the call is being dispatched to. The filter is only deciding whether the message is “ours” with respect to the namespace it is targeting.

The HttpMethodOperationSelectorBehavior is hooked into the service endpoint by the HttpMethodOperationSelectorAttribute’s implementation of IContractBehavior that you can look up in Part 3. In BindDispatch(), the dispatcher’s OperationSelector property is set to a new instance of our specialized operation selector. An “operation selector” is a class that takes an incoing request on an endpoint and figures out the proper operation to dispatch to. The default operation selector in Indigo acts according to the SOAP dispatch rules that I explained in Part 1 (see “Figuring out a programming model”).

However, in our REST/POX world that we’re building here we do not have a concept of “SOAP action”, but rather URIs and HTTP methods and therefore the default dispatch mechanism doesn’t take us very far. Hence, we need to replace the operation selection algorithm with our own and we do that by implementing IDispatchOperationSelector:

As you can see, there is only one method: SelectOperation. The method will only do work on its own if the incoming request is an HTTP request received by Indigo’s HTTP transport. We can figure this out by looking into the message properties and looking for the presence of a property with the name HttpRequestMessageProperty.Name. The presence of this property is required, because that’s the vehicle through which Indigo gives us access to the HTTP method that was used for the request. What we’re looking for sits as an instance string property on HttpRequestMessageProperty.Method.

The algorithm itself is fairly straightforward:

1.      We grab all operations whose HttpMethodAttribute.Method property matches (case-insensitively) the incoming HTTP method string and which have a suffix expression and throw them into a list.

2.      We sort the list by the priority of the attributes amongst each other. I introduced the priorities, because I am allowing wildcards here and I want to allow the suffixes /item/detail and /item/* (read: “anything except detail”) to coexist on the same endpoint, but I need a something other than method order to specify that the match on the concrete expression should be done before the wildcard expression. In absence of priorities and/or in the case of collisions, longer suffixes always trump shorter expressions for matching priority.

3.      We match the sorted list in reverse order (higher priority is better) and return the first operation in the list whose suffix expression matches the incoming messages “To” header (which is the same as the HTTP request URI).

4.      If we don’t have a match, we proceed to iterate over all operations that do not have a suffix and see whether we can find a match solely based on the  HttpMethodAttribute.Method value or, if the HttpMethodAttribute is absent, on the plain method name. (So if the method just named “Get” and there is no attribute, an HTTP GET request will still match).

5.      If we still don’t have a match, we look for the common “all messages without a proper home” method with an OperationContract.Action value of “*”.

6.      And as the very last resort we fall back to the default selector if we have been given one and else we fail out by returning an empty string, which means that there is no match at at all.

If we find a match, we return a string that’s the same as the name of the method we want to dispatch to and Indigo will them promptly do the right thing and call the respective method, either by passing the raw message outright (as in my TV app) or by breaking up the message body using the XmlFormatter or the XmlSerializer and passing a typed message or a set of parameters.

Step 4 is noteworthy insofar as that the [HttpMethod] attributes aren’t strictly necessary. If you name your methods exactly like the HTTP methods they should handle, the operation selector will figure this out. If that’s what you want, you don’t even need the [HttpMethodOperationSelector] attribute, if you choose to add that information in the configuration file instead. To enable that. I’ve built the required configuration class that you can register in the <behaviorExtensions> and map to the <behaviors> section of an endpoint’s configuration. The class is very, very simple:

Alright, so where are we? We’ve got dispatch metadata, we’ve got an endpoint dispatch mechanism and we’ve got an operation dispatch mechanism. Furthermore we have a tool that conveniently grabs “parameter segments” from the URI and maps them to an out-of-band collection on the UriArgumentsMessageProperty from where we can conveniently fetch them inside the service implementation.

What we don’t have is POX. We’re still dealing with SOAP messages here. So the next step is to modify the wire encoding in a way that we unwrap the content and throw away the envelope on the way out and that we wrap incoming “raw” data into an envelope to make Indigo happy with incoming requests.

That’s plenty of material for Part 5 and beyond. Stay tuned.

Go to Part 5

Part 1, Part 2

If you’ve read the first two parts of this series, you should know by now (if I’ve done a reasonable job explaining) about the fundamental concepts of how incoming web service messages (requests) are typically dispatched to their handler code and also understand how my Indigo REST/POX extensions are helping to associate the metadata required for dispatching plain, envelope-less HTTP requests with Indigo service operations using the HttpMethod attribute and how the HttpMethodParameterInspector breaks up the URI components into easily consumable, out-of-band parameters that flow into the service code the UriArgumentsMessageProperty.

What I have not explained is how the dispatching is actually done. There are two parts to that story: Dispatching to services on the listener level (which I will cover here) and dispatching to operations at the endpoint level (which I’ll cover in part 4).

When an HTTP request is received on a namespace that Indigo has registered with HTTP.SYS, the request is matched against a collection of “address filters”. “Registering a namespace” means that if you configure a service-endpoint to listen at the endpoint http://www.example.com/foo, the service-endpoint “owns” that URI.

What’s noteworthy is that if you have an Indigo/WCF application listening to endpoints at http://www.example.com/baz, http://www.example.com/foo and http://www.example.com/foo/bar, the demultiplexing (“demuxing” in short) of the requests is done by Indigo and not by the network stack. HTTP.SYS will push requests from any registered URI namespace of the particular application into the “shared” Indigo HTTP transport and leave it up to Indigo to figure out the right endpoint to dispatch to. And that turns out to be perfect for our purposes.

Whenever an incoming message needs to be dispatched to an endpoint, the message is matched against an address filter table. [For the very nosy: The place where it all happens is in the internal EndpointListenerTable class’s Lookup method, which you could probably look at if you had the right tools, but I didn’t say that.]

By default, the address filter that is used for any “regular” service is the EndpointAddressFilter, which reports a match if the incoming message’s “To” addressing header (which is constructed from the HTTP header information if it’s not immediately contained in the incoming message) is a match for the registered URI. Whether a match is found is dependent on the URI’s port and host-name (controllable by the HostNameComparisonMode in the HTTP binding configuration) and the URIs remaining path, which must be an exact match for the registered service endpoint URI. Since we want to introduce a slightly different dispatch scheme that is based on matching not only on the exact endpoint URI’s path but also on suffixes appended to that URI, we must put a hook into the dispatch mechanism and extend the default behavior. If a method marked up with [HttpMethod(“GET”,UriSuffix=”/bar”)] and the endpoint is hosted at http://www.example.com/foo, we want any HTTP GET request to http://www.example.com/foo/bar to be dispatched to that endpoint and, subsequently, to that exact method.

To infuse that behavior into Indigo, we need to tell it so. If you take a look at Part 2 and at the service contract declarations that I posted there, you will notice the HttpMethodOperationSelector attribute alongside the ServiceContract attribute. That attribute class does the trick:

In the attribute’s implementation of IEndpointBehavior.BindServiceEndpoint, which is invoked by Indigo as the endpoint is initialized (in response to ServiceHost.Open() ), we replace the service’s default endpoint filter with our own SuffixFilter class. Once we’ve done that, we iterate over the HttpMethodAttribute metadata elements that sit on the individual operations/methods in the contract description (this is the actual reason we put them there, see Part 2) and add any suffix we find to the filter’s suffix table. We’ll get back to this class in the next part while to investigate how the “operation selector” is hooked in; let’s investigate the suffix filter first.

The filter’s filet piece is in the Match method. To finally figure out whether a message is a match, we employ the matching logic of the default EndpointAddressFilter, which deals with matching the host names and the “base URI” at which the service was registered. What the suffix filter does in addition is to match the suffix regex pattern against the incoming message’s “To” header and if that is a match, the suffix is stripped and the remaining URI is matched against the aggregated EndpointAddressFilter. Only if we get a match for the suffix and for the remainder URI, we’ll report a positive match back to the infrastructure by returning true. And in that case and only in that case the service endpoint for which “this” suffix filter was installed and populated gets the request.

For each incoming request, Indigo goes through all registered endpoint address filters and asks them whether they want to service it. And that really means “all”. Indigo will refuse to service the request if two or more filters report ownership of the respective request and will throw a traceable (using Indigo tracing) internal exception that will cause none of the services to be picked due to this ambiguity. In the case of overlapping dispatch namespaces, none is indeed better than “any random”.

Next part: HttpMethodOperationSelectorBehavior

Go to Part 4

Before I get back to the POX/REST story, I promised a few folks to re-publish an updated version of my „JITA pool“ that I published over three years ago. Many people have used the technique that this utility class enables and have seen dramatic performance improvements with their Enterprise Services applications. And until Indigo ships, Enterprise Services (a.k.a. “COM+” or, shorter, “ES”) is still the most powerful application server technology on the Windows platform, so I think it deserves continued attention.

One of the common misconceptions around ES is that keep hearing is that it comes with such a significant overhead for each call that turns your server application into a fat, slow moving thing. And as things are, there are always two sides to every story and it turns out that if you use ES correctly, it is probably faster than most other cross-process technologies you can easily use from managed code. I write “probably”, because as with every distributed systems technology, “your mileage may vary” based on what your scenario is.

Before I show you the code, let’s take a quick dive into the ES/COM+ internals so that you understand what I mean with “use ES correctly”. To use technology in an optimal way you either need to understand how things work and how all technology pieces fit together or you need absolutely precise documentation that gives you the guidance you’d otherwise have to work out yourself. The Microsoft of the “COM+ era” (2000 and earlier) didn’t do so well on giving us either. And unfortunately it’s still very often the case that Microsoft’s technical marketing teams drop a technology like a hot potato once it has shipped and the launch events are over. And so ES still suffers from former negligence and in managed code land it’s clearly overshadowed by ASP.NET, Windows Forms and everything else that has design-time support and demos easily. Anyways, let’s dig in:   

Assume you had a ServicedComponent and you’d call it from a client application in the following way:

MyComponent myComp = new MyComponent();
myComp.MyMethod()

Surprising to many is that it turns out that the innocent looking “new” is sometimes the more costly of these two code lines. Invoking and executing the functionality you’ve been implementing might in some cases indeed be significantly quicker than constructing the component instance. Why is that so? Because constructing ES/COM+ component instances is a lot of work. The picture above is a simplified illustration of the moving parts involved in the process. (Mind that I am simplifying the explanation a bit. I’ve already written about the internals in 2003, but in a bit different context.)

The COM+ infrastructure is essentially an aspect engine that allows plugging interception sinks into the call chain that leads from the client proxy to the server component instance. Whenever a (any) COM object is constructed on Windows 2000 (or later), the CoCreateInstance(Ex) API function will route the request through a chain of “activators” that are registered in the COM+ catalog, which is a simple ISAM database with very fast read-capabilities that has been custom-built for COM+. If an component isn’t “configured” (registered in a proper COM+ application), the activation process shortcuts out of the activator chain and creates a “normal” COM object, otherwise the activator chain is fully processed. “Activators” are nothing but proper COM components implementing a special interface ISystemActivator whose CLSID is registered in the COM+ catalog. In the illustration about the activators are depicted as yellow circles. Whenever a new instance must be created, each activator is polled for whether it has interest in contributing a “policy” (blue rectangles) into the interceptor chain. It does so by checking the COM+ catalog for whether the component or the application has been configured to use the feature the activator is responsible for. Conceptually, each COM+ feature (Transactions, Security, JITA, Object Pooling) therefore has an activator even though one activator may (and in fact does) do the work for multiple features and install multiple policies.

A policy is also a COM component (or two) implementing the IPolicy and IPolicyMaker interfaces. The former interface has the interceptor methods that are being invoked before and after the method call and before and after leaving the context, the latter has methods for actually installing that interceptor into the call chain. The interceptor methods in IPolicy are the ones where the COM+ functionality actually sits. The transaction policy will open/close new transaction scopes here, the object pooling will pool/depool components, the JITA policy connects/disconnects instances, and the tracker starts and stops its stopwatch to measure the call times. The resulting policies form a sink-chain, which means that any policy can absorb a call or change the environment before it lets the call proceed. The policy objects have context-affinity, which means that they are created anew for each context.

What that all means is that whenever you create a new instance of your serviced component, you don’t create just one object, you create a whole lot and I haven’t really gone into the additional managed code object instances that are created for the proxy/dispatcher trickery of hooking it all up to the Remoting infrastructure. In addition to all that context setup work, a cross-process connection (on-machine and off-machine) does, of course, require a DCOM/MS-RPC connection to be established, which comes with additional cost.

And looking at all that internal effort that’s hidden in the guts of COM+/ES, it is now not very surprising that that creating a component is pretty costly, is it?

The goal for optimizing a COM+/ES application must therefore be to eliminate as much of that cost as possible. And it turns out that two of the policies sitting in the server context stage are incredibly helpful in getting this done. The “Just In Time Activation” feature of COM+/ES is in fact a policy that will drop the reference to the object instance on its right (in the illustration above) once the completion-bit in the context properties is set. Before it does so, it calls the Deactivate() method if the component supports IObjectControl. The object-pooling policy will grab such a deactivated object and move it into a server-side object pool is the object agrees to that by returning true from CanBePooled(). Even though the policy chain (“context”) has no active instance sitting at its far end, it is alive and doing quite well. Whenever the next call is made on the proxy, the call comes through the chain, the “Just in Time Activation” policy will create a new instance and, if present, the object pooling policy will supply one from the pool. Otherwise a new instance is created. The key aspect here is that the entire context and all that context setup work is reused, even though there’s an entirely new or a recycled component acting on the server side.

This is quite similar to databases where you have connections (context) and statements (instance/call). A serviced component proxy is not just a proxy. It’s got the whole policy chain and the server connection behind it. And as we know, database connections are pretty expensive to establish as well and therefore the infrastructure you use to connect to them (ADO, System.Data, OLE DB) commonly gives you “connection pools” from which pre-established connections are recycled even though the API creates the illusion that you are creating new connections every time you call Connect() or Open().  

Consequently and learning from the database folks, what we’ll do for optimizing ES is to steal that idea and build a connection pool. The downloadable file below contains an implementation of such a pool. The JustInTimeActivationProxyPool<T> class implements a simple, lockless, SMP safe pool of static size that keeps references to existing proxies. To create a pool on the client side, you will typically add a static field like  JustInTimeActivationProxyPool<MyComponent> myComponentPool to your client implementation and initialize it appropriately. Once you’ve done that, you can obtain a proxy with Pop() and return the proxy after use with Push(). Because all serviced components you write in managed code are implicitly multi-threading aware (MTA), this works perfectly well in multi-threaded environments.

However, due to the connection-oriented nature of COM, there’s a bit of a complication in case the server application recycles (stops and restarts). In that case, all the proxies you have cached are stale and will throw an exception with the HRESULT 0x800706bf (E RPC CALL FAILED DNE), which means that the call couldn’t be made. In that case you need to create a new proxy and simply reissue the call. The two other special cases for COM+/ES (security errors and general network failures aside) are those where the target application has been paused or disabled, in which case the proxies are also invalid. The older versions of my pool class did not address these issues, but this new one does.

The example below shows the proper usage of the pool with the pool’s Using() method and an anonymous inline method. This technique allows me to call the user code in three different contexts that I can establish inside the implementation of Using(). The first is when the call were to be executed within a preexisting transaction context, which disallows the use of pooled proxies, the second is the normal Pop()/Push() bracket around the call and the third is the new/Push() exception case for when the proxy is detected to be stale.

The “requirement” for the server component is that Just-In-Time Activation is enabled (the [JustInTimeActivation] attribute on the serviced-component class will do that and the [Transaction] attribute with the TransactionOption.Supported/Required/RequiresNew optional will implicitly do that, too) , even though stateful components could be pooled as well with this technique.

Download the code for the class below and try it out.

Yes, all the rumors are true. I am moving from the consumer side of things to the builder side of things. From February 1^st, 2006 I will be a “blue badge” and work for Microsoft as a Program Manager on the Windows Communication Foundation. The guys convinced me that it would be a good idea to make the move.

I’ve been spending so much time talking about and writing extensions for the shipping and not-yet shipping Microsoft distributed systems technologies stuff that it became the logical next step for me to become part of the team that creates all of these things. I hope that I can make some contribution to the cause.

As for why I am leaving my baby newtelligence? It’s the urge to build stuff that matters in a big way. Bart and Achim (my partners) have given me all the support they could since January in pursuing this goal. We’ve worked hard to put the company into a position that allows me to make this move and we are all delighted with the way things are. newtelligence is expanding its consulting business, continues to deliver world-class developer education and will continue to be a strong partner for our customers, which makes it easier for me to let go.

I’ll tell you more about it in the upcoming weeks…