A model SOA application in .NET Part 6: the client proxy

Introduction

In the previous post we got as far as creating a service layer. Now it’s time to build a client proxy on that, i.e. a layer that the external clients of the service can send their requests to. We’ll use the the Web API technology to build this layer. If you’ve read through the other software architecture series on this blog you’ll see that Web API is very dear to me as it’s very simple to set up and use.

The client proxy

In this section I’ll refer a lot to this post in the series on the DDD skeleton project. Make sure you get familiar with it as it contains a lot of information that’s relevant to this post. In that post I show you how to add a web API project and transform it so that it only contains the web service relevant parts. We don’t want to deal with views, JS files, images etc. in a web service project. I also go through the basics of how to install and use the IoC called StructureMap in an MVC-based project. It will be responsible for resolving dependencies such as the ones in this constructor:

public ProductService(IMessageRepositoryFactory messageRepositoryFactory, IProductRepositoryFactory              productRepositoryFactory)

Add a new MVC4 web application called SoaIntroNet.WebProxy to the solution. Make sure to select the Web API template in the MVC4 Project Template window. Add a reference to all other layers – this is necessary for the StructureMap IoC container as we’ll see in a bit.

Next get rid of the standard MVC4 web application components. Again, consult the above link to see how it can be done. Install StructureMap from NuGet. You should have the following simplified structure of the web client project:

Add the following section to the Register method of WebApiConfig.cs in the App_Start folder to make sure that we respond with JSON:

var json = config.Formatters.JsonFormatter;
json.SerializerSettings.PreserveReferencesHandling = Newtonsoft.Json.PreserveReferencesHandling.Objects;			
config.Formatters.Remove(config.Formatters.XmlFormatter);

In the same method you’ll see that the API calls are routed to api/controller/id by default. Remove the ‘api’ bit as follows:

config.Routes.MapHttpRoute(
	name: "DefaultApi",
	routeTemplate: "{controller}/{id}",
	defaults: new { id = RouteParameter.Optional }
	);	

Add a folder called Helpers to the web layer. Add the following two classes with extension methods:

public static class ExceptionDictionary
{
	public static HttpStatusCode ConvertToHttpStatusCode(this Exception exception)
	{
		Dictionary<Type, HttpStatusCode> dict = GetExceptionDictionary();
		if (dict.ContainsKey(exception.GetType()))
		{
			return dict[exception.GetType()];
		}
		return dict[typeof(Exception)];
	}

	private static Dictionary<Type, HttpStatusCode> GetExceptionDictionary()
	{
		Dictionary<Type, HttpStatusCode> dict = new Dictionary<Type, HttpStatusCode>();
		dict[typeof(ResourceNotFoundException)] = HttpStatusCode.NotFound;
                dict[typeof(LimitedAvailabilityException)] = HttpStatusCode.InternalServerError;
		dict[typeof(Exception)] = HttpStatusCode.InternalServerError;
		return dict;
	}
}	

public static class HttpResponseBuilder
{	
	public static HttpResponseMessage BuildResponse(this HttpRequestMessage requestMessage, ServiceResponseBase baseResponse)
	{
		HttpStatusCode statusCode = HttpStatusCode.OK;
		if (baseResponse.Exception != null)
		{
			statusCode = baseResponse.Exception.ConvertToHttpStatusCode();
			HttpResponseMessage message = new HttpResponseMessage(statusCode);
			message.Content = new StringContent(baseResponse.Exception.Message);
			throw new HttpResponseException(message);
		}
		return requestMessage.CreateResponse<ServiceResponseBase>(statusCode, baseResponse);
	}
}

Set the namespace of both classes to SoaIntroNet.WebProxy so that they are available from everywhere in the Web project without having to set using statements.

Add a new Web API controller in the Controllers folder. Name it ReservationController and make sure to select the Empty Api controller template in the Add Controller window. You’ll see that the controller derives from ApiController. The controller will need the services of the IProductService interface so add the following private field and controller:

private readonly IProductService _productService;

public ReservationController(IProductService productService)
{
	if (productService == null) throw new ArgumentNullException("IProductService");
	_productService = productService;
}

If you are familiar with the SOLID principles then you’ll understand why it’s important to inject an abstract dependency through the constructor this way. If not, then start here.

The client will need to send a POST request with the parameters needed to build a ReserveProductRequest object. This is as simple as inserting a Post() method in the controller which accepts a ReserveProductRequest object. The implementation is equally simple: we delegate the actual work to the product service:

ServiceResponseBase response = _productService.ReserveProduct(reserveProductRequest);
return Request.BuildResponse(response);

Insert another controller in the Controllers folder called PurchaseController. It too will depend on the product service so insert the following private field and constructor:

private readonly IProductService _productService;

public PurchaseController(IProductService productService)
{
	if (productService == null) throw new ArgumentNullException("IProductService");
	_productService = productService;
}

The product purchase will also be a POST operation:

public HttpResponseMessage Post(PurchaseProductRequest purchaseProductRequest)
{
	purchaseProductRequest.CorrelationId = purchaseProductRequest.ReservationId;
	ServiceResponseBase response = _productService.PurchaseProduct(purchaseProductRequest);
	return Request.BuildResponse(response);
}

