One of the few (IMO) problems that Agatha suffered from, was that it sorta pushed you down the inheritance-road if you wanted to deal with cross-cutting concerns. Well, not anymore. Earlier this year, Bart Deleye started working on a way to use interceptor classes to do the same thing. It enables you to write small interceptor classes which just focus on one thing and have them executed before and after requests are processed. It's sort of similar to global action filters in ASP.NET MVC3, except that it's not attribute based. The order of execution is also guaranteed to be in the order in which the interceptors were registered. Bart and his team have been using this for a while now in their own projects, and recently contributed the changes back to the project. You can read more about these interceptors here and you can find some real examples here.

Another problem that Agatha suffered from was that there was no way to definitively know which type of Response corresponded with a certain type of Request. Because that was important to the interceptors feature, Bart went ahead and implemented something for that as well, so you can now define request/response conventions which can be used in your code. You can read about those here.

Those are the two most important new features, but some of you will be glad to hear that we finally have nuget packages as well. Because of the problem i described here, i ended up with 8 nuget packages:

• Agatha-Common-Castle-Windsor
• Agatha-ServiceLayer-Castle-Windsor
• Agatha-Common-Ninject
• Agatha-ServiceLayer-Ninject
• Agatha-Common-StructureMap
• Agatha-ServiceLayer-StructureMap
• Agatha-Common-Unity
• Agatha-ServiceLayer-Unity

The packages for Castle Windsor, Unity and Ninject each support Silverlight as well. All container dependencies are now based on their latest Nuget packages. With Agatha 1.2, it was clear that the majority of people downloaded the source code instead of the binary release (i presume to build against whatever version of container they used) so you can still get the entire source package on Google Code or on Github. I didn't create another binary package since i figured that most people who want that will be using Nuget anyway.

The two other changes are:

• now possible to POST to the IWcfRestJsonRequestProcessor (contributed by Andrew Rea)
• our container abstraction allows key-based resolving (contributed by Nikos Baxevanis)

My favorite part about this release is that all of the new code has been contributed by other people

For 1.4, the focus might be more about making Agatha as easy as possible to consume from JavaScript, which may or may not introduce a new REST based service interface. Though none of that is certain at this point, so we'll see how it goes

Now how do you make that fit into the Nuget packaging system? Ideally, Nuget would someday support a scenario where i can define that my package requires the user to also select one package from a list of suitable packages but until that's possible i can't really come up with a solution that i like. Here's what i specifically don't want:

• I don't want the package to include something that the user might not want.
• I don't want to force a particular container on users
• I don't want to ILMerge any container assemblies because that would cause problems if users themselves make use of a container already.
• I don't want to do it like the current NHibernate 3.1 package because that pretty much guarantees nobody will install it. NHibernate can get away with something like that because it's already an established project.

Ideally, i'd be able to define the following package structure:

• Agatha-RRSL, requires one of the following packages to be installed (if no selection is made, go with Agatha-Windsor by default):
  • Agatha-Windsor, depends on Agatha-RRSL and Castle Windsor
  • Agatha-StructureMap, depends on Agatha-RRSL and StructureMap
  • Agatha-NInject, depends on Agatha-RRSL and NInject
  • ... (one for each supported container)

If that were possible, users wouldn't have to include anything they don't like and it could work together nicely with the packages of the various IOC containers.

As for how it should be packaged for now, i still have no idea. Suggestions are welcome

This week i was introduced to Membase, a great distributed caching solution which is very easy to set up. I wanted to see what it would take to make Agatha's server-side caching work with Membase. With a little help from the Enyim Membase client, it turned out to be very easy. If you want to change the actual caching implementation that Agatha uses, you have to implement 2 interfaces. First, you'll need a custom implementation of the ICache interface:

    public class MembaseCache : ICache
    {
        private readonly MembaseClient membaseClient;

        public MembaseCache(string region = null)
        {
            // this implementation assumes password-less buckets
            membaseClient = new MembaseClient(region, null);
        }

        public Response GetCachedResponseFor(Request request)
        {
            return membaseClient.Get<Response>(GetKey(request));
        }

        public void Store(Request request, Response response, TimeSpan expiration)
        {
            membaseClient.Store(StoreMode.Set, GetKey(request), response, expiration);
        }

        public void Clear()
        {
            membaseClient.FlushAll();
        }

        private static string GetKey(Request request)
        {
            return string.Format("{0}_{1}", request.GetType().FullName, request.GetHashCode());
        }
    }

With Agatha's caching, you can use regions in your caching configuration. A region corresponds with a bucket in Membase. If you don't specify a region name when configuring caching for a response, Agatha will use the default region which is named _defaultRegion. You will need to create at least the _defaultRegion bucket in your Membase cluster, and you'll also need to create a bucket for each other region you use in your caching configuration. When your service layer is initialized, Agatha will create an ICache instance for each known region to be used.

Then you'll need an ICacheProvider implementation:

    public class MembaseCacheProvider : ICacheProvider
    {
        public ICache BuildCache(string region)
        {
            return new MembaseCache(region);
        }
    }

