Recently, I’ve been working on a Web Api system where, thanks to support of @jeanlaurent http://morlhon.net/blog/, I used Scala applying DCI architecture in a real world project. This post is about reporting benefits of using this approach. Other posts will follow that will be more focused on the use of Scala and Functional Programming in that project. Code included is a bit simplified and parts of the system that are not of interest are omitted.

The concerned part of the system is an API for logging a Web API usage and using it for showing interesting statistics to users and for implementing a Web 2.0 business model authorization.

The story starts with an API key passed as a parameter in the requested URI something like product/1234?api_key=AFFSEFFVFE2344

I create an object that represents the API user containing the key: (did I tell I like one liners?)

This is a class of an object that holds the apiKey, now I need a method that I will call to log the use of product/123 for user represented by the apiKey AFFSEFFVFE2344. What could be quite convenient and OOP-iesh is to call a record method on the apiKey instance, something like apiUser.record(…) . The problem with this, as explained in the original DCI article, is that adding these methods to the domain objects adds noise in other contexts for which recording is not relevant such as authorization and statistics, as we will see later. I would rather use here the DCI’s role concept (or context). Doing so I would say (apiUser in recording role).record(…) . This pseudo code tends to be very close to mixins implemented in Scala language and will look like following in real world Scala code:

Here the ApiUser object doesn’t contain a record method by default and so it can be shared in different contexts. In other words we kept our domain objects pure yet not scarifying OOP convenience. Now the Recorder is a trait that minds only business in the context of recording. The definition looks like the following:

Another view of the system is the end user’s statistics. Statistics should be represented in a meaningful way to the user and the user can’t care less about how the recording is done. So, it is quite desirable not to have the noise of recording when talking about the statistics view context. Here is how the call looks like in our example in Scala:

Again what we are doing here looks merely like saying: I want to use the ApiUser in a statistics context and I choose to call method getRequestsPerMonthForLast12Months. I guess the convenience brought by using this approach is obvious. This is how the Statistics trait looks like:

Note that as in the Recording trait, the ApiUser object is not passed as an explicit parameter but rather as an implicit receiver parameter (something like this for an object). To access it we use Self that refers to it.

The third view of the system is what allows us to provide an authorization mechanism based on user’s activities for a business plan they choose (be it a quota per day, per month or other interesting combinations). It could be quite convenient to have the call looking like apiUser.isAuthorized . We get pretty close with DCI without polluting our domain object with a specific context logic:

Like the previous, the Authorizer trait looks straightforward :

Now that we looked at the three views of our system introducing three examples of “Context” from DCI pattern we can go beyond that to discover how we use nested contexts (or roles).

Looking at the Authorizer trait, the ApiUser referred to by Self, doesn’t tell us much about how many requests the user did today or this month. And for authorizing user one needs a richer ApiUser that can give the necessary information that live themselves in a file or a database. But once again, we don’t want to pollute our domain object with Data Access code that varies on a different axis than the domain object itself.  Introducing a nested context/role that adds the Data Access logic would pretty convenient here:

Here Self is a richer ApiUser that carries Requests Data Access logic defined in the RequestsDataAccessor trait:

And the implementation of the Authorizer trait defined in terms of ApiUser with RequestsDataAccessor:

In the same way we implement the Statistics and Recorder traits using ApiUser with RequestsDataAccessor:

If you are not familiar with generics ( getRequestsPer[Day] ) you can ignore them since they are not central to the subject of this post and simply use their readability to understand the purpose of the method. The use of generics in this project will be the subject of a future post.

Encapsulation Test!

Now in the first version of the system, the ApiKey was passed in clear in the service URI. This is not very secured as it is quite easy to get the key and use it for using the API. We might prefer to encrypt the key in some way. This fortunately changes nothing for any of our traits implementations since the decryption of the key is the responsiblity of the ApiUSer object and all what our traits need is to get the concerned ApiKey from that object which can be easily done with pattern matching. Same thing if we want to replace database logging with file system in RequestsDataAccessor. Modularity and separation of concerns are apparent in this DCI architecture implementation.

