It’s not uncommon for blog posts about monads to say something like, “monads are cool because you have been using them all along and you didn’t even know it, and once you know it the world gets even more awesome.” I prefer to try to make this argument along the lines of, “monads are cool because you have had the potential to use them all along and when you recognize & leverage them in the structures you are using, your code gets better and then the world gets even more awesome.” Saying “your code gets better” is a broad statement, I know, but I will be expanding on that throughout this post.

Using the monad for RiakOperation[T] we can chain together operations without having to call execute() (performing the side-effect) until the chain has been completely constructed. This gives us greater control of the side-effects our application performs.

The meat of the code in this post will be written in Scala, because I am more familiar with and prefer it, but it can be done in Java. In case you haven’t seen the Riak Java Client before, here is its original definition:

1
2
3
4
5

public interface RiakOperation<T> {

    T execute() throws RiakException;

}

RiakOperations Do Not Compose (Yet)

Once we have implemented the monad instance for RiakOperation[T] we will be able to compose instances. Composition is a much larger subject but specific to this case it means the ability to build up a RiakOperation[T] that, when we finally call execute() on it, runs all of its parts returning a final value of type T. Here is a quick example of why we can’t do this (yet). Say we want to create a bucket, store a value at a key, and then fetch a key in that bucket. This requires three instances of RiakOperation[T], one WriteBucket, one WriteObject[T] and one FetchObject[T]. From the README we can see how to do this:

1
2
3
4
5
6

// create a new bucket
Bucket myBucket = riakClient.createBucket("myBucket").execute();
// add data to the bucket
myBucket.store("key1", "value1").execute();
//fetch it back
IRiakObject myData = myBucket.fetch("key1").execute();

In order to fetch and store data from a bucket we needed a reference to a bucket itself, which required a call to execute(). In real code, we would have wrapped either that entire thing in a try/catch or wrapped each component part, perhaps putting some of them behind our own methods for clarity. In the former case, however, we are directly preventing composition. Another exception handling block is required if we then want to fetch or create a bucket and perform some map/reduce functions on it. In the latter case, we are adding code to allow us to use the pieces more easily. However, in both cases, this isn’t composition, its just simply writing more code. Code written this way in a real application gets unwieldy, verbose and harder to test over time.

The primary benefit of composition is we can control when all of the actions happen, since we execute them all in one call, as opposed to forcing them to happen individually. This has far-reaching implications both in our application’s source and its tests. Pure code is more reuseable and as a result we write less of it. We don’t have to write extra exception handling blocks or duplicate logic. In tests, having full control over when side-effects happen makes writing and reasoning about those tests much easier.

Making RiakOperation Composeable

In order to make RiakOperation[T] composeable we need to implement the necessary functions that define the monad instance. To do this begs the question, if you are not familiar with the answer, “What is a Monad?” I won’t pretend to the be the authority on this as its a subject I still work on learning & understanding everyday and I won’t give a clinical definition here. You may find this to be a good resource to start. The way I like to think of monads is they allow us to chain operations together where operations in the chain may depend on the previous ones. There is more to monads than this but it’s enough to explore our topic, RiakOperation[T]. We want to be able to chain RiakOperation[T]s together when some of the calls depend on previous ones returning a new RiakOperation[T]. Only at the end, not at any intermediate point in the construction of the chain, do we call execute(). If an exception is thrown somewhere in the chain after execute() is called, execution stops.

To implement the monad instance we will use Scalaz7 and its Monad[M[_]] type class. We will need to provide implementations for two functions: bind[A,B](ra: RiakOperation[A])(f: A => RiakOperation[B]): RiakOperation[B], commonly called flatMap in Scala, and point(a: => A): RiakOperation[A], which takes any simple value of type A and lifts it into the monad. bind allows us to compose RiakOperation[T] instances and point makes it possible to take simple values and use them within the RiakOperation[T] that we build up.

1
2
3
4
5
6
7
8
9
10

import com.basho.riak.client.operations.RiakOperation
import scalaz.Monad

object RiakOperationW {

  implicit def riakOpMonad[T] = new Monad[RiakOperation] {
    def point[A](a: => A): RiakOperation[A] = ...

    def bind[A,B](ra: RiakOperation[A])(f: A => RiakOperation[B]): RiakOperation[B] = ...
}

Before we look at the implementation, lets see the result. Scalaz7 allows for Standalone Type Class Usage which helps reduce the cognitive load in seeing how things work at the cost of some prettier syntax. We will use that method now and explore nicer syntax and use of for-comprehensions later. To work through our example we need to import some packages from the Riak Java Client, as well as scalaz.Monad, and our implicit Monad[RiakOperation] instance:

1
2
3
4
5

import com.basho.riak.client._
import bucket._
import operations._
import scalaz.Monad
import RiakOperationW._

We will then get an instance of a Riak Client (in this case, over HTTP and connected to a single node, but it doesn’t matter):

1

val riakClient = RiakFactory.httpClient("http://localhost:8091/riak")

We, also, need the standalone Monad instance for RiakOperation, Monad[RiakOperation]. Note: You may have noticed above that we write Monad[RiakOperation] and not Monad[RiakOperation[T]]. That is because the type parameter for Monad[M[_]], takes one type parameter. Or M[_] is a type function of one argument. We get a concrete RiakOperation[T] using the type parameters in point and bind, applying them to the type function.

1

val M: Monad[RiakOperation] = Monad[RiakOperation]

With a reference to the instance, we can chain operations together and lift pure values into operations:

1
2
3
4
5

val bucketName = "test-bucket"
val bucketNameOp: RiakOperation[String] = M.point(bucketName)
val fetchBucket: RiakOperation[Bucket] = M.bind(bucketNameOp){
  (s: String) => riakClient.fetchBucket(s)
}

Here, we take a string value and lift it into RiakOperation[String]. We then compose that operation with a FetchBucket operation, a RiakOperation[Bucket], using the string that will be returned from the former as an argument to the latter (the latter depends on a previous operation). We haven’t called execute() still so we have preserved the RiakOperation[T] structure and have not made a real HTTP call or received a real reference to the bucket yet. Before we call execute we can continue to build more operations, like one to store a key/value pair in the bucket and another to fetch:

1
2
3
4
5
6

val fetchKey: RiakOperation[IRiakObject] = M.bind(fetchBucket) {
  (b: Bucket) => b.fetch("key"))
}
val storeKey: RiakOperation[IRiakObject] = M.bind(fetchBucket) {
  (b: Bucket) => b.store("key", "value")
}