Now, because the Enyim Membase client uses binary serialization of cached objects by default, we're going to provide our own ITranscoder (defined in the Enyim assembly) implementation which uses the DataContractSerializer:

    public class MembaseTranscoder : ITranscoder
    {
        public CacheItem Serialize(object o)
        {
            using (var stream = new MemoryStream())
            {
                var serializer = new DataContractSerializer(typeof(Response), KnownTypeProvider.GetKnownTypes(null));
                serializer.WriteObject(stream, o);
                var data = stream.ToArray();

                return new CacheItem(((ushort)(((ushort)Type.GetTypeCode(o.GetType())) | 0x100)),
                    new ArraySegment<byte>(data, 0, data.Length));
            }
        }

        public object Deserialize(CacheItem item)
        {
            using (var stream = new MemoryStream(item.Data.Array.Skip(item.Data.Offset).ToArray()))
            {
                var serializer = new DataContractSerializer(typeof(Response), KnownTypeProvider.GetKnownTypes(null));
                return serializer.ReadObject(stream);
            }
        }
    }

That's actually all we need to support distributed response caching with Membase. To use this, you'd need to add this to the configuration file of your service host:

  <membase>
    <servers bucket="_defaultRegion">
      <add uri="http://localhost:8091/pools/default" />
    </servers>
    <transcoder type="Agatha.Common.Caching.MembaseTranscoder, Agatha.Common" />
  </membase>

Obviously, you'd need a bucket definition for every region that you'd use and you'll probably need a different bucket URI as well

You'd also need to configure Agatha to use the MembaseCacheProvider implemention:

            var config = new ServiceLayerConfiguration(Assembly.GetExecutingAssembly(), 
                typeof(HelloWorldRequest).Assembly, typeof(Agatha.Castle.Container))
                            {
                                CacheProviderImplementation = typeof(MembaseCacheProvider)
                            };
            config.Initialize();

And that's it... distributed caching of service-layer responses has never been this easy

Note that i haven't committed this implementation to Agatha's Subversion repository... the plan is to add it in the 2.0 version, which will have many more changes (more on that in a future post). But if you need it already, or you need inspiration for an implementation that targets a different distributed caching server, the information in this post should get you going.

I didn't even know there was a NuGet package for Agatha, so this was a nice surprise. I have no idea who made the package, but thanks

• Client-side caching (BREAKING CHANGE: EnableResponseCachingAttribute no longer exists, use the EnableServiceResponseCachingAttribute instead) -> this is not supported in the in-process model
• RequestProcessor now has an AfterHandle(request, response) virtual method which is called after the request has been handled by the handler
• ReceivedResponses now has a Responses property which returns all of the retrieved responses
• ExceptionInfo now has a FaultCode property (string) which will be automatically filled in as long as your BusinessException type contains a FaultCode property (thanks to a patch from Huseyin Tufekcilerli)
• Agatha.Spring has been included (thanks to a patch from Jernej Logar)
• Agatha.StructureMap.Container has been fixed so that it instructs StructureMap to use the default constructors of RequestProcessorProxy and AsyncRequestProcessorProxy (thanks to a patch by Bart Deleye)
• Added BeforeResolvingRequestHandler virtual method to the RequestProcessor which gets called right before a RequestHandler is resolved through the container
• Fixed logging of WCF messages where some requests were logged as "... stream ..." (thanks to patch by Bart Deleye)
• Added Agatha.Ninject.Silveright (thanks to patch by Bart Deleye)
• Updated Agatha.Unity and Agatha.Unity.Silverlight to use the 2.0 version of Unity
• Applied patch from Andrew Rea to improve REST support (xml and json)

Thanks to everyone who contributed to this release. It's very nice to see the list of contributors growing with each release

You can download the source code or the binaries here.

Usage of the client-side caching is practically identical to usage of the server-side caching feature, which means you have to use the EnableClientResponseCaching attribute on your request types where you want to use caching, and they have to implement the Equals and GetHashCode methods properly (read this post for more info on this).

Here's a small example from the Sample that is included in the Agatha source code:

    [EnableServiceResponseCaching(Minutes = 5)]
    [EnableClientResponseCaching(Seconds = 30)]
    public class ReverseStringRequest : Request
    {
        public string StringToReverse { get; set; }
 
        public bool Equals(ReverseStringRequest other)
        {
            if (ReferenceEquals(null, other)) return false;
            if (ReferenceEquals(this, other)) return true;
            return Equals(other.StringToReverse, StringToReverse);
        }
 
        public override bool Equals(object obj)
        {
            if (ReferenceEquals(null, obj)) return false;
            if (ReferenceEquals(this, obj)) return true;
            if (obj.GetType() != typeof(ReverseStringRequest)) return false;
            return Equals((ReverseStringRequest)obj);
        }
 
        public override int GetHashCode()
        {
            return (StringToReverse != null ? StringToReverse.GetHashCode() : 0);
        }
    }

In this case, both the EnableServiceResponseCaching and EnableClientResponseCaching attributes were used, which means that responses for this request will be cached for 5 minutes on the server, and for 30 seconds on the client. You don't have to use both attributes simultaneously, you can use either one of them as well depending on where you want to cache the response. You can also set a region (like you can with the server-side caching) so you can explicitely clean a certain region of the cache if you need to at some point.

Everything happens transparently from your code. If you make a service call with one request, and there is a cached response available for that request, the service call is not made and you'll get the cached response. If you send a batch of requests, and there are cached responses available for any of those requests, the call that is sent to the service will only include the requests for which no cached response was available.

There are only two things you need to do to use Agatha’s server-side caching feature:

1. Use the EnableServiceResponseCaching attribute

If you want certain Request-derived types to be eligible for caching, you need to put the EnableServiceResponseCaching attribute on top of them.  This attribute enables you to set the logical region (more on that later) where the Response for this Request needs to stored in the cache, and it requires you to set an expiration.  Here’s a simple example:

For this particular request type, responses should be cached for a maximum duration of 10 minutes, and the cached responses will be stored in the Issues region.  A region is pretty much just a section within the cache.  If you don’t specify a region, each response will be placed in the default region.  If you do specify one, each cached response for that region is placed within that section.  This gives you the ability to clear an entire region (and thus, all the cached responses that are stored in that region) without impacting any of the other regions (including the default one).

The expiration can be configured by providing a number of hours, minutes or seconds (or a combination of those three) to the attribute.

Now obviously, Agatha needs a way to differentiate between multiple instances of the GetUnassignedIssuesForProjectRequest class.  More specifically, Agatha needs to know when a request can be considered equal to a previous request for which a response has already been cached.  So that brings us to the next thing you need to do:

2. Override the Equals and GetHashCode methods

The response for a GetUnassignedIssuesForProjectRequest instance with ProjectId set to e35c60f7-c35e-43db-9988-0dab3f39c61b will obviously contain a different set of unassigned issues than one for a GetUnassignedIssuesForProjectRequest with ProjectId set to 5d47161a-f334-4cce-9cc4-9606a9d294a6.  To make sure that Agatha knows which response can be returned for a given request, your request needs to override the Equals and GetHashCode methods so you can tell Agatha when an instance of a certain request can be considered equal to one for which a cached response already exists.  In the case of our example, requests of type GetUnassignedIssuesForProjectRequest can be considered equal if they both return the same value through their ProjectId property.  So in this case, our request class needs to look like this:

Now that we have an Equals and a GetHashCode method which only looks at the value of the ProjectId property, Agatha can differentiate between different requests on a value basis instead of a reference basis.  Note that this doesn’t mean that your request types need to be value objects in the truest sense of the term.  They just need to be able to perform an equality check based on the values that make the difference between actually handling the request, or returning the response that has previously been cached for the set of values that you’re using to determine equality.  Simply overriding the Equals method is not enough, since Agatha will use these instances of requests as keys in a dictionary so you need to provide a proper GetHashCode implementation as well (which is recommended anyway if you’re overriding the Equals method).

It’s very important to really consider which properties you want to include in the equality check and the hashcode calculation.  If your request type inherits from some base request (typically one that contains user credentials and stuff like that), then you typically don’t want to include those inherited property values in your equality check, unless you really want to cache different responses based on one of those inherited properties.  I’d recommend writing enough tests to verify that your equality checks and hashcode calculations indeed behave the way you want them to because if they don’t, you will either get suboptimal results from Agatha’s caching or even incorrect ones which would lead to bugs that will be very hard to debug.

A question that came up recently in the Agatha discussion group was how to implement the Equals and GetHashCode method for request types for which each instance should really be considered equal.  For instance, a request type like this:

In this case, the default Equals and GetHashCode implementations will be reference-based and not value based.  But as you can see, there are no values to differentiate between requests.  In this case, there is only one way to retrieve the known Countries in this system, so how do we implement the Equals and GetHashCode methods so this request type can be used correctly with Agatha’s caching layer?  Well, the solution isn’t very nice but it is pretty simple.  You can just introduce a dummy field with a fixed value:

Now, every instance of the GetAllCountriesRequest will be considered equal to each other and they’ll all return the same hashcode as well.  So every incoming instance of this request will return the same cached response (once it’s been cached that is).

That’s pretty much it.  In itself, the caching layer of Agatha is very easy to use, but you definitely need to make sure that your Equals and GetHashCode implementations are correct.  That’s pretty much the only tricky part (and downside) to how Agatha’s caching works, but i was unfortunately unable to come up with something that was easier to use.

One final word on the usage of regions.  If you’re caching responses, then you typically want a way to remove stale responses from the cache.  If some of the data that you’re caching is changed before the cached responses expire, you can clear the region in which those cached responses are being stored.  Just add an ICacheManager constructor parameter to your handler (or any other class for that matter) and call the Clear method which takes a region name as a parameter.

As always with caching: be careful in how you use it, and make sure you think it through

First of all, make sure your service exposes its metadata.  You do this in the usual WCF fashion:

The serviceMetadata element with the httpGetEnabled=”true” attribute is the important one in the snippet above.

After that, you can simply generate a service proxy through visual studio or svcutil or whatever:

Now you can write the following code to communicate with your Agatha Service Layer:

Notice that there are no Agatha-related using statements, nor is there any reference to Agatha or the assembly which contains the Request/Response types. All of the required data can be found within the WSDL and you can generate proxies for it just as you could with any other WCF service.  The client-side usage model is of course as bad as it always is with standard WCF (for more information, be sure to read: Why I Dislike Classic Or Typical WCF Usage) but if you’re willing to put up with it, then at least you can

This also means that you should be able to generate service proxies for other platforms as well, as long as they support SOAP services.

These are the changes between the 1.0.1 and the 1.1 release:

• Support for the NInject container (patch contributed by Ian Davis).
• First version of the server side caching layer.  Consider this implementation to be experimental and there are most likely plenty of issues with it.  Issues that pop up will obviously be fixed in further 1.1.x releases and the trunk as well. 
• AsyncRequestDispatcher and RequestDispatcher now have a virtual AfterSendingRequests virtual method where you can add some custom code if you need to.
• Both Request/Response types and RequestHandler can now be located in multiple assemblies (patch contributed by Jason Diamond)
• Castle Windsor binaries have been updated to version 2.1
• Castle support for Silverlight has been added
• The Process method of the IWcfRequestProcessor service contract now allows transaction flowing
• All configuration classes have been made a bit more fluently (thanks to Mark Meyers)
• There is now an Agatha.Servicelayer.Silverlight assembly which contains a lightweight version of the service layer to run within your Silverlight application if you want/need this
• Support for the StructureMap container (patch contributed by Andrew Rea)
• The IWcfRequestProcessor service contract now supports REST (JSON + XML) (patch contributed by Andrew Rea)
• RequestDispatcher contains a BeforeReturningResponses method where you can put some additional code to modify responses before they are returned to the consumer of the dispatcher.
• The serverside RequestProcessor contains a few extra virtual methods which enables you to customize how exceptions are logged (patch contributed by Emil Ingerslev)
• Fixed NullReferenceException in MessageInspector when using one-way requests in combination with INFO logging