The only major difference between the the two Post method structures is that here we set the correlation ID ourselves. It is set to the reservation ID which is unique and it makes sense to use as the message correlation ID to check if we have fulfilled the request. Otherwise the client could provide just any correlation ID so we cannot trust that input.

Finally we need to instruct StructureMap to fetch the correct dependencies. Locate IoC.cs in the DependencyResolution folder. Make sure it looks as follows:

public static IContainer Initialize()
{
	ObjectFactory.Initialize(x =>
				{
					x.Scan(scan =>
							{
								scan.TheCallingAssembly();
								scan.AssemblyContainingType<IProductService>();
								scan.AssemblyContainingType<IMessageRepository>();
								scan.WithDefaultConventions();
							});
					x.For<IMessageRepositoryFactory>().Use<LazySingletonMessageRepositoryFactory>();
					x.For<IProductRepositoryFactory>().Use<LazySingletonProductRepositoryFactory>();
				});
	ObjectFactory.AssertConfigurationIsValid();
	return ObjectFactory.Container;
}

We tell IoC where to look for concrete implementations and which concrete types to take in those cases where the standard ‘I’ naming convention doesn’t apply: (I)Service => Service. For more details consult the post I hinted at in the beginning of this post.

This actually completes the client proxy layer. In the next post we’ll test the proxy by building a console application client.

View the list of posts on Architecture and Patterns here.

A model SOA application in .NET Part 5: the service layer continued

Introduction

In the previous post we started implementing the IProductService interface. We got as far as declaring a couple of private fields and a constructor. Here we’ll implement the ReserveProduct and PurchaseProduct methods.

The concrete service continued

Open the project we’ve been working on in this series and locate ProductService.cs. The implemented ReserveProduct method looks as follows:

public ProductReservationResponse ReserveProduct(ReserveProductRequest productReservationRequest)
{
	ProductReservationResponse reserveProductResponse = new ProductReservationResponse();
	try
	{
		Product product = _productRepository.FindBy(Guid.Parse(productReservationRequest.ProductId));
		if (product != null)
		{
			ProductReservation productReservation = null;
			if (product.CanReserveProduct(productReservationRequest.ProductQuantity))
			{
				productReservation = product.Reserve(productReservationRequest.ProductQuantity);
				_productRepository.Save(product);
				reserveProductResponse.ProductId = productReservation.Product.ID.ToString();
				reserveProductResponse.Expiration = productReservation.Expiry;
				reserveProductResponse.ProductName = productReservation.Product.Name;
				reserveProductResponse.ProductQuantity = productReservation.Quantity;
				reserveProductResponse.ReservationId = productReservation.Id.ToString();
			}
			else
			{
				int availableAllocation = product.Available();
				reserveProductResponse.Exception = new LimitedAvailabilityException(string.Concat("There are only ", availableAllocation, " pieces of this product left."));
			}
		}
		else
		{
			throw new ResourceNotFoundException(string.Concat("No product with id ", productReservationRequest.ProductId, ", was found."));
		}
	}
	catch (Exception ex)
	{
		reserveProductResponse.Exception = ex;
	}
	return reserveProductResponse;
}

First we let the product repository locate the requested product for us. If it doesn’t exist then we throw an exception with an appropriate message. We check using the CanReserveProduct method whether there are enough products left. If not then we let the client know in an exception message. Otherwise we reserve the product, save the current reservation status and populate the reservation response using the product reservation returned by the Save method. We wrap the entire code in a try-catch block to make sure that we catch any exception thrown during the process.

Here’s the implemented PurchaseProduct method:

public PurchaseProductResponse PurchaseProduct(PurchaseProductRequest productPurchaseRequest)
{
	PurchaseProductResponse purchaseProductResponse = new PurchaseProductResponse();
	try
	{
		if (_messageRepository.IsUniqueRequest(productPurchaseRequest.CorrelationId))
		{					
			Product product = _productRepository.FindBy(Guid.Parse(productPurchaseRequest.ProductId));
			if (product != null)
			{
				ProductPurchase productPurchase = null;
				if (product.ReservationIdValid(Guid.Parse(productPurchaseRequest.ReservationId)))
				{
					productPurchase = product.ConfirmPurchaseWith(Guid.Parse(productPurchaseRequest.ReservationId));
					_productRepository.Save(product);
					purchaseProductResponse.ProductId = productPurchase.Product.ID.ToString();
					purchaseProductResponse.PurchaseId = productPurchase.Id.ToString();
					purchaseProductResponse.ProductQuantity = productPurchase.ProductQuantity;
					purchaseProductResponse.ProductName = productPurchase.Product.Name;
				}
				else
				{
					throw new ResourceNotFoundException(string.Concat("Invalid or expired reservation id: ", productPurchaseRequest.ReservationId));
				}
				_messageRepository.SaveResponse<PurchaseProductResponse>(productPurchaseRequest.CorrelationId, purchaseProductResponse);
			}
			else
			{
				throw new ResourceNotFoundException(string.Concat("No product with id ", productPurchaseRequest.ProductId, ", was found."));
			}
		}
		else
		{
			purchaseProductResponse = _messageRepository.RetrieveResponseFor<PurchaseProductResponse>(productPurchaseRequest.CorrelationId);
		}
	}
	catch (Exception ex)
	{
		purchaseProductResponse.Exception = ex;
	}
	return purchaseProductResponse;
}

