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

1. Use the EnableResponseCaching attribute

If you want certain Request-derived types to be eligible for caching, you need to put the EnableResponseCaching 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?

Favorite quote from the post:

When I read about this it looked good. After one day of using it, I’m impressed, … really impressed.
It doesn’t use a lot of fancy patterns, just some tried and tested basic OO stuff, and it forces you to abide by these rules.

Let’s see how easily you can use your Request/Response Service Layer in-process with Agatha.  Do you remember the full-blown Hello World, Agatha Style example?  Let’s try to use that service layer and use it in-process without WCF.  First of all, i added a new project to my sample solution.  It references both the Sample.Common and the Sample.ServiceLayer assemblies.  Sample.Common contains my Request/Response types, and Sample.ServiceLayer contains the Request Handlers that the service layer consists of.  To configure both the client-side components (mainly the request dispatchers) as well as the server-side components (mainly the request processor and your request handlers), we just need to do this:

And that’s it.  No WCF configuration necessary.  No required XML at all.  The ServiceLayerAndClientConfiguration class will take care of everything and you can use your Request/Response Service Layer both synchronously and asynchronously in your code.   The service layer will behave exactly the same as it would when running on another machine or in a different process through WCF.  And you’ll still get to benefit from all of the advantages that Agatha can offer you.

Note: I made some changes to the codebase after the 1.0 beta 2 release to make this so easy (and also to get the async stuff working properly when running in-process) so you will need to use the current trunk version (as of revision 38) or wait for the next release.

The biggest benefit here is that client can simply send a One-Way request to the service layer, and instead of waiting for the service layer to process it, the call to the service layer will return immediately.  You could achieve similar behavior by using the asynchronous service proxy and supplying an empty delegate to be called after the response was received.  The downside of that is obviously that the communication channel between the client and the server would remain in use throughout the handling of the request, only to return a response later on that will be ignored anyway.  Sending a One-Way request avoids this kind of waste.

Let’s see how we can use One-Way requests with Agatha.

First of all, you will need to create a Request class which inherits from Agatha’s OneWayRequest class:

Normally you’d also create a corresponding Response type for your Request type, but for Requests that inherit from OneWayRequest that’s useless.  You’ll also need to create a Request Handler which inherits from Agatha’s OneWayRequestHandler class:

This is very similar to a regular RequestHandler, except that there’s no way for you to return a response.  Simply inherit from this class, implement the Handle(TRequest) method to perform whatever it is that you need to do and that’s it as far as the service layer is concerned.  If you want to, you can (as always) override the BeforeHandle and AfterHandle methods to add some extra stuff.  If you don’t want to inherit from this OneWayRequestHandler class, you can just as well create a class which implements Agatha’s IOneWayRequestHandler<TRequest> interface.  Your One Way Request Handlers will be picked up and registered by Agatha automatically, just as it does with regular Request Handlers.

As for sending One Way Requests to your service layer, you can do that with both the synchronous IRequestDispatcher and the IAsyncRequestDispatcher.  The IRequestDispatcher interface now looks like this:

Sending OneWayRequests can be done through the Send method, which will immediately send the given OneWayRequests to the service layer and the call will return as soon as the requests have been transmitted.  This means that this call will block for a short time until the requests have actually been sent.  It will return before the requests are actually processed by the service layer however.

The IAsyncRequestDispatcher now looks like this:

You can add your OneWayRequest through the correct Add method, and then have them processed by the server by calling the ProcessOneWayRequests method.  This call will not block and will return immediately. That means that it won’t wait until the requests have actually been sent to the server like it does with the IRequestDispatcher.

Here’s the changelog:

• Logging in the servicelayer now happens through the Common.Logging instead of using log4net directly… which means you can use whatever logging library you prefer
• (Breaking Change): If you want to pass your container instance to an Agatha container wrapper, you have to pass it to the constructor of the wrapper, and then pass that IContainer instance to your ServiceLayerConfiguration or ClientConfiguration instance before initializing
• Added Agatha.Unity and Agatha.Unity.Silverlight
• Added simple example of Agatha in use, with a small service layer, an IIS host for the service layer, a .NET client which performs a synchronous and an asynchronous client, and a Silverlight client which also performs an asynchronous call

The 2 most important changes are obviously that you can now integrate your own IOC container more easily and cleanly, and that you can use whatever logging library that you prefer. If you download the source of beta 2, you’ll also get the example solution which shows you how easily you can start using Agatha in your projects.

You can download the bits here.

I originally planned to use the Common Service Locator project for this, because the project description certainly seemed to fit my need:

The Common Service Locator library contains a shared interface for service location which application and framework developers can reference. The library provides an abstraction over IoC containers and service locators. Using the library allows an application to indirectly access the capabilities without relying on hard references. The hope is that using this library, third-party applications and frameworks can begin to leverage IoC/Service Location without tying themselves down to a specific implementation.

Unfortunately, the shared interface defined in this project only contains method for resolving components.  I really wanted to avoid having an Agatha-user be responsible for the correct registration of each component in their container, so the Common Service Locator project doesn’t really offer me any benefits.  Instead, i defined my own IContainer interface in Agatha which looks like this:

This interface enables me to perform automatic registration of all of the required components, and whenever Agatha needs to resolve components it will also do so through an instance which implements this interface.  We currently have two specific implementations of this interface: one for Castle Windsor, the other for Unity.  I’m going to cover how these implementations work later on in this post (as it will be useful to anyone who wants to use another IOC container together with Agatha) but first i want to show how Agatha will either obtain a reference to your container, or instantiate its own container if you don’t give it a container instance.