So basically, everyone that’s been running on the trunk is probably better off using the 1.1 version, unless you’re willing to move to .NET 4.

You can download the 1.1 version here.

The goals for the 1.2 release are to take as much advantage as possible from new .NET 4 and WCF 4 improvements, and also to make the caching layer as good as it can be.  And yes, that will include some form of client-side caching

First of all, the Silverlight client’s WCF config has 2 defined endpoints:

Notice that each endpoint has a defined name.

Now you can create 2 new service proxies which inherit from Agatha’s proxy:

Once you have those proxies, you can create new request dispatchers, which also inherit from Agatha’s:

If you register those types with your container (make sure it’s the same container instance that Agatha uses) and you can have the correct dispatchers injected for whichever service you want to communicate with.  But in the case of asynchronous request dispatchers, you typically use a factory to get them, so you probably want to add something like this:

And there you go… inject the proper factory (or both of them) and just use whichever one you need to get a dispatcher for the service you want.

So, i figured i’d just ask you guys.  Have you used Agatha? Did you have positive experiences with it? If so, i’d really appreciate any testimonials you can send me (email address is ralinx at the domain name of this blog).  Not only do i get to read about your experiences, i can add them to the project site as well which does kinda boost the credibility of the project for people who never heard about it before.  If you’re willing to write such a testimonial (which only needs to be one or two sentences, though something longer than that is more than welcome as well), please include your name, your jobtitle and the name of your company in the email.

Also, if you have tried it and were not happy with it or ran into problems with it, i’d definitely like to hear from you as well so i can look into possible solutions or improvements.

Thanks!

I don’t like to tie myself to WCF-specific features, so i always plug in custom authentication into either a custom Request Processor, or a base Request Handler class that all other Request Handlers must inherit from.   But first, how do we get the authentication-related data from the client to the service?

In each project i use Agatha in, i always have a MyProjectRequest and MyProjectResponse base class:

Each request in the project inherits from this base request, and each response inherits from the base response.  The base response class is often empty, though this does make it very easy if you ever need to send something back with every response.

Now obviously, if every single request that is sent to your service layer needs values for the UserName and PasswordHash properties you want this to be done in only one place.  I do this by using a custom request dispatcher:

The IUserContext dependency is just a component that is registered in my IOC container and will be injected automatically whenever you get an instance of IAsyncRequestDispatcher.   Now, in this example you can see that i add the authentication data to every request in a batch, even though the batch will be sent in one roundtrip.  If you want, you can add the authentication data only to the first request and then only use the first request to do the authentication within your service layer.  I prefer to add the authentication data to each request and then authenticate every single request (even subsequent requests in a batch) within the service layer.  I’ll get back to this point later on.

Now, the only thing we need to do to make sure that your requests will always have the authentication data contained within them is to instruct Agatha to always use instances of your MyProjectAsyncRequestDispatcher class whenever an IAsyncRequestDispatcher is needed.  This is easily done during Agatha’s client-side configuration:

Keep in mind that you still have to register your IUserContext with the container on your own though. 

With that in place, we are sure that each request that comes from our clients always contains the proper authentication data.  Now we need to make sure that we actually authenticate these requests within the service layer.  You basically have 2 options: either implement your own Request Processor which adds authentication checks, or create a base Request Handler that your other Request Handlers inherit from.

We’ll first cover the option of using a custom Request Processor.   You could create one like this:

The BeforeHandle virtual method is called right before the request is passed to its Request Handler to be handled.  Note that this Request Processor would authenticate every request.  If you want a Request Processor that only authenticates the first request, you could do so like this:

The BeforeProcessing virtual method is called before any of the requests are handled, so you could authenticate only the first request in a batch and then proceed with regular processing if the first one is authenticated.  Now, the big problem that i have with this approach is that you aren’t really in control of what is sent to your service layer.  Yes, you can guarantee that each request coming from your clients contains the proper authentication data.  What you simply can’t guarantee however is what other people or custom clients can send to your service layer.  If they send you a batch of 2 requests, the first containing valid credentials of a normal user for a benign request, it will pass the authentication just fine.  If the second request in that batch contains invalid credentials (to trick your authorization into believing it’s from a user with higher privileges for instance) for a request that could cause some damage (deleting important information or triggering certain tasks or whatever), then you can’t really do anything to prevent that.  Unless of course, you reject this approach and authenticate every single request.

As for the MySecurityException type, that’s up to you as well.  When you configure your Agatha service layer, you can set the SecurityExceptionType property to the type of exception that should be considered as a security exception.  When the Request Processor catches an exception of that type, it will set the ExceptionType property of the response to ExceptionType.Security so you can check for that specific situation in your client.

To configure Agatha to use your custom Request Processor, your configuration code would look like this:

Another alternative is to create a base Request Handler for your project and to have each Request Handler inherit from it.  Something like this, for instance:

In case you’re wondering why i’m using Setter-injection here instead of Constructor-injection, read this.