It doesn’t matter in what order we define fetchKey and storeKey because they haven’t actually executed anything against the database yet. Its not until we call execute() that anything will happen.

1
2
3
4
5
6
7
8

scala> fetchKey.execute()
res5: com.basho.riak.client.IRiakObject = null

scala> storeKey.execute()
res6: com.basho.riak.client.IRiakObject = null

scala> fetchKey.execute()
res7: com.basho.riak.client.IRiakObject = com.basho.riak.client.DefaultRiakObject@26151aae

This was a pretty simple example but, if we had something more realistic, writing code this way could get rather sphagetti-like. That’s why the syntax extensions from Scalaz7 and the ability to use the monad in for-comprehensions, that we will discuss later, is convenient.

Lets switch back to the implementation though. The easier and more obvious implementation is point. To implement point means we are lifting a value of type A into a RiakOperation[A], which basically means that value is returned when we call execute() on that operation.

1
2
3

def point[A](a: A): RiakOperation[A] = new RiakOperation[A] {
   def execute(): A = a
}

Easy enough. Now onto bind. This implementation is a little tricky at first but, once you know it, its rather obvious. When we call bind we pass in an initial operation of type RiakOperation[A], ra below, and a function A => RiakOperation[B]. In order to get that value of type A out of the RiakOperation we must call execute on it, but we don’t want that call to happen until we call execute on the result returned from bind. Next we pass that value of type A into the provided function returning a new RiakOperation[B]. Our result is a RiakOperation[B] that when execute() is called returns what would have been returned by the RiakOperation[B] returned by the function had we called execute() on it. This leads to the following definition:

1
2
3

def bind[A,B](ra: RiakOperation[A])(f: A => RiakOperation[B]): RiakOperation[B] = new RiakOperation[B] {
  def execute(): B = f(ra.execute()).execute()
}

Simpler, we can just write this as:

1

def bind[A,B](ra: RiakOperation[A])(f: A => RiakOperation[B]): RiakOperation[B] = f(ra)

That’s it. We have implemented the Monad[RiakOperation] instance. With that simple bit of code we are able to chain operations together, or compose them, giving more control over the side-effects they perform. In addition, we can leverage all of the other functions provided via the Monad library, defined as part of Scalaz.

The Prettier Syntax

By importing scalaz.syntax._ we get a nice set of syntax extensions we can use with our new monad instance. For example, we can write the above standalone type class examples with a more “object-oriented feel” to them.

1
2
3
4
5
6

val bucketName = "test-bucket"
val fetchBucket: RiakOperation[Bucket] = bucketName.point[RiakOperation] flatMap {
  riakClient.fetchBucket(_)
}
val fetchKey: RiakOperation[IRiakObject] = fetchBucket flatMap { _.fetch("key") }
val storeKey: RiakOperation[IRiakObject] = fetchBucket flatMap { _.store("key", "value") }

We can also use RiakOperation[T]s in for-comprehensions now, allowing us to more cleanly express the closure that is created as we chain multiple ones together.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

val op1: RiakOperation[IRiakObject] = for {
  bn <- bucketName.point[RiakOperation]
  k <- "key".point[RiakOperation]
  b <- riakClient.fetchBucket(bn)
  _ <- (b.store(k, "value"): RiakOperation[IRiakObject])
  v <- (b.fetch(k): RiakOperation[IRiakObject])
} yield v

val op2: RiakOperation[Bucket] = for {
  bn <- bucketName.point[RiakOperation]
  k <- "key".point[RiakOperation]
  b <- riakClient.fetchBucket(bn)
  _ <- (b.store(k, "value"): RiakOperation[IRiakObject])
} yield b

Part 2

In the for-comprehension, the type annotations are necessary to help along the Scala type-inferencer and is one of the reasons I chose to use the IO monad in Scala instead of implementing Monad[RiakOperation]. I plan to cover this in more detail in a subsequent post.

To close, I found this comment interesting when perusing the RiakOperation source, “Just like Callable, hey, wait, maybe it should just be replaced with Callable”. Scalaz defines a monad instance for Callables.