If you recall from the first part of this series we talked about the Idempotent pattern. The IsUniqueRequest is an application of the pattern. We check in the message repository if a message with that correlation ID has been processed before. If yes, then we return the response stored in the repository to avoid making the same purchase again. This is not the only possible solution of the pattern, but only one of the viable ones. Probably the domain layer could have a similar logic as well, but I think this is more robust.

If this is a new request then we locate the product just like in the ReserveProduct method and throw an exception if the product is not found. If the product exists then we need to check if the reservation can be made using the reservation ID of the incoming message. If not, then the reservation either doesn’t exist or has expired and a corresponding exception is thrown. Otherwise we confirm the purchase, save the product and dress up the product purchase response using the product purchase object returned by the ConfirmPurchaseWith method. Just like above, we wrap the code within a try-catch block.

This completes the service layer of the SOA project. We’ll look at the web client in the next post. The web client will be a web service client based on the Web API technology so that we don’t need to waste time and energy on presentation stuff such as HTML and CSS.

View the list of posts on Architecture and Patterns here.

A model SOA application in .NET Part 4: the service layer part 1

Introduction

Now that we’re done with the domain and repository layers it’s time to build the service layer. If you are not familiar with the purposes of the service layer then make sure to read this post. I’ll employ the same Request-Response pattern here.

The service layer

Open the application we’ve been working on and add a new C# class library called SoaIntroNet.Service. Remove Class1.cs and make a reference to both the Domain and the Repository layers. Insert a new folder called Responses and in it a base class for all service responses:

public abstract class ServiceResponseBase
{
	public ServiceResponseBase()
	{
		this.Exception = null;
	}

        public Exception Exception { get; set; }
}

The clients will be able to purchase and reserve products. We put the result of the purchasing and reservation processes into the following two Response objects:

public class PurchaseProductResponse : ServiceResponseBase
{
	public string PurchaseId { get; set; }
	public string ProductName { get; set; }
	public string ProductId { get; set; }
	public int ProductQuantity { get; set; }
}

public class ProductReservationResponse : ServiceResponseBase
{
	public string ReservationId { get; set; }
	public DateTime Expiration { get; set; }
	public string ProductId { get; set; }
	public string ProductName { get; set; }
	public int ProductQuantity { get; set; }
}

Nothing really fancy up to this point I hope. In order to make a purchase or reservation the corresponding Request objects must be provided by the client. Add a new folder called Requests and in it the following two requests:

public class PurchaseProductRequest
{
	public string CorrelationId { get; set; }
	public string ReservationId { get; set; }
	public string ProductId { get; set; }
}

public class ReserveProductRequest
{
	public string ProductId { get; set; }
	public int ProductQuantity { get; set; }
}

The only somewhat unexpected property is the correlation id. Recall its purpose from the opening post in this series: ensure that a state-changing operation is not carried out more than once, e.g. purchasing the same tickets twice.

Add a folder called Exceptions and insert the following two custom exceptions:

public class ResourceNotFoundException : Exception
{
	public ResourceNotFoundException(string message)
		: base(message)
	{ }

	public ResourceNotFoundException()
		: base("The requested resource was not found.")
	{ }
}

public class LimitedAvailabilityException : Exception
{
	public LimitedAvailabilityException(string message)
		: base(message)
	{}

	public LimitedAvailabilityException()
		: base("There are not enough products left to fulfil your request.")
	{}
}

As the names imply we’ll throw these exception if some requested resource could not be located or that the required amount in the request could not be fulfilled.

Add the following service interface to the Service layer:

public interface IProductService
{
	ProductReservationResponse ReserveProduct(ReserveProductRequest productReservationRequest);
	PurchaseProductResponse PurchaseProduct(PurchaseProductRequest productPurchaseRequest);
}

This represents our service contract. We state that our service will be able to handle product purchases and reservations and they need the necessary Request objects in order to fulfil their functions. The concrete implementation – which we’ll look at in a bit – is an unimportant implementation detail from the client’s point of view.

However, before we do that we’ll need to revisit the repository layer and make room for saving and retrieving the messaging history based on the correlation ID. These messages are not part of our domain so we won’t bother with setting up a separate Message object.

Open SoaIntroNet.Repository and add a new folder called MessagingHistory. Insert the following interface which describes the operations a message repository must be able to handle:

public interface IMessageRepository
{
	bool IsUniqueRequest(string correlationId);
	void SaveResponse<T>(string correlationId, T response);
	T RetrieveResponseFor<T>(string correlationId);
}

The purpose of IsUniqueRequest is to show whether the message with that correlation ID has been saved before. You can probably guess the purpose of the other two methods.

Here comes an implementation of the repository with the same lazy loading static initialiser we saw in the ProductRepository example:

public class MessageRepository : IMessageRepository
{
	private Dictionary<string, object> _responseHistory;

	public MessageRepository()
	{
		_responseHistory = new Dictionary<string, object>();
	}

	public bool IsUniqueRequest(string correlationId)
	{
		return !_responseHistory.ContainsKey(correlationId);
	}