I typically prefer the custom Request Handler approach for authentication.  In most applications that we write, authentication is not enough and we need custom authorization checks for many requests.  So i’m going to need a base Request Handler which introduces the virtual Authorize method anyway.  So i might as well do my authentication check right before it.

With the custom Request Handler approach, you probably still want to configure Agatha to use your custom security exception type:

And then you just need to let your own Request Handlers inherit from your MyProjectRequestHandler.  Authentication will be performed for each request by default, and you can easily add specific authorization logic for every request. 

And those are pretty much the options you have to secure your Agatha Service Layer.   Oh, and be sure to only expose your Service Layer through SSL

Agatha is a Request/Response Service Layer framework.  It basically supports synchronous and asynchronous Request/Response style communication and tries to make it as easy as possible to write a service layer for that type of communication.  Apart from being easy to use, it also encourages a clean implementation of your service layer and a way to minimize the repetitiveness of cross-cutting concerns.  It also enables you to get better performance than with typical Remote Procedure Call or Remote Method Invocation style service layers because it will try to minimize roundtrips by batching requests and responses together.  In the next release, it will also offer a caching layer so certain requests (depending on how you set it up) don’t need to be processed and cached responses can simply be returned.  There’s also support for one-way requests (or fire-and-forget requests) but it has the same downsides as one-way requests with typical WCF services have. That’s pretty much all it does.  That’s probably all it’ll ever do.  In short, it’s just an upgrade over your typical WCF services.

NServiceBus on the other hand also does Request/Response, but that’s just one of the things it can do.  Again, Agatha is essentially an RPC or RMI framework whereas NServiceBus is built on top of one-way messaging technology.  This allows for much more possibilities when it comes to communicating between different applications or different parts or processes within the same application boundary.  A great overview of those possibilities can be found here.  Because it is based on messaging, there are a lot of benefits that you can get from NServiceBus that you’ll probably never get from Agatha.  For one, the ‘Store & Forward’ messaging model from NServiceBus might seem similar to Agatha’s one-way requests on first sight, but there are some very important differences.  If you send a fire-and-forget request with Agatha, and the service is currently down, then that request is essentially lost.  With NServiceBus, the message is stored in a message queue and it will be processed when the target of the fire-and-forget message comes up again.  From a reliability point of view, that’s obviously a tremendous improvement over what Agatha can offer you.  Another area where NServiceBus truly shines (IMO) is in its Publish/Subscribe implementation.  Some people have asked me if i’ll ever provide something like that in Agatha and the answer has always been ‘no’.   For one, it doesn’t fit into what Agatha tries to do and i don’t see the point in implementing it if a better implementation is available already in another project.   There’s plenty more interesting things in NServiceBus to deal with more advanced scenarios, which you’ll have to find out about on your own

So which one is more suitable for you or your applications? As with every technology choice, it depends.  Agatha is great for most typical business applications.  If you need to communicate between one or more different clients (with different i don’t mean multiple instances but different types of clients like a web app, a silverlight client and/or a WPF client) and one service (you can obviously use it with more than one service as well if you want to) on an application server which encapsulates your business layer then it is a very attractive solution, as long as you don’t need the superior reliability that NServiceBus can offer you.  With superior reliability i particularly mean the ability to still process received messages once the service layer comes back up after having been unavailable.  In my experience, most business applications don’t really need that, since most of those applications are entirely unusable if the service they depend on is down.  In short, if all the possible downsides of using a WCF service layer are not an issue for your project, then Agatha will be a great fit.

If however, you need to maximize reliability, performance and general robustness of a critical enterprise application, then NServiceBus will definitely be a much better choice.  If you’re dealing with many distributed parts, NServiceBus will also make things much easier for you than Agatha (or any other WCF service layer for that matter) will.   And obviously, if you want to integrate multiple applications while reducing coupling between applications as much as possible, NServiceBus will also be a much better fit than Agatha.  With NServiceBus, you’d only need to share an assembly containing the types of the messages.  With Agatha, you either need to share an assembly with shared request/response types or use proxies for them and you would also have to know about the other applications since you’d need to access their services directly.  This can get quite ugly pretty fast.

And in some cases, you can just use both of them at the same time.  At work we have two projects that use Agatha for all of their internal communication within their own application boundary, yet they use NServiceBus to notify each other of certain events.  Neither of the applications knows about the existence of the other… the only thing they share is one assembly with some shared message types.  We’ve also started working on a new platform where each application in the platform will use Agatha for all of the communication within their own application boundary (since they’re all typical silverlight clients backed by a WCF service style applications) but they will use NServiceBus for every kind of communication that goes outside of the application boundary.

As with many things, it’s just a matter of choosing the right tool for the right job.  Hopefully, this post will help some of you make that decision should you need to make it in the future

First of all, requests whose response is eligible for caching must override the Equals method and the GetHashCode method.  I’ll use the following two request/response combinations for this test:

Agatha’s Request Processor should cache responses for requests that are eligible for caching, and when subsequent requests need to be processed which are equal (in their values) to previous requests whose response has been cached already, the cached response needs to be returned instead of handling the request again.

In order to inspect the usage of the caching layer during tests, i wrote the following CacheManagerSpy class which inherits from my normal CacheManager class (which is used by Agatha):

This Spy basically gives me the ability to see which entries are stored in the cache, and which responses have been returned.

Now i can create a QuickNet Acid test.  I’m going to go over the code step by step instead of listing it all at once because each step probably needs quite a bit of explanation if you don’t understand QuickNet yet.

First of all, here’s the definition of the test:

The 10 means that QuickNet will perform 10 testruns.  The 2000 means that each testrun will contain 2000 executions of the defined transitions.  Don’t worry yet about what a transition is, i’ll get to that later on in the post.

We’ll also need some fields to access some of the classes that will be used in this test:

Yeah, i know what you’re thinking.  Static is bad right?  Well, not in this case since we need to be able to use these instances in some inner classes that we’ll go over soon enough and these references will hold the same instance for each testrun (which, as mentioned consists of 2000 transition executions).  Anyway, forget about the static keyword for a second and keep reading.

Now we can implement the SetUp of our testrun:

This setup code will be executed for each testrun.  So QuickNet will execute this 10 times, and each time it will run 2000 transition executions on the classes that we set up for the current testrun. 

So what exactly is a transition? It’s just a piece of code that you want to execute.  That piece of code can receive input and it can return output.  It’s basically the code that you’re testing.  Our transition will simply consist of calling Agatha’s Request Processor and instructing it to process 2 requests.  Those requests would be the two request types shown earlier which are eligible for caching.  After QuickNet executes the transition, it will also verify that our defined specifications for that particular transition are indeed correct.

Let’s define the input that our transition will receive.  In this particular case, we need a Request instance, an instance of a Request Handler for that Request, and the Response that the Request Handler needs to return if there’s no valid Response available in the cache.  So we’ll use the following helper class to define this input:

An instance of this class basically combines the Request, its Request Handler and the Response that needs to be returned.  It also contains a helper method so we can easily instruct the mocked Request Handler to return the given Response when it is asked to handle the given Request.  And we’ll also set a simple flag to true if the Request Handler has indeed been called.

As i mentioned a few times already, QuickNet will execute our transition (which i’ll show later on in the post) 2000 times for each testrun.  Obviously, we can’t be expected to create these instances manually all the time, so we need to define some generators that QuickNet will be able to use to randomly generate the input that it can pass to the transition.  We first need two generators which are capable of generating random instances of the FirstCachedRequest and SecondCachedRequest types:

The FirstRequestGenerator class is capable of returning a new instance of FirstCachedRequest whenever it is asked to do so, and it will populate the FirstCachedRequest instance’s String property with a random string consisting of one character.   Some of the generated instances will be considered equals of each other if the generated string value is equal, and some will not be considered as equals if the generated string value is not equal.  The SecondRequestGenerator basically does the same thing, except that it will populate the SecondCachedRequest instances’ Integer property with a random int value between 0 and 5.  So again, some of the generated instances will be considered as equals, and some won’t.   The important part to remember is that QuickNet will generate random instances for us and that we don’t have to worry about it.

Now that we have the generators for the request instances, we can write a generator which can generate random ProcessInputElement instances:

Actually, this generator doesn’t just generate one instance of ProcessInputElement, it generates a tuple consisting of two ProcessInputElement instances.  The first value in the tuple will always contain a random instance of FirstCachedRequest, its Request Handler and a FirstCachedResponse instance that needs to be returned by the Request Handler if there’s no cached response yet.  The same goes for the second value in the tuple, except that it has a random instance of SecondCachedRequest, its Request Handler and a SecondCachedResponse instance.

Again, every time QuickNet will execute our transition, it will ask the ProcessInputTupleGenerator to generate a new tuple, and that tuple will contain the random request instances.  The generated tuple is then passed into the transition and the transition will be executed.

Now i can finally show you the transition that we’ll define:

As you can see, the ProcessRequestsTransition inherits from the MetaTransition<TInput, TOutput> class.  So we basically just defined that the input of the transition is a Tuple<ProcessInputElement, ProcessInputElement> and the output is an array of Response objects.  In the constructor of the transition, we define that the generator to be used to generate the input values is the ProcessInputTupleGenerator.  And we also define what actually needs to be executed by the transition.  In this case, the piece of code that will always be executed will first clear the CacheManagerSpy instance (so we can safely inspect it during our specification verification), it will then prepare both Request Handler mocks and then it simply calls the Process method of the Request Processor.  It’s output (a Response array) will be the output of the transition since that is our return value.

After all that work, we can finally define our specifications for this transition.  Let’s start with the first one:

The SpecFor attribute makes it possible to define which Transition this Spec belongs to.  The method has 2 parameters, which correspond with the input that will be passed into the transition, and the output that the transition returned.  It’s very important to realize that this method is executed before the transition is executed (yet after the input has been generated), but the block of code that we pass into the Spec instance will only be executed after the transition has been executed.  Actually, that block of code will only be executed if the Spec’s precondition and postcondition have been satisfied.  The precondition (which can be defined with the Spec class’ If method) will be evaluated before the transition is executed.  If it evaluates to false, the spec will be ignored for the current execution of the transition.  The postcondition (which can be defined with the Spec class’ IfAfter method) is evaulated after the transition is executed.  If it evaulates to false, the spec will be ignored.  If it evaluates to true, the spec will be verified using the input that was passed into the transition and the output that was returned from the transition.

For this particular spec, we define a postcondition that the spec only needs to be verified if the CacheManager returned one or more null values instead of cached responses.  If the CacheManager returns a null, it means that there was no cached response for the request it was given.  And that is when we need to verify the following things:

1. The request was handled by the Request Handler
2. The response that was returned by the Request Handler has been put in the cache
3. The response array that was returned by the Request Processor contains the expected response