Conclusion

This is a refreshing approach to OOP. The Domain Context Interaction pattern allowed us to restore interesting properties of real OOP approach yet not sacrificing modularity and separation of concerns. This simple view of “an object in several contexts” helps quite much in thinking explicitly about and understanding context boundaries. Note that an object(instance) is not defined by a single class but each instance curries the necessary context. This is essential to OOP which is NOT COP (for Class Oriented Programming ;) )

Feel free to ask questions and/or comment about this implementation. Refer to original papers for more in-depth explanation of the pattern.

Thanks to JetBrains’ IDEA and the Scala plug-in that helped me programming in Scala.

One of the few things that lack seriously, IMO, in C# is the power of Java checked exceptions. In Java world? things happen weirdly. Maybe it is a result of crowd intelligence and a bad side effect of open source. Often, people in J2EE world tend to believe the opposite. Anyway you see the effect in most preferred frameworks (such as today’s popular ORMs and Containers) of wrapping checked Java exceptions and rethrowing them as runtime ones.

I guess offering runtime exceptions together with compile time ones did a hole in the Java type system, but this hole was left to discipline, in a way of giving the tools and letting smart enterprise programmers decide for the right tool for the job. Things turned to happen differently in the enterprise world.  Programmers abused of this freedom of choice and mainstream frameworks designers decided to dismiss and bury one of the most interesting features of the Java type system.

Why do I like Java checked exceptions? Well simply because it saves me from surprises. And I tend not to like surprises much!

The funny thing is that, in my experience, it is mostly architects that dismiss Java checked exceptions whereas Compile time exceptions are a very good asset for cleaner and bug free architecture.

I just take a look at a “standard” DAO method that gets an entity

Customer getCustomer(CustomerId id);

This method lies! what if there is no connection? what if the Id is incorrect? The signature of the methods gives quite a promise that under all circumstances it will returns a Customer. Now for any architecture this is bad. It used to be better before some popular frameworks decided to completely omit it! Before? well I used to control my architecture better!

Before these “good practices” become mainstream, imposed in mainstream frameworks, It used to be often more predictable the return type a method has. For my example, the signature would tell me that the method will either return a customer OR throws a “Dao Exception”.

Customer getCustomer(CustomerId id) throws DaoException;

No surprise. Now when I use this method, I will certainly need to handle the case when the method will return something else than a Customer. Now of course, a Java “enterprise developer” could do one of to things:

1- Out of laziness or incompetence, keep rethrowing data access exceptions up until you’ll have to deal with it up in the GUI logic (where handling an infrastructure error does not often belong)

This often sounds for me the main argument for dismissing Java Compile Time Exceptions claiming that it is a “code boilerplate”. The thing is that you’ll have to deal with these exceptions once even when you turn them into runtime. The fact of wrapping them into runtime does not eliminate them (even if I wish it did). But having them as compile time will make easy to spot where a “bad” developer did not handle the exception correctly simply by following the signature and type system. Then the solution will be to wrap them into more business friendly, context meaningful Compile Time Exceptions that need to be handled. This way the contract communicated better the result of executing a piece of logic.

This turns to be as useful for “void” return type methods. With Compile Time Exception a method can simply communicate the fact that it will either return “void” or will throw an exception to be handled.

2- Out of laziness or incompetence, frustrated developers will start “catch”ing checked exception without rethrowing them.

This one is a result of the hole in the type system that is left intentionally to leave some place for flexibility relying on discipline. Nevertheless, and before the big favor of generous frameworks I mentioned earlier, this turned out to be an easy problem to spot. Most IDEs and code analyses tools can find easily empty catch clauses and warn me about them.

I often get surprised of the limited use of Java language wealth in enterprise J2EE applications!

Good thing: C# and .Net are introducing checked exceptions together with other DbC stuff (like non null objects) in the next release. Sad thing: Java has Compile Time Exceptions since version 1, open source chose to unvalue them!