	public void SaveResponse<T>(string correlationId, T response)
	{
		_responseHistory[correlationId] = response;
	}

	public T RetrieveResponseFor<T>(string correlationId)
	{
		if (_responseHistory.ContainsKey(correlationId))
		{
			return (T)_responseHistory[correlationId];
		};
		return default(T);
	}

	public static MessageRepository Instance
	{
		get
		{
			return Nested.instance;
		}
	}

	private class Nested
	{
		static Nested()
		{
		}
		internal static readonly MessageRepository instance = new MessageRepository();
	}
}

We store the responses in a Dictionary. In a real case scenario we can store these in any type of storage mechanism: a database, a web service, cache, you name it. An in-memory solution is the easiest in this case.

A side note: it’s not necessary to go with the lazy singleton pattern for all repositories. However, in this example the pattern will make sure that a single object is created every time one is required and the in-memory objects won’t be re-instantiated. We don’t want to lose the Dictionary object every time somebody sends a new purchase request. In the series on DDD, especially in this post and the one after that, I show how it suffices to lazily instantiate a Unit of Work instead of all implemented repositories.

Just like for the ProductRepository we’ll need the corresponding factory:

public interface IMessageRepositoryFactory
{
	MessageRepository Create();
}

public class LazySingletonMessageRepositoryFactory : IMessageRepositoryFactory
{
	public MessageRepository Create()
	{
		return MessageRepository.Instance;
	}
}

We can now turn our attention to the Service layer again. Add a class called ProductService with the following stub:

public class ProductService : IProductService
{
	public ProductReservationResponse ReserveProduct(ReserveProductRequest productReservationRequest)
	{
		throw new NotImplementedException();
	}

	public PurchaseProductResponse PurchaseProduct(PurchaseProductRequest productPurchaseRequest)
	{
		throw new NotImplementedException();
	}
}

The ProductService will need some help from the Repository layer to complete these tasks. It will need a product repository and a message repository. These objects are created by our lazy singleton factories. We know from the discussion on SOLID and especially the Dependency inversion principle that an object – in this case the ProductService – should not create its own dependencies. Instead, the caller should inject the proper dependencies.

The most obvious technique is constructor injection. Add the following private fields and a constructor to ProductService:

private readonly IMessageRepositoryFactory _messageRepositoryFactory;
private readonly IProductRepositoryFactory _productRepositoryFactory;
private readonly IMessageRepository _messageRepository;
private readonly IProductRepository _productRepository;

public ProductService(IMessageRepositoryFactory messageRepositoryFactory, IProductRepositoryFactory productRepositoryFactory)
{
	if (messageRepositoryFactory == null) throw new ArgumentNullException("MessageRepositoryFactory");
	if (productRepositoryFactory == null) throw new ArgumentNullException("ProductRepositoryFactory");
	_messageRepositoryFactory = messageRepositoryFactory;
	_productRepositoryFactory = productRepositoryFactory;
	_messageRepository = _messageRepositoryFactory.Create();
	_productRepository = _productRepositoryFactory.Create();
}

We let the factories be injected through the constructor. This follows the good habit of programming against abstractions. We then ask the factories to create the repositories for us – note that they are abstractions as well.

In a real application you wouldn’t rely on the memory to store objects for you. A more “normal” constructor would look like this:

private readonly IMessageRepository _messageRepository;
private readonly IProductRepository _productRepository;

public ProductService(IMessageRepository messageRepository, IProductRepository productRepository)
{
	if (messageRepository == null) throw new ArgumentNullException("MessageRepository");
	if (productRepository == null) throw new ArgumentNullException("ProductRepository");
	_messageRepository = messageRepository;
	_productRepository = productRepository;
}

However, for the reasons outlined above we go with the factory solution in this demo. If we followed this simplified version then our in-memory data would be re-instantiated after every subsequent request making a demo meaningless.

We’ll see in the next post how the reserve ticket and purchase ticket methods are implemented.

View the list of posts on Architecture and Patterns here.

A model SOA application in .NET Part 3: the repository

In the previous post we built the thin domain layer of the model application. Now it’s time to build the repository.

The abstract repository

Open the SoaIntroNet application we started building previously. Add a new interface in the SoaIntroNet.Domain.ProductDomain folder:

public interface IProductRepository
{
	Product FindBy(Guid productId);
	void Save(Product product);
}

This is a very simplified repository interface but it suffices for our demo purposes. In case you’re wondering what the purpose of this interface is and what it is doing in the domain layer then make sure to at least skim through the series on Domain-Driven-Design here. Alternatively you can go through the solution structure of the series about the cryptography project starting here. This latter project follows a simplified repository pattern that we’ll employ here.

The concrete repository

The repository will be a simple in-memory repository so that we don’t need to spend our time on installing external storage mechanisms.

Let’s build the infrastructure around the concrete repository. Add a new C# library project called SoaIntroNet.Repository to the solution. Add a new folder called ProductRepository. Add the following stub to the class:

public class InMemoryProductRepository : IProductRepository
{
	public Product FindBy(Guid productId)
	{
		throw new NotImplementedException();
	}

	public void Save(Product product)
	{
		throw new NotImplementedException();
	}		
}