We perform this check for both requests, or only one of them, depending on which one was not in the cache yet.  Remember that the transition will be executed 2000 times using the same request processor and the same cache manager.  Which means that cached responses from previous transition executions might still be in the cache.  Also keep in mind that one of the request types has a defined expiration of 1 second, and the other an expiration of 2 seconds which means that there will be plenty of transition executions where they are either both in the cache, only one of them, or none of them.  All of those cases are now covered with the code in this spec.

Here’s another spec:

Here we verify that when a cached response was returned by the CacheManager:

1. The Request Handler was not executed
2. The response array returned by the Request Processor contains the cached response

We again perform this check for both requests, or only one of them depending on which one had a cached response.

You might think that this was a lot of work, but was it really?  It’s about 160 lines of code, and i’m quite sure that the functionality that i’m testing is covered much more thoroughly than it would’ve been with 160 lines of code for classical unit tests.   In fact, i challenge each one of you to come up with a more thorough test for this in less than 160 lines of code.  Also, i can keep adding specs quite easily and those really don’t contain that much code.  But my functional coverage would increase dramatically, much more than it would with classical unit tests.

Granted, the learning curve is steep as i mentioned already in a previous post.  But once you start to get it, you become pretty productive with it and you’ll catch a lot more bugs before you deliver your software because of it.

Now, i tried hard to make everything here as clear as possible, so i’d love to hear from you whether or not:

1. you understood it
2. you like it
3. you think it’s way over the top
4. you want to start doing this too

Before i discuss the two bugs, i’d like to explain what the exception handling quicknet test does, and how it works.  It basically calls the request processing code a bunch of times, each time with a set of requests where either none, one or more of the request handlers will throw an exception during the handling of the requests.  The order of the exceptions or which handlers will throw an exception is completely randomized (thanks to QuickNet) and thus it varies from test to test.  This particular QuickNet test will perform 50 testruns, where each testrun consists of 50 transitions that will be executed.  Each transition is a piece of functionality that will be executed (in this case, the processing of requests) with randomized input (in this case, there is a fixed set of requests but which ones will fail will differ with each run of the transition) and after a transition is executed, the relevant specs are verified (in this case, a bunch of checks to make sure that the whole error handling functionality always does what it needs to do) to make sure that the piece of code that you’re testing (your transition, in this case the processing of requests) actually works.

Instead of testing with a mocked caching layer, i used the real thing in the tests.  I also added 2 cached request types to the test request types, and gave one of them an expiration of 1 second, the other an expiration of 2 seconds.  This means that during the entire QuickNet testrun, some requests will return cached responses, some won’t, some cached responses will expire and subsequent requests of that particular type need to be executed and have their responses cached again until they expire.   In the meantime, QuickNet is constantly firing requests at the RequestProcessor, and some of them will randomly fail.  Our specs need to verify that the returned responses always contain the correct exception information for the batch of requests that was processed.

And here’s the beauty of the whole thing.  I hadn’t even thought about how exception handling also influences how you deal with cached responses.  I didn’t take exception handling into account when adding the caching code, and without even adding specific tests to see whether the caching worked correctly, my QuickNet specs that intended to cover something that doesn’t really have anything to do with caching uncovered 2 issues with my caching code.   I was suddenly getting error messages from QuickNet that in some cases, the exception information wasn’t correct.   And it frequently took over 30 executions of the transition, or sometimes multiple testruns before some of those specs would fail.  The longer it takes for a bug to show up in a QuickNet test, the better the bug is at hiding and the harder it is to find it manually because it almost certainly is an edge-case that you hadn’t considered at all and that only occurs in certain situations.

And those are the type of bugs that you typically don’t find with traditional unit tests.  When you write traditional tests that are aimed at asserting correct behavior, you typically only write tests for the problems that you thought about.  Sometimes you’ll get lucky and traditional unit tests will inform you of incorrect behavior that you didn’t think of,  but it rarely happens for the edge-cases.  And those are the bugs that can be really hard and painful to find and fix.

By now you’re probably wondering what the two bugs are.  The first one is that if an exception occurs during the handling of a request which is eligible for caching, the response with the exception information would be stored in the cache, and the next time that that particular request would be processed while the cached response hadn’t expired yet, you’d simply get the original response with the exception information again instead of actually handling the request again (which might have been handled successfully this time).  The second bug was that if an earlier request in the batch of requests already failed, it could possibly return a valid response later on in the same batch for one of the cached requests if its response hadn’t expired yet.   Pretty stupid huh?  But they were there nevertheless, and sooner or later somebody would’ve tripped over it and it would’ve caused frustration for the user who would run into it, and pain for me because i’d have to go looking for it long after i’d written the code.

Again, i seriously doubt that traditional unit tests would’ve prevented the existence of these 2 problems since it never occurred to me while i was writing it.  The QuickNet tests did find it, even before i added specific tests for the caching functionality to them, which i found pretty impressive and a huge benefit to this sort of testing.  Granted, the learning curve for writing valuable QuickNet tests is steep (i’m not even halfway there IMO) and it takes a lot of effort when you’re starting out with it.  But if it helps me prevent the sort of bugs that are otherwise easily missed and could negatively influence the perception of my project, then i definitely consider it worth it.

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.

 

Copyright [yyyy] [name of copyright owner]

 

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

 

http://www.apache.org/licenses/LICENSE-2.0

 

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

This sort of implies that i’m required to put this boilerplate notice in each file, which is just tedious and the odds are pretty high that you’re going to forget to put this in one (or more) of the files that will be added later on.

Instead, i put a LICENSE.txt file in the root folder of the project with the following content:

Copyright 2009 Agatha RRSL Project, original authors and contributors

 