Agatha has two configuration classes: ServiceLayerConfiguration and ClientConfiguration.  ServiceLayerConfiguration defines the following constructors:

And ClientConfiguration defines the following ones:

As you can see, you can pass either an instance of an object that implements Agatha’s IContainer interface, or you can just pass in the type of the IContainer implementation.  If you pass in an instance, Agatha will simply reuse that instance for both the registration and the resolving of components.  If you pass a type instead of an instance, Agatha will create its own instance and use that for the registration and resolving of components.

Now, how do you integrate your own container? Quite simple, just create a type which implements the IContainer interface and pass an instance of that type to Agatha’s configuration objects.  As an example, i’ll show how i did it for Castle Windsor.  I created a new assembly called Agatha.Castle which contains the following Container class:

The Agatha.Castle.Container class defines two constructors.  One is the default constructor, which will create a new instance of the Windsor container, and the other requires you to pass an instance to a Windsor container.  The rest of the type simply implements Agatha’s IContainer interface methods and delegates to the real container instance.  If you pass an instance of the Agatha.Castle.Container class to Agatha’s ServiceLayerConfiguration class, Agatha will use this type to register and resolve all components.  Which means it either reuses your container instance, or creates its own if you don’t pass one (which i’d only recommend if you’re not using an IOC container in your code). This makes it pretty easy to integrate whatever IOC container you want to use. 

Agatha currently has ‘out-of-the-box’ support for Castle Windsor and Microsoft’s Unity.  If you want to use your own container, you now know how easily you can integrate it with Agatha.  And i’d be very happy to accept patches which add more Agatha.YourPreferredContainer assemblies

First of all, you’ll need an assembly that contains the types you want to share between your service layer and your clients. More specifically, this assembly needs to contain the Request/Response types and any other types that are contained in your Requests and Responses. This assembly needs to reference Agatha.Common. In my example, this example only contains one file:

Once we have that, we need to implement our service layer. You basically need an assembly that references both Agatha.Common and Agatha.ServiceLayer. This assembly also needs to reference your shared assembly. Then you can start implementing your request handlers. Since my service layer only has one ‘operation’, i only have the following Request Handler:

I also always include a ComponentRegistration class with a static method to perform all of the initialization. The only thing that needs to be done to initialize Agatha in your service layer is this:

The ServiceLayerConfiguration’s constructor requires 3 parameters. The first is the assembly that contains the Request Handlers, the second the one that contains your Request and Response types. The third parameter is either a reference to a Type which implement’s Agatha’s IContainer interface, or an instance of IContainer if you want Agatha to reuse an existing IOC container instance (like, the one the rest of your application is using). If you pass in a reference to a type which implements IContainer instead of an actual instance, Agatha will create a new container and use that instead. All of the Request Handlers and Request and Response types found in the passed in assemblies will all be registered within the container automatically so you don’t have to worry about that at all. I’m going to write another detailed post soon to show how you can integrate your favorite IOC container with Agatha, so i’m not going to get into the specifics of this right now. The only thing you need to remember from this part is how little work it takes to initialize everything. Oh, you’ll also need to reference the assembly which contains the relevant IOC container wrapper for what you want. In my case, that would be Agatha.Castle but i also have an Agatha.Unity assembly for those who want to use Unity. Agatha.StructureMap will be added soon.

Alright, you still need to host this service layer somewhere. In my example, i chose to host it in an ASP.NET Web Application through IIS. My Web Application project obviously has a reference to my Sample.ServiceLayer assembly. In the Global.asax.cs file i have the following code:

I also have a Service.svc file which contains the following:

My web.config has the following WCF configuration:

And that is it. The service layer is now functional and being hosted through IIS. You can obviously use whatever WCF hosting option you prefer, though the example only uses IIS as a host. Feel free to contribute other hosts

Then we have a .NET client which is able to call the service layer both synchronously and asynchronously. In my sample, it’s just a console app but it could just as well be another ASP.NET Web Application, a Windows Server, a WPF application, a Winforms application (if you’re down with the whole retro thing, that is), or any other .NET process you can think of.

In the case of my sample console app, i need to reference Agatha.Common and Agatha.Castle. In my app.config file, i need to add the following WCF configuration block:

Before i can call the service, my console app obviously needs to initialize Agatha:

That should be self-explanatory.

Then i can start making service calls:

And of course, asynchronous usage is also possible:

In case you’re wondering about the usage of IoC.Container in this code: Agatha provides a static IoC class which has an IContainer getter property. If you configured Agatha to use your container instance, then you can simply resolve the IRequestDispatcher or the IAsyncRequestDispatcher through your usual methods, or preferably, have them injected in your components. And if you’re not into the whole IOC thing, you can just use the RequestDispatcherFactory or the AsyncRequestDispatcherFactory directly.

And that is it. Yeah, probably the most over-engineered Hello World app ever, but still, i think it shows nicely how easy it is to use Agatha in your projects.

Oh wait, i almost forgot about the Silverlight sample… In your Silverlight application, reference Agatha.Common.Silverlight, and add the following ServiceReferences.ClientConfig file:

provide a way to initialize Agatha in your Silverlight app like this:

Make sure the ComponentRegistration.Register method is called when the silverlight client starts, and then you can do something like this:

Now you tell me, is that easy or what?