We’ll use the thread-safe singleton design pattern to build an instance of this object. Add the following code to the class:

public static InMemoryProductRepository Instance
{
	get
	{
		return Nested.instance;
	}
}

private class Nested
{
	static Nested()
	{
	}
	internal static readonly InMemoryProductRepository instance = new InMemoryProductRepository();
}

If you don’t understand what this means then make sure to check out the post on the singleton pattern. It ensures that we always return the same instance of the concrete repository.

Before we get rid of the NotImplementException bits we’ll take care of the rest of the initialisation elements. Add the following interface to the folder:

public interface IProductRepositoryFactory
{
	InMemoryProductRepository Create();
}

The following class implements the above interface:

public class LazySingletonProductRepositoryFactory : IProductRepositoryFactory
{
	public InMemoryProductRepository Create()
	{
		return InMemoryProductRepository.Instance;
	}
}

We don’t want to start with an empty “database” so add the following fields, properties, a constructor and an initialisation method to the class:

private int standardReservationTimeoutMinutes = 1;
public List<Product> DatabaseProducts { get; set; }
public List<ProductPurchase> DatabaseProductPurchases { get; set; }
public List<ProductReservation> DatabaseProductReservations { get; set; }

public InMemoryProductRepository()
{
	InitialiseDatabase();
}

private void InitialiseDatabase()
{
	DatabaseProducts = new List<Product>();
	Product firstProduct = new Product()
	{
		Allocation = 200,
		Description = "Product A",
		ID = Guid.Parse("13a35876-ccf1-468a-88b1-0acc04422243"),
		Name = "A"
	};
	Product secondProduct = new Product()
	{
		Allocation = 500,
		Description = "Product B",
		ID = Guid.Parse("f5efdfe0-7933-4efc-a290-03d20014703e"),
		Name = "B"
	};
        DatabaseProducts.Add(firstProduct);
	DatabaseProducts.Add(secondProduct);

	DatabaseProductPurchases = new List<ProductPurchase>();
	DatabaseProductPurchases.Add(new ProductPurchase(firstProduct, 10) { Id = Guid.Parse("0ede40e0-5a52-48b1-8578-de1891c5a7f0") });
	DatabaseProductPurchases.Add(new ProductPurchase(firstProduct, 20) { Id = Guid.Parse("5868144e-e04d-4c1f-81d7-fc671bfc52dd") });
	DatabaseProductPurchases.Add(new ProductPurchase(secondProduct, 12) { Id = Guid.Parse("8e6195ac-d448-4e28-9064-b3b1b792895e") });
	DatabaseProductPurchases.Add(new ProductPurchase(secondProduct, 32) { Id = Guid.Parse("f66844e5-594b-44b8-a0ef-2a2064ec2f43") });
	DatabaseProductPurchases.Add(new ProductPurchase(secondProduct, 1) { Id = Guid.Parse("0e73c8b3-f7fa-455d-ba7f-7d3f1bc2e469") });
	DatabaseProductPurchases.Add(new ProductPurchase(secondProduct, 4) { Id = Guid.Parse("e28a3cb5-1d3e-40a1-be7e-e0fa12b0c763") });

	DatabaseProductReservations = new List<ProductReservation>();
	DatabaseProductReservations.Add(new ProductReservation(firstProduct, standardReservationTimeoutMinutes, 10) { HasBeenConfirmed = true, Id = Guid.Parse("a2c2a6db-763c-4492-9974-62ab192201fe") });
	DatabaseProductReservations.Add(new ProductReservation(firstProduct, standardReservationTimeoutMinutes, 5) { HasBeenConfirmed = false, Id = Guid.Parse("37f2e5ac-bbe0-48b0-a3cd-9c0b47842fa1") });
	DatabaseProductReservations.Add(new ProductReservation(firstProduct, standardReservationTimeoutMinutes, 13) { HasBeenConfirmed = true, Id = Guid.Parse("b9393ea4-6257-4dea-a8cb-b78a0c040255") });
	DatabaseProductReservations.Add(new ProductReservation(firstProduct, standardReservationTimeoutMinutes, 3) { HasBeenConfirmed = false, Id = Guid.Parse("a70ef898-5da9-4ac1-953c-a6420d37b295") });
	DatabaseProductReservations.Add(new ProductReservation(secondProduct, standardReservationTimeoutMinutes, 17) { Id = Guid.Parse("85eaebfa-4be4-407b-87cc-9a9ea46d547b") });
	DatabaseProductReservations.Add(new ProductReservation(secondProduct, standardReservationTimeoutMinutes, 3) { Id = Guid.Parse("39d4278e-5643-4c43-841c-214c1c3892b0") });
	DatabaseProductReservations.Add(new ProductReservation(secondProduct, standardReservationTimeoutMinutes, 9) { Id = Guid.Parse("86fff675-e5e3-4e0e-bcce-36332c4de165") });

	firstProduct.PurchasedProducts = (from p in DatabaseProductPurchases where p.Product.ID == firstProduct.ID select p).ToList();
	firstProduct.ReservedProducts = (from p in DatabaseProductReservations where p.Product.ID == firstProduct.ID select p).ToList();

	secondProduct.PurchasedProducts = (from p in DatabaseProductPurchases where p.Product.ID == secondProduct.ID select p).ToList();
	secondProduct.ReservedProducts = (from p in DatabaseProductReservations where p.Product.ID == secondProduct.ID select p).ToList();
}