Licensed under the Apache License, Version 2.0 (the "License");
you may not use the files in this directory structure except in compliance with the License.
You may obtain a copy of the License at

 

http://www.apache.org/licenses/LICENSE-2.0

 

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Honestly, i have no idea if i’m allowed to do that.  I can’t think of a reason why i shouldn’t be able to do this since it certainly sounds reasonable to do so, but then again i’m not a lawyer and i wouldn’t be surprised if there are reasons for not doing so.  If anyone can provide advice on this, it would be much appreciated

Another thing that left me wondering is the actual copyright notice.  In the 1.0 release, i unfortunately used the following copyright statement for both the LICENSE.txt as well as the copyright information on the assembly level:

Copyright 2009 Davy Brion

Now, i did write most of the code, i did start the project and i do own the project.  But i did not write all of the code as there have been some contributions from other people.  I certainly want to give credit where credit is due, so i’ve changed that copyright notice (both in the LICENSE.txt file and the assembly copyright notices) to:

Copyright 2009 Agatha RRSL Project, original authors and contributors

I then added a CONTRIBUTORS.txt file at the same location of the LICENSE.txt file which contains the names of the contributors and the parts they worked on.  I think that’s all i need to do to to be fair and correct, but again, i’m not entirely sure on this.

If anyone can provide feedback on these issues, please do so

As for the next version (1.1) the biggest focus will be on the caching layer, and the ability to pick your own error handling strategy.

I hope the few users that we have will enjoy this

First, you need to add the configuration section for Common.Logging to the <configSections> element:

As you can see, i also included the definition of my preferred logging library (log4net) in this as well.  In this particular case, your service host needs to reference the following assemblies: Common.Logging.dll, Common.Logging.Log4Net.dll and log4net.dll.

The configuration of the Common.Logging library looks like this:

You need to specify which factoryAdapter that Common.Logging will use, in our case the one for log4net.  If you then configure the INLINE value for the configType key, Common.Logging will just initialize log4net in a way that it will simply use the XML configuration that is also present in your config file.  Again, i’ll point you to the Common.Logging documentation for configuring it for your specific library if you’re using something else. 

In my case, my log4net configuration looks like this:

The ‘Agatha’ logger simply logs everything coming from types whose namespace starts with Agatha and that logs at the error level (basically just exceptions caught by the Request Processor) and sends that the LogFileAppender (which simply logs in a log.txt) file.  The ‘AgathaPerformance’ logger specifically logs performance warnings coming from Agatha’s PerformanceLoggingRequestProcessor and also sends it to the LogFileAppender.

And that’s all there is to it.

First of all, there’s the following attribute that you can put on your Request types:

I really want to support both programmatic configuration as well as XML configuration (which would always override any existing programmatic configuration for a particular request) but for now, this attribute is the only way.  Also, everything in this caching layer assumes that your requests which enable response caching must override the Equals and GetHashCode() methods correctly (hint: use Resharper for that).

When we configure Agatha, we need to transform the caching metadata into objects of the following class:

And we also need something that contains all of the caching configuration data:

These classes already give us all we need to know (for now, at least) to set up our cache.  As mentioned previously, i wanted to use a region-based approach like NHibernate’s 2nd Level Cache.  Each region is basically a logical cache (and depending on the caching provider you’ll use, perhaps even a separate physical one) which is separated from the other ones.  It gives us the ability to specifically clear a logical cache.

So, we need something which can create a cache for a region:

And the cache itself would need to expose the following methods:

So now we can write something that manages the whole caching thing.  I couldn’t come up with a good name, so i just named the class CacheManager (i know it sucks, so suggest a better name if you know one):

The RequestProcessor’s ugly request-processing-loop (i know i need to clean that up) could then look like this:

And that’s it, so far.   Obviously, we need ICache and ICacheProvider implementations for the various caching libraries that are already available.  I already wrote an InMemoryCache and InMemoryCacheProvider to facilitate early experimentation/testing of the caching layer:

That’s it so far… i probably forgot about a lot of stuff that i really should take into account, but at least it’s something that we can start with.  Or to throw away and start over

The idea is basically to implement a caching layer which works very similar to NHibernate’s Second Level Cache.  You would need to be able to define which request/response combination is eligible for caching.  When a request/response combination is eligible for caching, Agatha should check to see if a cached response is already available for a particular incoming request.  That would mean that the request type would need to override the Equals method to compare the values.   If a previous request has already been processed which is equal to the current request, the corresponding cached response could be sent back immediately without having to handle it again.  Obviously, this check would only happen for requests which have been made eligible for caching.

We’d also need to provide a way to invalidate the cache.  Both time-based expiration and explicit removal from the cache should be possible.  For time-based expiration we could just provide some sort of time-out setting in the same place where you enable the caching for the request.  I’d probably do that through a .NET attribute which you can put on your Request type, and the time-out would simply be a property of the attribute.  For explicit removal, i’d probably go with a ‘region’-approach, similar to the regions in NHibernate’s Second Level Cache.  For instance, when declaring a request to be eligible for caching, one of the properties of the caching attribute could be a region name, and then we’d need to give you the ability to clear a certain region of the cache in your request handlers when it’s necessary to do so.

That’s pretty much all i can think of for now.  It’s not much yet, but i do think it could really be a tremendous improvement to Agatha.  The performance benefits for requests that deal with mostly static data, or data that doesn’t change frequently could be huge.  And the required coding effort for developers using Agatha would be minimal… simply put the correct attribute on your request type and explicit clearing of the right cache region when necessary would be all there is to it.

Thoughts?