We have 2 products with a couple of product purchases and reservations in our data store.

The lazy singleton implementation will make sure that the initialisation code only runs once so we’ll have access to the initial set of data every time we need a concrete repository.

The implementation of FindBy is very simple:

public Product FindBy(Guid productId)
{
	return (from p in DatabaseProducts where p.ID == productId select p).FirstOrDefault();
}

The implementation of Save is not much harder either:

public void Save(Product product)
{
	ClearPurchasedAndReservedProducts(product);
	InsertPurchasedProducts(product);
	InsertReservedProducts(product);
}

…which calls the following three private methods:

private void ClearPurchasedAndReservedProducts(Product product)
{
	DatabaseProductPurchases.RemoveAll(p => p.Id == product.ID);
	DatabaseProductReservations.RemoveAll(p => p.Id == product.ID);
}

private void InsertReservedProducts(Product product)
{
	DatabaseProductReservations.AddRange(product.ReservedProducts);
}

private void InsertPurchasedProducts(Product product)
{
	DatabaseProductPurchases.AddRange(product.PurchasedProducts);
}

In the Save method we want to concentrate on updating the product reservations and purchases and ignore the changes in the Product domain itself. Updating product reservations and purchases line by line is a cumbersome task. It’s easier to remove all existing purchases and reservations first and insert the old ones along with the new ones. The existing product purchases and reservations are always populated correctly in the InitialiseDatabase() method. Therefore a call to FindBy will product a product with the existing purchases and reservations.

So we now have the Domain and the Repository layer ready – we’ll build the service layer in the next solution.

View the list of posts on Architecture and Patterns here.

A model SOA application in .NET Part 2: the domain

Introduction

The SOA model application will simulate a Product purchase system. The Product must be reserved first and the purchase must be then confirmed. So this is a scenario familiar from e-commerce sites, although in reality the flow may be more complicated. The point here is that the purchase is not a one-step process and the web service must be able to track the registration somehow. So the Product can be anything you can think of: tickets, books, whatever, that’s a detail we don’t care about.

We’ll continue from the previous post which set the theoretical basis for the model we’re about to build.

If you have followed along the series on DDD then you’ll notice that the Domain structure I’m going to present is a lot simpler: there’s no aggregate root and entity base etc., and that’s for a good reason. Those belong to the DDD-specific discussion whereas here we want to concentrate on SOA. Therefore I decided to remove those elements that might distract us from the main path and keep the Domain layer simple. Otherwise if you are not familiar with DDD but still want to learn about SOA you may find the code hard to follow.

Demo

Open Visual Studio and insert a new blank solution called SoaIntroNet. Add a C# class library called SoaIntroNet.Domain to it and remove Class1.cs. Add a folder called ProductDomain and a class called Product in it. Here’s the Product domain code with some explanation to follow. The code will not compile at first as we need to implement some other objects as well in a bit.

public class Product
{
	public Product()
	{
		ReservedProducts = new List<ProductReservation>();
		PurchasedProducts = new List<ProductPurchase>();
	}

	public Guid ID { get; set; }
	public string Name { get; set; }
	public string Description { get; set; }
	public int Allocation { get; set; }
	public List<ProductReservation> ReservedProducts { get; set; }
	public List<ProductPurchase> PurchasedProducts { get; set; }

	public int Available()
	{
		int soldAndReserved = 0;
		PurchasedProducts.ForEach(p => soldAndReserved += p.ProductQuantity);
		ReservedProducts.FindAll(p => p.IsActive()).ForEach(p => soldAndReserved += p.Quantity);

		return Allocation - soldAndReserved;
	}

	public bool ReservationIdValid(Guid reservationId)
	{
		if (HasReservation(reservationId))
		{
			return GetReservationWith(reservationId).IsActive();
		}
		return false;
	}

	public ProductPurchase ConfirmPurchaseWith(Guid reservationId)
	{
		if (!ReservationIdValid(reservationId))
		{
			throw new Exception(string.Format("Cannot confirm the purchase with this Id: {0}", reservationId));
		}

		ProductReservation reservation = GetReservationWith(reservationId);
		ProductPurchase purchase = new ProductPurchase(this, reservation.Quantity);
		reservation.HasBeenConfirmed = true;
		PurchasedProducts.Add(purchase);
		return purchase;
	}

	public ProductReservation GetReservationWith(Guid reservationId)
	{
		if (!HasReservation(reservationId))
		{
			throw new Exception(string.Concat("No reservation found with id {0}", reservationId.ToString()));
		}
		return (from r in ReservedProducts where r.Id == reservationId select r).FirstOrDefault();
	}

	private bool HasReservation(Guid reservationId)
	{
		return ReservedProducts.Exists(p => p.Id == reservationId);
	}

	public bool CanReserveProduct(int quantity)
	{
		return Available() >= quantity;
	}

	public ProductReservation Reserve(int quantity)
	{
		if (!CanReserveProduct(quantity))
		{
			throw new Exception("Can not reserve this many tickets.");
		}

		ProductReservation reservation = new ProductReservation(this, 1, quantity);
		ReservedProducts.Add(reservation);
		return reservation;
	}
}

We maintain a list of purchased and reserved products in the corresponding List objects. The Allocation property means the initial number of products available for sale.

• In Available() we check what’s left based on Allocation and the reserved and purchased tickets.
• CanReserveProduct: we check if there are at least as many products available as the ‘quantity’ value
• Reserve: we reserve a product and add it to the reservation list. We set the expiry date of the reservation to 1 minute. In reality this value should be higher of course but in the demo we don’t want to wait 30 minutes to test for the reservation being too old
• HasReservation: check if the reservation exists in the reservation list using the reservation id
• GetReservationWith: we retrieve the reservation based on its GUID
• ReservationIdValid: check if a product can be purchased with the reservation id
• ConfirmPurchaseWith: confirm the reservation by adding the constructed product to the purchase list

Here comes the ProductReservation class:

public class ProductReservation
{
	public ProductReservation(Product product, int expiryInMinutes, int quantity)
	{
		if (product == null) throw new ArgumentNullException("Product cannot be null.");
		if (quantity < 1) throw new ArgumentException("The quantity should be at least 1.");
		Product = product;
		Id = Guid.NewGuid();
		Expiry = DateTime.Now.AddMinutes(expiryInMinutes);
                Quantity = quantity;
	}

	public Guid Id { get; set; }
	public Product Product { get; set; }
	public DateTime Expiry { get; set; }
	public int Quantity { get; set; }
	public bool HasBeenConfirmed { get; set; }

	public bool Expired()
	{
		return DateTime.Now > Expiry;
	}

	public bool IsActive()
	{
		return !HasBeenConfirmed && !Expired();
	}
}

Note the expiry date property which fits in well with our discussion in the previous post: the client needs to reserve the product first and then confirm the purchase within the expiry date.

The ProductPurchase class is equally straightforward:

public class ProductPurchase
{
	public ProductPurchase(Product product, int quantity)
	{
		Id = Guid.NewGuid();
		if (product == null) throw new ArgumentNullException("Product cannot be null.");
		if (quantity < 1) throw new ArgumentException("The quantity should be at least 1.");
		Product = product;
		ProductQuantity = quantity;
	}

	public Guid Id { get; set; }
	public Product Product { get; set; }
	public int ProductQuantity { get; set; }
}

That’s all the domain logic we have in the model application. In the next post we’ll implement the repository.

View the list of posts on Architecture and Patterns here.

A model SOA application in .NET Part 1: the fundamentals

Introduction

SOA – Service Oriented Architecture – is an important buzzword in distributed software architecture. This term has been misused a lot to mean just any kind of API that spits out responses to the incoming requests regardless of the rules and patterns common to SOA applications.

We looked at the role of the Service layer in this post and the one after that. In short a service represents the connecting tissue between the back-end layers – typically the domain logic, infrastructure and repository – and the ultimate consumer of the application: an MVC controller, a Console app, a Web Forms aspx page etc., so any caller that is interested in the operation your system can provide. To avoid the situation where your callers have to dig around in your backend code to find the operations relevant to them you can put up a service which encapsulates the possible operations to the clients. Such a service – an application service – is usually void of any business logic and performs co-ordination tasks.

The goals of this series are the following:

• Provide an understanding of SOA, the rules and patterns associated with it
• Provide a down-to-earth example SOA project in .NET
• Concentrate on the fundamentals of SOA without going into complex architectures such as CQRS

The target audience is developers getting started with SOA.

The sample application will follow a layered structure similar to this application although in a simplified form. I won’t concentrate on the Domain as much as in that project. We’ll put most of our focus on service-related issues instead. However, I encourage you to at least skim through that series on Domain Driven Design to get an understanding of layered projects in .NET.

Rules and patterns

SOA is quite generic and can be applied in several different ways depending on the starting point of the – often legacy – application you’re trying to transform. There are however a couple of rules and practices to keep in mind when building a SOA app.

The 4 tenets of SOA

• Boundaries are explicit: a service interface needs to be clean and simple. Note the term ‘interface’: it is what the clients see from the outside that must be clear and concise. Your code in the background can be as complex as you wish, but your clients should not be aware of it.
• Services are autonomous: service methods should be independent. The caller should not have to call certain methods in some order to achieve a goal. You should strive to let the client get the relevant response in one atomic operation. Service methods should be stateless: the client calls a service and “that’s the end of the story”, meaning there shouldn’t be any part of the system left in a partially done state.
• Interoperability: a service should only expose an interface, not an entire implementation. Communication should happen with standard message types such as JSON or XML for complex objects or simple inputs like integers and strings for primitive inputs so that clients of very disparate types can reach your services.
• Policy exposure: a service interface should be well documented for clients so that they know what operations are supported, how they can be called and what type of response they can expect.

Facade design pattern

We discussed the Facade design pattern in this post. In short it helps to hide a complex backend system in form of a simplified, clear and concise interface. The main goal of this pattern is that your clients shouldn’t be concerned with a complex API.

The RequestResponse messaging pattern

We discussed the RequestReponse pattern in this post. In short the main purpose of this pattern is to simplify the communication by encapsulating all the necessary parameters to perform a job in a single object. Make sure to read the referenced post as we’ll see this pattern a lot in the model application.

The Reservation pattern

As stated above operations of a SOA service should be autonomous. It is not always guaranteed that this is possible though. At times it is necessary to break up a complex unit of operation into 2 or more steps and maintain the state between them. A typical example is e-commerce sites where you can order products. The complete check-out process might look like this:

1. Put items in a shopping cart
2. Provide payment information
3. Provide delivery information
4. Confirm the purchase

It would be difficult to put all these steps into a single interface method, such as ReserveAndBuyGoodsAndConfirmAddress(params). Instead, a reservation ID is provided when the items are reserved in the shopping cart. The reservation ID can be used in all subsequent messages to complete the purchase. Typically an expiration date is attached to the reservation ID so that the purchase must be completed within a specified time range otherwise your reservation is lost. This is very often applied when buying tickets to the concert of a popular band: you must complete the purchase within some minutes otherwise the tickets you’ve requested will be put up for sale again.

Here’s a flow diagram of the pattern:

The client, very likely a web interface sends a reservation request to the service. This request includes the product ID and the quantity. The reservation response includes a reservation ID and en expiry date. The reservation must be completed with a purchase until that date. The client then asks for payment and delivery details – not shown in the flow chart, this happens within the client. When all the details are known then the purchase order is sent to the service with the reservation ID. The service checks the validity of the reservation ID and rejects the call if necessary. If it’s validated then a confirmation ID is sent by the service.

The Idempotent pattern

An operation is idempotent in case it has no additional effects if it is called more than once with the same parameters. You cannot control how your public API is called by your clients so you should make sure it does not lead to any undesired effects if they repeat their calls over and over again.

A common solution is to provide a correlation ID to any potentially state-altering operations. The service checks in some repository whether the request has been processed. If yes then the previously stored response should be provided.

Here’s a flow chart showing the communication with a correlation ID:

The client sends a request to the API along with a unique correlation ID. The service checks in its cache whether it has already processed the request. If yes, then it sends the same answer as before other it asks the backend logic to perform some action and then put the response into the cache.

Duplex

Most often the communication with a web service is such that you send a HTTP, TCP etc. message to it and receive some type of acknowledgement. This kind of message exchange pattern (MEP) is well represented with the RequestResponse pattern mentioned above. You send off the payload in the query string or the HTTP message body and receive at least an “OK” or “Error” back. The service then “let’s you go”, i.e. it won’t just remember your previous request, you’ll need to send a reference to any previous communication, if it’s available.

The Duplex MEP on the other hand is a two-way message channel. It is used in the following situations:

• The caller needs to be notified of the result of a long running request when it’s complete – a classic “callback” situation. The caller sends a request and instead of waiting for the service to respond it provides a callback address where the service can notify the caller
• The caller wants ad-hoc messages from the service. Say that the service pushes periodic data on stock prices. The caller could provide a channel where the service can send the updates

We discussed the service contracts above. These are the interfaces of the service which the caller can call upon without worrying about the exact implementation details. In a Duplex scenario we have another contract, namely the Callback contract. The caller sends a one-way request – i.e. a request with no immediate response whatsoever – to the service and the service responds back after some time using the callback contract.

WCF has built-in attributes to support Duplex MEP. Here’s a simple scenario with an addition service:

[ServiceContract]
interface IAdditionHandler
{
    [OperationContract(IsOneWay = true)]
    void AdditionCompleted(int sum);
}

[ServiceContract(CallbackContract = typeof(IAdditionHandler))]
interface IAdditionService
{
    [OperationContract(IsOneWay = true)]
    void AddTwoNumbers(int numberOne, int numberTwo);
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]
class AdditionService : IAdditionService
{
    public void AddTwoNumbers(int numberOne, int numberTwo)
    {
        IAdditionHandler additionCallback = OperationContext.Current.GetCallbackChannel<IAdditionHandler>();
        additionCallback.AdditionCompleted(numberOne + numberTwo);
    }
}

There are several difficulties with Duplex channels:

• The service needs a channel to the client which is problematic for security reasons. It might not even be possible to keep the channel open due to firewalls and Network Address Translation problems.
• Scaling the service becomes difficult due to the long running sessions between the client and the service. SOA scales best with the RequestResponse pattern where each request is independent
• Diminished interoperability: Duplex implemented with WCF cannot be consumed with from other client types such as Java. RequestResponse operates with primitives which are found in virtually every popular platform: Java, PHP, Objective C, you name it

In case the client request triggers a long-running process in the service then do it as follows:

1. Send a Request with the service with the necessary parameters
2. The service starts the long process on a separate thread and responds with a reservation ID or tracking ID etc. as mentioned above
3. The long running process updates the state of the job in some repository periodically: started, ongoing, about to finish, finished, exited with error, etc.
4. The service has an interface where the client can ask about the state of the job using the reservation ID
5. The client periodically checks the status of the job using the reservation ID and when its complete then it requests a result – or the result is sent automatically in the response in case the job is completed

In the next post we’ll start building the model application using these patterns – with the exception of the Duplex MEP as it’s too complex and rarely used nowadays.

View the list of posts on Architecture and Patterns here.