Functional approach to Exception handling in Scala

Did you know that in functional programming world there is a criticism of throwing exceptions? It seems that it would break a functional programming principle that a function have to always return a value. I'm not sure that this approach is the best for all situations, but I can imagine some cases when it might be good. Especially because Scala dumped the idea of checked exceptions.

So what we could do if we would like not to throw the exception when the exceptional situation occurs? In example, when we receive a zero as denominator in division operator. In standard approach we could throw IllegalArgumentException, but what to do in a purely functional approach? We could return a Not-A-Number value or an Infinity value. But that would not be the best approach if this exceptional situation should be handled somehow. Also there is a risk that this value would be passed further in an application and that might cause a difficult to detect problem in other part of the code.

More reliable solution would be to return an info about the error. We could reuse the IllegalArgumentException, as it is an object that nicely describes the problem and, also, it can hold a stack trace, which can be useful for debugging. So let's look at the example code:

def divide(a:Double, b:Double) = {
  if (b == 0) {
    new IllegalArgumentException("Cannot divide by zero!")
  } else {
    a / b
  }
}

That might work, but what type returns the divide function? In this case Scala compiler we'll choose Any as closest common ancestor. That means, a user of our function we'll have to check returned type and manually cast a result to a Double. You can imagine that this is inconvenient, and sometimes might cause ClassCastException when user won't predict correctly all possible types that might be returned.

Some literature suggests usage of Either[A,B] class from standard Scala's library. Basically this is an extension of an Option idea. Either object can hold a value in one of it's two fields: left and right. This can be leveraged to be useful in exception handling if we assume that we'll always put correct result in right field and error in left field. This way we could have more control over returned type, and we could handle an exception using pattern matching. I would recommend to get familiar with Either class as it can be useful in some situations, but I also think that it is not a best solution to handle exceptional situations. First, for my taste, it is too general and it requires a convention that must be known by every user. I would like to propose a different approach, inspired by Either class, but with more specific purpose.

My solution is based on a new Result class which would be a holder of a function result value, or an exception, if required. Here is it's definition:

abstract class Result[A, E <: Throwable] {
  def isSuccess: Boolean
  def isFailure: Boolean
  def get: A
  def getOrDefault(default: => A): A
  def error: E
}

As you can imagine this class can have two basic states implemented as two case classes, Success and Failure:

final case class Success[A, E <: Throwable](result: A) extends Result[A, E] {
  override def isSuccess = true
  override def isFailure = false
  override def get: A = result
  override def error: E = throw new IllegalAccessException("It's a success, not a failure")
  override def getOrDefault(default: => A): A = result
}

final case class Failure[A, E <: Throwable](err: E) extends Result[A, E] {
  override def isSuccess = false
  override def isFailure = true
  override def get: A = throw err
  override def error: E = err
  override def getOrDefault(default: => A): A = default
}

Those two are very simple implementation of abstract Result[A, E] class. Before we go into details of this implementation let's look how it can be used in our divide function:

class DivideByZeroException extends IllegalArgumentException("Cannot divide by zero")

def divide(a: Double, b: Double): Result[Double, DivideByZeroException] = {
  if (b == 0) {
    Failure(new DivideByZeroException)
  } else {
    Success(a / b)
  }
}

I hope it doesn't require a lot of explanation. Our modified function is returning a Result[Double, DivideByZeroException] type which will be a Failure containing an exception if b is equal zero, or a Success containing the result of computation in other cases.
Let's look closer on a methods provided by Result class:

• isSuccess and isFailure - those methods simply allow us to distinguish between Success and Failure objects
• get - this methods returns a result value in the case of a Success object, or it throws the inner exception object in the case of an Failure object
• error - this method returns an exception object that was contained inside Failure object, or it throws an IllegalAccessException in the case of a Success instance
• getOrDefault(default: => A) - this method is similar to get method, so it returns a result value in the case of Success object, but in the case of Failure instead of throwing an exception it returns a value passed as default (if default is an expression it is evaluated only if needed)

This set of methods, and the fact that Success and Failure are case classes, provides us with a convenient way of handle results returned from functions. Let's look at some examples where function succeedes:

scala> divide(10, 2)
res = Success(5.0)

scala> divide(10, 2).get
res = 5.0

scala> divide(10, 2).isSuccess
res = true

scala> divide(10, 2).isFailure
res = false

scala> divide(10, 2).getOrDefault(27)
res = 5.0

scala> divide(10, 2).error
java.lang.IllegalAccessException: It's a success, not a failure  // IllegalAccessException was thrown

And now the case when function returns a Failure:

scala> divide(10, 0)
res = Failure(java.lang.IllegalArgumentException: Cannot divide by zero)

scala> divide(10, 0).get
DivideByZeroException: Cannot divide by zero  // DivideByZeroException was thrown

scala> divide(10, 0).isSuccess
res = false

scala> divide(10, 0).isFailure
res = true

scala> divide(10, 0).getOrDefault(27)
res = 27.0

scala> divide(10, 0).error
res = DivideByZeroException: Cannot divide by zero  // DivideByZeroException was returned, not thrown

Those were simple, method's use cases, here you can look how it is possible to handle exceptions now:
Simple if checking for success:

val divideResult = divide(10, 2)
if (divideResult.isSuccess) {
  println("Result of division is " + divideResult.get)
} else {
  println("You shouldn't divide by zero")
}

Do you remember the C times when negative number have meant an error?

val result = divide(10, 0).getOrDefault(-1)

And this is probably most convenient way of doing this, with a usage of pattern matching:

divide(20, 5) match {
  case Success(x) => println("Result of division is " + x)
  case Failure(err) => println("Something went wrong: " + err.getMessage)
}

Conclusion
This approach to exception handling is only a proposition how it could be done if we would like to limit the throwing of the exceptions. There are people that believe in clean functional approach to programming and I think that they should be listened and understood. For me, dilemma between throwing an exception or returning it reminds me discussion about checked vs unchecked exceptions, that still doesn't have a winner.

I think that presented approach could be used when an exceptional situation is part of a business, ie. when parsing user's input. In this case we have to provide a response for any data user provided, even this corrupted. On the other hand this approach shouldn't be used to handle exception caused by internal error in our software, ie. parsing a rest request from other part of our system. In this case there is probably nothing smart to do, other than to fail gracefully, so it is best to throw an exception that will be handled by our application server.

I'm sure that with proper care both approaches have the justification for existence, even in one application.

Edit
As Konrad mentioned, Scala 2.10 is equipped with scala.util.Try class, which works almost the same as my Result class. That's great news, you can give it a try with no cost o creating custom class, and if you would like, you can use it in production code already.

Writing a simplified JSON parser in Clojure

Today I want to write a step by step example of creating a parser for JSON. What is extraordinary, I'll use a Clojure to do that. This is because I have to learn Clojure for my current job and I think parsing problem is very good for this, due it's complexity and usefulness.

What is Clojure? Basically it is a programming language that is a dialect of another language called Lisp. And it is targeted for Java Virtual Machine. Here is some minor description from clojure.org:

Clojure is predominantly a functional programming language, and features a rich set of immutable, persistent data structures.

For those that aren't familiar with Clojure this article might be too difficult, because Clojure has a tremendously different syntax than ie. Java or Scala. In that case it would be better to start with some other tutorial that covers Clojure basics or with some book, ie. "Practical Clojure". I found that book to be a very good, easy to read and a comprehensive introduction to the language.

Enough introduction, let's go to our parser problem.

Define parser requirements

We want to write a JSON parser. Why JSON? I've chosen it because of a couple of reasons. First it is very popular in many commercial usages (ie. RESTful services or NoSQL databases), on the second hand it has very simple syntax so it will be good for training.

JSON syntax is defined on a page www.json.org. So basically in JSON we could have 6 different value types:

1. Object - wrapped in curly brackets, properties separated by commas and values separated from properties names separated with colon. ie. {name:"Marcin", surname:"Pieciukiewicz"}
2. Array - wrapped in square brackets, values separated with commas, ie. ["dog","cat","cow"]
3. String - sequence of characters wrapped in double quotes, ie. "dog"
4. Number
5. Boolean - true or false
6. Null - null

For our purpose I would like to make some simplifications to the syntax, so we could focus on general parsing problems:

1. No white characters are allowed (outside a string)
2. Number can be non negative integer only
3. String cannot contain double quotes and escape character won't be supported, so "\" will be treated as normal character
4. Parsed JSON is always correct

All those simplifications are introduced so our parser could be simple enough to well fit in this article.

Parsing based on sequence traversing

Clojure provides us with a powerful sequence mechanism and we will use it to traverse through a JSON string. You can imagine that we want to have a cursor over a JSON string that will be used to read subsequent characters, and it will only move forward (from the beginning of the json string, to the end).

To do so we'll have to utilize two commands:

(first some-string)

and

(rest some-string)

first command simply returns first element from the given sequence, and rest command returns a sequence of the elements after the first element. We'll use this commands extensively mainly in recursive operations. It's important to notice that first and rest functions work on sequence passed as parameter, in our case this functions implicitly converts passed string into a sequence.

To understand better how we'll utilize those functions this is a simple example of printing every character from stream in separate line:

(defn print-in-lines [text]
  (if (not (empty? text))
    (do
      (println (first text))
      (recur (rest text)))))

This function first checks if given text is not empty and, if so, it prints out the first character of text and then calls itself recursively with text parameter stripped of the first character.

Detect element type

Because our parser will traverse json string only once we need to detect what kind of element is going to be next. To do that we'll define a set of functions that will check the first character from json sequence and compare it with a character from JSON syntax. Ie. we want to be able to detect beginning of an object. To do so we'll define is-object-opening? function:

(defn is-object-opening? [json] (= \{ (first json)))

As you can see (which might be hard in Clojure ;)) this function takes a json sequence and checks if it's first character is an opening curly bracket “{“. And in the end it returns boolean value. Also we would like to know when this object ends, so let's define function to detect closing curly bracket:

(defn is-object-ending? [json] (= \} (first json)))

This is very simple, so let's define this kind of functions for array and string detection:

(defn is-array-opening? [json] (= \[ (first json)))
(defn is-array-ending? [json] (= \] (first json)))

(defn is-string-opening? [json] (= \" (first json)))
(defn is-string-ending? [json] (= \" (first json)))

Also we'll need to detect integers, boolean values and nulls. To do that we'll assume that integer value starts with a digit from 0 to 9, boolean value starts with lowercase 't' (for true) or lowercase 'f' (for false), and null starts with lowercase 'n'. Now we can define functions that will detect those values:

(defn is-boolean-opening? [json] (or (= \t (first json)) (= \f (first json))))

(defn is-null-opening? [json] (= \n (first json)))

(defn is-digit? [json]
  (and
    (>= (int (first json)) (int \0))
    (<= (int (first json)) (int \9))))

(defn non-digit? [json]
  (not (is-digit? json)))

As you can see I haven't defined functions that detects the end of boolean or null value. That is because we exactly know what values can start with 't', 'f' or 'n' and in particular how long they are. And we'll use this knowledge later.

For integers instead of creating is-integer-opening? and is-integer-ending? I've created more generally named functions that do exactly the same thing.

Parsing primitive values - number, string, boolean and null

When we know what is going to be next in the sequence we want to parse it. We'll start with a basic types, object and array we'll leave for later.

So we need to create a function for each type that will return a parsed value, and, evenly important, a new sequence that is pointing just after parsed value. You can think about it as returning new cursor position in json text.

Parsing string.

String parsing is about reading our json stream until we occur double quote symbol. We'll do that recursively (tail-recursive). What is important, we assume that json sequence passed to this function doesn't start with opening double quote, because it was "consumed" when we checked value type. This is parse-string function implementation (in first call string is initialized to an empty string ""):

(defn parse-string [json string]
  (if (is-string-ending? json)
    [string (rest json)]
    (recur (rest json) (str string (first json)))))

As you can see we check first character of json to see if we should finish parsing. If so we return string (which is our accumulator of read value) and the remaining json sequence. We've used rest function to skip closing double quote character. Otherwise, if we haven't found double quote, we remove first character of passed sequence and concatenate current string value with first character in current sequence and make a recursive call to parse-string function.

Parsing number.

Number parsing is very similar to string parsing. We simply read subsequent character until it's not a digit, and meanwhile we increase an accumulated value (in first call number have to be initialized to zero):

(defn char-to-number [character]
  (- (int character) (int \0)))

(defn parse-number [json number]
  (if (non-digit? json)
    [number json]
    (recur (rest json) (+ (char-to-number (first json)) (* number 10)))))

To convert a digit character into corresponding numerical value I've created char-to-number function that simply casts character into ASCII integer value and calculate difference between that value and integer value of '0' character.

Parsing boolean.

To parse a boolean we'll just have to check the first letter. If it is 't' the value is 'true', if the first letter is 'f' the boolean value is 'false'. Now implementation of parser function is very simple:

(defn parse-boolean [json]
  (if (= \t (first json))
     [true (drop 4 json)]
     [false (drop 5 json)]
    )
  )

We don't have to detect where the value string ends because we know that true is 4 characters long, and false is 5 characters long, so we'll just drop corresponding number of characters from json sequence.

To be clear, we could do that because we assumed that json we are parsing is correct.

Parsing null.

Parsing null value is even simpler than parsing a boolean value. Because we'll call our parse-null function after we detected null value, we'll only need to skip 4 characters from json sequence and return nil:

(defn parse-null [json]
    [nil (drop 4 json)]
  )

Call a parse function for a detected type

Now we have to combine our detection of element type with proper parse function. To do that we'll create parse-value function (because everything is a value ;)):

(declare parse-object parse-array)

(defn parse-value [json]
  (cond
    (is-digit? json) (parse-number json 0)
    (is-boolean-opening? json) (parse-boolean json)
    (is-null-opening? json) (parse-null json)
    (is-string-opening? json) (parse-string (rest json) "")
    (is-object-opening? json) (parse-object (rest json) {})
    (is-array-opening? json) (parse-array (rest json) [])
    :else (println "Incorrect character?")))

Also we've declared parse-object and parse-array functions, so parse-value function would compile. We'll implement those functions later.

Parse array

Array parsing will be a little more complex. Basically we need to read elements separated by comma character, until we occur closing square bracket “]” that is closing the array. We'll do that by recursively calling our array-parse function and in each run it will read one element of the array. This is the implementation:

(defn drop-comma-if-first [json]
  (if (= \, (first json))
    (rest json)
    json))

(defn parse-array [json array]
  (if (is-array-ending? json)
    [array (rest json)]
    (let
      [value-result (parse-value (drop-comma-if-first json))
       value (nth value-result 0)
       rest-json (nth value-result 1)]
      (recur rest-json (conj array value)))))

As you can see we simply stop the recursion when the first element of json stream is “]” character (is-array-ending? function). If not, we have to read element value and to do that we'll use parse-value function. There is also drop-colon-if-first function used - it simply skips the first colon in json sequence if it is present, this is the case when we want to read second or subsequent element from array and we need to skip separator.

Also in parse-array function we use let statement so we can acquire result of parse-value function that is a vector containing parsed value, and also the new json stream that points just after parsed value. After that we simply call parse-array function recursively with new json stream and array with added value we've just parsed (we've used conj function to do that).

Parse object

Object parsing is very similar to array parsing, with the difference that we also need to parse the key name of the value. To do that we have to introduce a method that will be responsible for parsing of that key:

(defn parse-property-name [json name]
  (if (= \: (first json))
    [name json]
    (recur (rest json)
           (str name (first json)))))

It works alike parse-string function, but instead of looking for double quote it is looking after colon to check if the name has ended. Next, let's look at the implementation of parse-object function:

(defn parse-object [json object]
  (if (is-object-ending? json)
    [object (rest json)]; rest to skip closing '}'
    (let
      [property-name-result (parse-property-name (drop-comma-if-first json) "")
       property-name (nth property-name-result 0)
       value-json (rest (nth property-name-result 1))
       value-result (parse-value value-json)
       value (nth value-result 0)
       rest-json (nth value-result 1)]
      (recur rest-json (assoc object property-name value)))))

As you can see it has very similar construction to parse-array function. In let statement it calls parse-property-name function, remembers it's result, then calls parse-value function. Also it uses assoc function to add new property to constructed object.

Main parser function
The last thing to do is to create a main function that can be access point to our parser:

(defn parse-json [json]
  (nth (parse-value json) 0))

It simply calls parse-value function and from it's result extracts first element which is a parsed element. That's all.

Summary
I hope that this example showed that Clojure is a good way to solve more complex problems, such as string parsing. It might not be a best language to do so, but it is not a great struggle to work with it either. For sure Clojure will force you to think differently than Java and this might be it's greatest advantage.

Source code with full solution is available on gist.github.com: json_parser.clj.

Scalatra - How to setup with Maven and Jetty

Recently I was inspired by a colleague to dig into AngularJS and Scalatra web application stack, so today I'll continue with first steps in digging into Scalatra.

Description from www.scalatra.org:
Scalatra is a simple, accessible and free web micro-framework.
It combines the power of the JVM with the beauty and brevity of Scala, helping you quickly build high-performance web sites and APIs.

And when you look at examples you can get feeling that this might be a great framework to help you develop your applications quickly:

package com.example.app
import org.scalatra._

class HelloWorldApp extends ScalatraFilter {
  get("/") {
    <h1>Hello, {params("name")}</h1>
  }
}

So let's start playing with it by creating a sample project that will use Maven as the build tool and a Jetty server as our application's container.

1. Define build process and application dependencies
To start we need to create main pom.xml file required by maven. It will be placed in the main directory we've created for our project.
First we need to configure it to properly compile Scala language sources. I have described this process in article Maven configuration example for Scala. So you should follow instructions from that article.

When this is done we'll add support for Scalatra. To do that we'll need to include org.scalatra:scalatra dependency in pom.xml. Also let's include library org.scalatra:scalatra-specs2 that will add support for writing tests in the future. So add this part of code inside <dependencies> tag (To be clear, I've used a Scalatra dependencies prepared for Scala 2.10, this is the reason for weird suffixes in artrifactId):

<!-- Scalatra -->
<dependency>
    <groupId>org.scalatra</groupId>
    <artifactId>scalatra_2.10</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.scalatra</groupId>
    <artifactId>scalatra-specs2_2.10</artifactId>
    <version>2.2.0</version>
    <scope>test</scope>
</dependency>

Also Scalatra requires that Java Servlet API 2.5 be available during application compilation, so we'll add it in provided scope:

<!-- Servlet API -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>servlet-api</artifactId>
    <version>2.5</version>
    <scope>provided</scope>
</dependency>

That will be all to support Scalatra in our application, now let's add Jetty so we'll be able to run our application without any external application server. This only requires to add a plugin inside a <build> -> <plugins> tag:

<plugin>
    <groupId>org.eclipse.jetty</groupId>
    <artifactId>jetty-maven-plugin</artifactId>
    <version>9.0.2.v20130417</version>
</plugin>

Now the configuration of our build process is complete. To summarize this is my complete pom.xml for this example:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>pl.marpiec</groupId>
    <artifactId>scalatratest</artifactId>
    <version>1.0-SNAPSHOT</version>

    <packaging>war</packaging>

    <properties>
        <scala.lang.version>2.10.1</scala.lang.version>
        <scala.maven.version>2.10.1</scala.maven.version>
        <scalatra.version>2.2.0</scalatra.version>
        <jetty.version>9.0.2.v20130417</jetty.version>
    </properties>

    <repositories>
        <repository>
            <id>scala-tools.org</id>
            <name>Scala-tools Maven2 Repository</name>
            <url>https://oss.sonatype.org/content/groups/scala-tools/</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>scala-tools.org</id>
            <name>Scala-tools Maven2 Repository</name>
            <url>https://oss.sonatype.org/content/groups/scala-tools/</url>
        </pluginRepository>
    </pluginRepositories>


    <dependencies>
        <!-- Scala -->
        <dependency>
            <groupId>org.scala-lang</groupId>
            <artifactId>scala-library</artifactId>
            <version>${scala.lang.version}</version>
        </dependency>

        <!-- Scalatra -->
        <dependency>
            <groupId>org.scalatra</groupId>
            <artifactId>scalatra_2.10</artifactId>
            <version>${scalatra.version}</version>
        </dependency>
        <dependency>
            <groupId>org.scalatra</groupId>
            <artifactId>scalatra-specs2_2.10</artifactId>
            <version>${scalatra.version}</version>
            <scope>test</scope>
        </dependency>

        <!-- Servlet -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.5</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.scala-tools</groupId>
                <artifactId>maven-scala-plugin</artifactId>
                <version>${scala.maven.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>compile</goal>
                            <goal>testCompile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.eclipse.jetty</groupId>
                <artifactId>jetty-maven-plugin</artifactId>
                <version>${jetty.version}</version>
            </plugin>
        </plugins>
    </build>
</project>

2. Configure web application by web.xml file
To be able to run our web application we need to create a standard Java web application description file, web.xml. Let's create this file inside [Project Dir]\src\main\webapp\WEB-INF\ directory. It's content is very simple:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 

         http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">

    <context-param>
        <param-name>org.scalatra.LifeCycle</param-name>
        <param-value>pl.marpiec.scalatratest.servlets.ScalatraBootstrap</param-value>
    </context-param>
    <listener>
        <listener-class>org.scalatra.servlet.ScalatraListener</listener-class>
    </listener>
</web-app>

This will tell an application's server (Jetty in our case) that it have to call a ScalatraListener when application starts. Also context parameter org.scalatra.LifeCycle points to the ScalatraBootstrap class that will be used by our application. This parameter is not required, but without it you will have to put ScalaBootstrap class in root package, and that would be ugly. Also, you probably want to change the package name that is used to be align with your project ;).

3. Create your first Scalatra servlet
So now let's create our first servlet that will send simple responses for GET requests. This servlet might look like this:

package pl.marpiec.scalatratest.servlets

import org.scalatra.ScalatraServlet

/**
 * @author Marcin Pieciukiewicz
 */
class MainServlet extends ScalatraServlet {
  get("/") {
    <html>
      Hello to scalatra
    </html>
  }

  get("/json-page") {
    "<json-response>Hello to scalatra</json-resonse>"
  }
}

As you can see this servlet will send an html response for the request of root application address, and it will send string containing json if /json-page is requested.

4. Create ScalatraBootstrap class
The last thing to do is to create a class mentioned earlier: ScalatraBootstrap, and then bind our servlet with proper URL path:

package pl.marpiec.scalatratest.servlets

import org.scalatra._
import javax.servlet.ServletContext

class ScalatraBootstrap extends LifeCycle {
  override def init(context: ServletContext) {
    context.mount(new MainServlet, "/*")
  }
}

This class is basicly starting point for scalatra configuration. In our case we've just added our server to be mapped for all url suffixes.

And now our sample application is complete.

5. Test application
To test this application we have to run it on servlet container, and as it was mentioned earlier we'll use Jetty runned as Maven plugin. So to start our server with our application just run:

mvn jetty:run

After a while a Jetty server will be running and listening on port 8080 on localhost. So just check the responses under http://localhost:8080:

And http://localhost:8080/json-page:

AngularJS example - simple calculator

Recently my attention was focused on a very interesting JavaScript framework named AngularJS. It is a framework created by Google to augment creation of rich browser-based application. In this article I would like to present an example of application created with AngularJS that will use some of the features provided by this framework. Of course I've just began to learn AngularJS so this article contains examples of basic concepts used by AngularJS.

1. Application concept
Our application will be a very simple calculator, that provides the four basic mathematical operations, and it will work on integer numbers. The expected layout should be like that:

2. Download AngularJS framework
AngularJS framework is distributed as a single JavaScript file and can be acquired on the angularjs.org page. Just choose stable and mininified version of the file. It will be named angular.min.js. When I was writing this article the stable version was 1.0.7.

3. Create an application's structure
Our application will be organized in this directory structure:

Calculator             Main project directory
|--lib                      
|  |--js                    JavaScript 3rd party libraries
|--app
   |--js                    JavaScript application source files
   |--style                 CSS files
   |--view                  HTML files

When the application's structure is created, then we copy downloaded angular.min.js file into Calculator/lib/js directory.
Then let's create basic source files that will define our application. We'll need three of them:

• Calculator/index.html - root view layer file of our application
• Calculator/app/js/app.js - main source file, will put logic in this file
• Calculator/app/style/default.css - main cascading style file

4. Create AngularJS application
In next step we'll create an html skeleton for our application that will define basic html properties and include our source files. So the content of index.html should look like that:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html ng-app="calculatorApplication">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <script src="lib/js/angular.min.js" type="text/javascript"></script>
    <script src="app/js/app.js" type="text/javascript"></script>
    <link href="app/style/default.css" rel="stylesheet" type="text/css">
</head>
<body>

<div ng-view></div>

</body>
</html>

Beside the standard html header there are two elements that are specific to AngularJS application:

• <html ng-app="calculatorApplication"> 
It tells AngularJS that everything inside html tag is an AngularJS controlled application. And it is a module called "calculatorApplication".
• <div ng-view></div>
This ng-view attribute points to the element that will be a container, where AngularJS will put created view.

As you can see a framework extends a standard HTML with its' own attributes that can be interpreted by AngularJS internals.

After creating HTML structure of our application we have to add some behavior. We'll do that by editing app.js file and adding there this part of code:

var app = angular.module("calculatorApplication", []);

This construct will create AngularJS module called calculatorApplication. Empty square brackets stands for empty list of dependencies that our application will require.
In the next step we would like to define some basic behavior for our application. Basically we want our application to have a home page that will have a welcome message and a link to our calculator.
That page should look like that:

As you can see the url for this page have an interesting #/home suffix. Basically it is an address of our application subpage. This is a standard way to define subpages in AngularJS. Now we would like to bind this /home suffix with some content. So let's add a controller definition of this page by changing app.js content into this:

var app = angular.module("calculatorApplication", []).config(function ($routeProvider) {
    $routeProvider.when("/home", {
        templateUrl: "app/view/home.html",
        controller: "HomeController"
    });

    $routeProvider.otherwise({
        redirectTo: "/home"
    });
});

app.controller("HomeController", function () {
});

A few things are happening in this part of code. First we've called config method and passed a function that will configure our application. This function takes a parameter $routeProvider which is responsible for binding url address (ie. /home suffix) with a proper behavior. In our case we want it to use a home.html template for the view and HomeController when there is /home suffix present. In any other case we want our application to redirect to that address. Also we've defined a controller that is called HomeController with no specific behavior.
The last thing we need to do is to create a template for our home page. So create a file Calculator/app/view/home.html and put this content inside it:

<div>
    <div>
        This is home page:
    </div>
    <div>
        You can go to <a href="#/calculator">Calculator</a>.
    </div>
</div>

As you can see it is very simple html code that will display a message and a link to the calculator page (the page we havn't created yet).

5. First try out of an application
Now you can try to run this application. You can do this in two ways:

• Deploy it on http server and go to url of index.html file
• Open index.html directly from your file system

For now, the latter one will be an easier solution ;)

Attention!
Because of security reasons some browsers can block a javascript to access local files through AJAX request. This is the case at least for a Chrome and an Internet Explorer. I don't know the solution for an IE but if you want to test it in a Chrome you have to run the browser with --allow-file-access-from-files parameter as stated on this stackoverflow question. It should not be the case if you deploy your application in http server.
For a Firefox browser our application should work flawlessly.

6. Add calculator page
To add a calculator to our application first we need to create an html template that will define ours calculator's view. We'll put it inside Calculator/app/view/calculator.html file:

<div class="calculator">
    <div class="display">0</div>
    <div class="digitsKeyboard">
        <div class="digitKey">1</div>
        <div class="digitKey">2</div>
        <div class="digitKey">3</div>
        <div class="digitKey">4</div>
        <div class="digitKey">5</div>
        <div class="digitKey">6</div>
        <div class="digitKey">7</div>
        <div class="digitKey">8</div>
        <div class="digitKey">9</div>
        <div class="digitKey">0</div>
        <div class="equalSignKey">=</div>
    </div>
    <div class="operationsKeyboard">
        <div class="operationKey">/</div>
        <div class="operationKey">*</div>
        <div class="operationKey">+</div>
        <div class="operationKey">-</div>
    </div>
</div>

So basically in our calculator we'll have a display, a keyboard with digit keys and an equal sign key, and a keyboard with possible mathematical operations. We also have to provide a stylesheet for our calculator so it can look properly. So put this CSS inside Calculator/app/style/default.css file:

.calculator {
    display: inline-block;
    background-color: black;
    height: 240px;
    width: 208px;
    overflow: hidden;
}

.display {
    background-color: #DDDDDD;
    border: 1px solid black;
    font-family: monospace;
    font-size: 27px;
    font-weight: bold;
    height: 30px;
    padding: 0 4px;
    text-align: right;
    width: 198px;
    overflow: hidden;
}

.digitsKeyboard {
    overflow: hidden;
    width: 156px;
    float: left;
}

.digitKey {
    width: 50px;
    height:50px;
    background-color: #AABBCC;
}

.equalSignKey {
    width: 102px;
    height: 50px;
    background-color: #AACCBB;
}

.operationsKeyboard {
    overflow: hidden;
    width: 52px;
    height:208px;
    float: left;
}

.operationKey {
    width: 50px;
    height:50px;
    background-color: #CCAABB;
}

.digitKey, .equalSignKey, .operationKey {
    cursor: pointer;
    font-family: monospace;
    font-size: 33px;
    border: 1px solid black;
    line-height: 50px;
    text-align: center;
    float: left;
}

.digitKey:hover, .equalSignKey:hover, .operationKey:hover {
    opacity: 0.8;
}
.digitKey:active, .equalSignKey:active, .operationKey:active {
    opacity: 0.7;
}

The last thing we have to do is to map a /calculator address in our application. So we need to add a calculator page to $routeProvider in exactly the same way we've defined a home page. So add this inside Calculator/app/js/app.js file:

$routeProvider.when("/calculator", {
    templateUrl: "app/view/calculator.html",
    controller: "CalculatorController"
}); 

And also define new empty controller for Calculator:

app.controller("CalculatorController", function () {
});

Now you can try to access calculator page in your browser. Just open the index.html file and click on the calculator link. Then you should see a calculator on the screen.

7. Define calculator constants
Now we'll add some juice to our CalculatorController. To do that let's start by changing the factory function declaration for the controller:

app.controller("CalculatorController", function ($scope) {
});

As you can see we've added a $scope parameter to a function definition. It is an object where our application state is held. For our purpose you just need to know that you can define any field inside the $scope object and it will be accessible in other places in an application.

So let us start with defining a keys of calculator with the required properties by putting this code inside controller's function.

$scope.digitKeys = [
    {label: "1", value: 1}, {label: "2", value: 2}, {label: "3", value: 3},
    {label: "4", value: 4}, {label: "5", value: 5}, {label: "6", value: 6},
    {label: "7", value: 7}, {label: "8", value: 8}, {label: "9", value: 9},
    {label: "0", value: 0}
];

We'll use digitKeys field to define an array of objects that represent every digit key in calculator keyboard. Every key has a label property that will be displayed on given key and a value that will be used for computation.

$scope.equalSignKey = {label: "="};

Here we only need a label for equal sign key. This code is placed here only to be consistent with other keys definitions. Other solution would be just to place equal sign directly inside html file.

$scope.operationKeys = [
    {label: "/", operation: function (a, b) {return a / b}},
    {label: "*", operation: function (a, b) {return a * b}},
    {label: "+", operation: function (a, b) {return a + b}},
    {label: "-", operation: function (a, b) {return a - b}}
];

And the last set of keys are the mathematical operation keys. As you can see we put the operation function inside every object, so that will give us easy access to them, when we'll want to call it.

8. Make calculator rendered dynamically
When we defined our buttons in CalculatorController we can use them to simplify our html template and generate buttons dynamically. Let's start with the easiest case of equal sign key:

<div class="equalSignKey">
    {{ equalSignKey.label }}
</div>

In this case we used {{ }} placeholder to tell AngularJS that we want to put equalSignKey.label value in this place. Angular will look for that value within the $scope object and it will bind it with a corresponding part of an html file.

We'll do similar thing with digit buttons, but we'll use an AngularJS directive named ng-repeat that allow us to iterate over array elements and repeat an html tag for every element in array:

<div class="digitKey" ng-repeat="key in digitKeys">
    {{ key.label }}
</div>

In this case AngularJS iterates over $scope.digitKeys array and puts current element inside a key variable. That way we don't have to repeat html code for every key.

We'll do exactly the same operation for operations keys:

<div class="operationKey" ng-repeat="key in operationKeys">
     {{ key.label }}
</div>

So the resulting calculator.html file should look like that:

<div class="calculator">
    <div class="display">0</div>
    <div class="keyboard">
        <div class="digitKey" ng-repeat="key in digitKeys">
            {{ key.label }}
        </div>
        <div class="equalSignKey" ng-click="compute()">
            {{ equalSignKey.label }}
        </div>
    </div>
    <div class="operations">
        <div class="operationKey" ng-repeat="key in operationKeys">
            {{ key.label }}
        </div>
    </div>
</div>

Now you can test the application to check if it still displays properly.

9. Add calculator behavior
Now we want to make our calculator to behave as real calculator so we'll need to define a variables that will hold a current calculator state. We'll need 5 of those:

• displayValue - current value displayed on calculator screen
• valueA - first (left) value that will be used for computation
• valueB - second (right) value that will be used for computation
• selectedOperation - which mathematical operation was chosen by the user
• clearValue - should value displayed on screen be cleared after new digit pressed?

So let's define them and initialize them with default values. Add this code inside a CalculatorController:

$scope.displayValue = 0;
$scope.valueA = 0;
$scope.valueB = 0;
$scope.selectedOperation = null;
$scope.clearValue = true;

10. Bind displayValue variable with view
As we now have a variable displayValue, we would like it to be displayed in our calculator. And in this place best of AngularJS comes in. To do that just put a {{ displayValue }} placeholder inside a calculator.html changing <div class="display">0</div> so it will look like this:

<div class="display">{{ displayValue }}</div>

That's all!
Now AngularJS we'll do it's tricks to ensure that value displayed on page is equal to the value of the variable. If you change the variable value, then automatically the value displayed on the page will be changed to be the same as the variable.
And that's not all, imagine if display would be editable input field, then when user would input some value inside it, then automatically the value of the binded variable would be changed as well. So it works both ways and it's hugely simplifies development of an application.

11. Add behavior to calculator's buttons
We have all parts of our calculator in place, so now it's time to add a behavior to it. So the main idea is to bind a buttons with correct behavior. To do this with AngularJS we'll use ng-click directive. So let's change the calculator.html template:

<div class="calculator">
    <div class="display">{{ displayValue }}</div>
    <div class="digitsKeyboard">
        <div class="digitKey" ng-repeat="key in digitKeys" 
                ng-click="digitClicked(key.value)">
            {{ key.label }}
        </div>
        <div class="equalSignKey" ng-click="compute()">
            {{ equalSignKey.label }}
        </div>
    </div>
    <div class="operationsKeyboard">
        <div class="operationKey" ng-repeat="key in operationKeys" 
                ng-click="operationClicked(key.operation)">
            {{ key.label }}
        </div>
    </div>
</div>

In this part of code we've added three ng-click directives that contains simple JavaScript function calls:

• For a digit key: ng-click="digitClicked(key.value)"
• For an operation key: operationClicked(key.operation)"
• For an equal sign key: ng-click="compute()"

As you can see we could pass a data defined earlier in AngularJS variables in the same way as we've passed them earlier into {{ }} blocks. The main idea for those changes is to call a corresponding function after clicking on a button.

Now let's define those three functions inside CalculatorController. It is important to notice that those functions have to be defined as a part of $scope object:

• Function to handle digit button click:

$scope.digitClicked = function (digit) {
    if ($scope.clearValue) {
        $scope.displayValue = digit;
        $scope.clearValue = false;
    } else {
        $scope.displayValue = $scope.displayValue * 10 + digit;
    }
    $scope.valueB = $scope.displayValue
};

After user clicks a digit button, we want to update displayed value by replacing displayed value with digit, or by increasing displayed value by that digit (it's simple, just scale previous value by the factor of 10 and then add clicked digit). Also we need to remember displayed value as second value for the mathematical operation.

• Function to handle operation button click:

$scope.operationClicked = function (operation) {
    $scope.selectedOperation = operation;
    $scope.valueA = $scope.displayValue;
    $scope.valueB = $scope.displayValue;
    $scope.clearValue = true;
};

When user clicks operation button we simply want to remember clicked operation, and assign currently displayed value as both values for mathematical operation. Also we need to set clearValue flag, so when user clicks on digit button, the displayed value will be replaced by selected digit, not increased by it.

• Function to handle equal sign button click:

$scope.compute = function () {
    if($scope.selectedOperation != null) {
        $scope.displayValue = Math.floor(
                       $scope.selectedOperation($scope.valueA, $scope.valueB));
        $scope.clearValue = true;
        $scope.valueA = $scope.displayValue;
    }
}

The last function main responsibility is to calculate a result if an operation is selected (assigned to $scope.selectedOperation field). It is done by simple call of remembered function. Also clearValue flag is set and a computation result is remembered as first value of new operation.

Summary
This is all, now we have a fully functional calculator for internet browsers.
As you can see AngularJS is an easy to use (at least for an online calculator) and quite powerful framework for JavaScript application development. It brings a new way to bind an application state with html based view layer, that greatly simplifies creation of JavaScript applications.

The complete source code of this calculator is available at github.com.

Faking System Clock with metaprogramming pattern in Scala

Tomasz Nurkiewicz has written an article Fake system clock pattern in Scala with implicit parameters on his blog. The problem he addresses is that sometimes you require to test your business code against a given date, ie. your system should behave differently on the weekends.

Obviously this will be impossible (or very hard) to handle if a programmers would directly use new Date(), System.curentTimeMills() or some similar construct provided by JVM. So Tomasz proposed an application wide Clock trait that is kind of proxy to Joda Time:

import org.joda.time.{DateTime, Instant}
 
trait Clock {
  def now(): Instant
  def dateNow(): DateTime
}

With the default implementation:

import org.joda.time.{Instant, DateTime}
 
object SystemClock extends Clock {
  def now() = Instant.now()
  def dateNow() = DateTime.now()
}

I like this approach very much, because it provides a clean way to grab the current date, and it decouples us from specific Time library (Joda Time in this case). It is quite obvious how programmer should grab the current system time:

val currentTime = SystemClock.now

Now let's back to initial problem, how to pass a specific time if we want to test our code? I propose to use the method I've described in Metaprogramming in Scala with higher order functions article.


First Step - Create companion object for clock
Let's create a companion object Clock that will provide, to a programmer, a kind of proxy to default clock implementation, so the programmer won't have to use SystemClock directly:

object Clock {
  private val clockInstance: Clock = SystemClock
  def now() = clockInstance.now()
  def dateNow() = clockInstance.dateNow()
}

And now the usage of our Clock has been simplified to this:

val currentTime = Clock.now

Second step - Allow to change clock instance
To solve our problem of testing against specific time we would like to allow programmer to change the clock instance that is used in Clock companion object:

object Clock {
  private var clockInstance: Clock = SystemClock
  def now() = clockInstance.now()
  def dateNow() = clockInstance.dateNow()
 
  def changeClock(newClock:Clock) {
    clockInstance = newClock
  }
}

Now the programmer can switch the instance of Clock in the following way:

//alternative Clock implementation
class FakeClock(fixed: DateTime) extends Clock {
  def now() = fixed.toInstant
  def dateNow() = fixed
}

//change of clock that is used
Clock.changeClock(new FakeClock(new DateTime(2013, 7, 15, 0, 0, DateTimeZone.UTC)))
//code to be tested
...
val currentTime = Clock.now
...
//revert the clock change
Clock.changeClock(SystemClock)

As you can see we allowed a programmer to force the Clock object to return specific date instead of current system date. To use it in tests a programmer only have to call Clock.changeClock function before tested code, and a tested code will "see" that current time is different.  


Final step - change Clock instance by declaration
In the final step we'll change our Clock.changeClock function to higher order function so it's usage will be much nicer and it will allow to change clock instance temporarily only.

object Clock {
  private var clockInstance: Clock = SystemClock
  def now() = clockInstance.now()
  def dateNow() = clockInstance.dateNow()
 
  def changeClock(newClock:Clock)(codeBlock: => Unit) {
  val oldClock = Clock.clockInstance
    clockInstance = newClock
    codeBlock
    clockInstance = oldClock
  }
}

So now to change a clock instance a programmer could write something like this:

import Clock.changeClock

// changing clock instance only for the  given block of code
changeClock(new FakeClock(new DateTime(2012, 2, 2, 0, 0, DateTimeZone.UTC))) {
  ...
  val currentTime = Clock.now
  ...
}

Usage example
This is a little more complicated usage example, but it's a nice way to demonstrate how easy the change of clock is now:

object ClockTest {

  import Clock.changeClock

  def testedMethod() {
    println(Clock.dateNow())
  }

  def main(args: Array[String]) {
    testedMethod()

    changeClock(new FakeClock(new DateTime(2013, 7, 15, 0, 0, DateTimeZone.UTC))) {

      testedMethod()

        changeClock(new FakeClock(new DateTime(2012, 2, 2, 0, 0, DateTimeZone.UTC))) {
          testedMethod()
        }

      testedMethod()
    }

    testedMethod()
  }

}

And the output of this simple program would be this (let's assume that now is 30th of July 2013):

2013-07-30T19:02:38.501+02:00
2013-07-15T00:00:00.000Z
2012-02-02T00:00:00.000Z
2013-07-15T00:00:00.000Z
2013-07-30T19:02:38.594+02:00

As you can see this worked very well even for nested blocks of changeClock.


The complete implementation is available on gist.github.com.


Previous article: Metaprogramming in Scala with higher order functions

Metaprogramming in Scala with higher order functions

Scala is very flexible programming language. In this article I would like to propose some usage pattern for higher order functions. This pattern could help us to create a convenient way to handle multiple situations such as:
- monitoring code performance
- exception logging
- executing commands in separate Thread
- transaction handling
- try with resource
- environment changing

Below I'm giving an usage examples and sample implementations for every of this cases.

Higher order function as meta-data
Basically higher order function is a function that takes another function as a parameter. In the following example calculate is a higher order function that takes function sum as parameter :

scala> def sum(a:Int, b:Int) = a + b
scala> def calculate(a:Int, b:Int, operation: (Int, Int) => Int) = operation(a, b)
scala> calculate(5, 3, sum)
res1: Int = 8

We will leverage the fact that we can pass a function that does not take any parameters, and does return nothing. That means that we'll simply pass a code block as a parameter to our function. This way we can do this:

//implementation
def doItTwice(codeBlock: => Unit) {
  codeBlock
  codeBlock
}
//usage with full syntax
doItTwice({
  println("Hello!")
})

and to do this even nicer we can skip parentheses in doItTwice call, so it will look this way:

//proper usage with abbreviated syntax
doItTwice {
  println("Hello!")
}

the result is simple to predict:

Hello!
Hello!

Doesn't it feel like we have extended language we are using? Now it's almost like adding simple metadata to our application.
This feature can be leveraged to improve our programs, but before that we have to use another Scala feature called currying. It allows us to define multiple parameters lists for a function. Thanks to that, we will be able to pass another parameters to our higher function. Will take a closer look at this by introducing new loop implementation.

Simple loop
Let's assume we want to define a simple way to loop our program for given number of times. And we want to do this as simple as possible. In example we would like to use it in this way:

//sample usage
repeat(5) {
  println("Cool loop")
}

Now we should be able to do this easily. This is the solution:

//implementation
def repeat(times: Int)(codeBlock: => Unit) {
  var i = 0
  while (i < times) {
    codeBlock
    i += 1
  }
}

Thanks to the currying we could have passed times parameter and still be able to use abbreviated syntax when passing a code block. This is very simple usage of this pattern, but it uses every feature of Scala we need. Let's go to more serious problem.

Execution time logging
Next case. Let's assume that we have some complex block of code, and we have to monitor it's execution time. So the nice way to do this would be like that:

//sample usage
logExecutionTime("My complex operations") {
  complexOperation1
  complexOperation2
  complexOperation3
}

with the result looking like this:

Execution time of "My complex operations" was 125 mills

To achieve this we can simply define logExecutionTime function this way:

//implementation
def logExecutionTime(name: String)(codeBlock: => Unit) {
  val start = System.currentTimeMillis()
  codeBlock
  val end = System.currentTimeMillis()
  println("Execution time of \""+ name +"\" was "+ (end - start)+" mills")
}

Btw. I have proposed a little more complex solution to measure time execution and described it in Neat and simple way to measure code performance in Scala article.

Exception logging
Now let's think about exceptions. There are many cases when you need just output the information about exception that occurred, but your application or maybe container of the application will handle that exception somewhere else. In the following example logExceptions will catch exception thrown from inner code block, write it out to a console, and than rethrow it, so the program can handle it:

//sample usage
logExceptions {
  operationThatMightCauseException
}

And this is simple implementation of it.

//sample usage
def logExceptions(codeBlock: => Unit) {
  try {
    codeBlock
  } catch {
    case e:Exception => {
      e.printStackTrace()
      throw e
    }
  }
}

I hope that now you've got feeling that this approach can be treated as metaprogramming, in this case logException can be treated as an annotation to a given code block. And, in my humble opinion, this is very nice. So let's go to further possible usages of this pattern.

Execute commands in separate Thread
So maybe we would like to execute some commands separately to our main program thread, ie. to send a message to external server. It have to be executed in separate thread, so it wouldn't block our application because of network delays. So that might be the way we would like to program it:

//possible usage
fireAndForget {
  sendMessageViaHttp
}

In the simplest solution we'll just create a new thread and run a given block of code in that thread:

//implementation
def fireAndForget(codeBlock: => Unit) {
  new Thread(new Runnable {
    def run() {
      codeBlock
    }
  }).start()
}

Transaction handling
Now let's think about a common pattern in enterprise application - a transaction handling in database communication. In simplest situation you will to start a transaction, then execute your database commands and in the end you will commit the transaction or rollback it if something went wrong. We would like to help a programmer to do this multiple of times, so it would be nice if he could simply declare a transaction around the database commands. In the example I've assumed that our database commection is represented by simple trait with three methods to control a transaction:

trait Connection {
  def beginTransaction()
  def commit()
  def rollback()
}

And now the programmer should be able to program like that:

//possible usage
transaction(postgresConnection) {
  insertRecords
  updateOtherRecords
}

The transaction is responsible for creating a transaction, executing commands and commiting or rollbacking transaction (on the exception occurrence). So it's implementation could look like that:

//implementation
def doInTransaction(connection: Connection)(codeBlock: => Unit) {
  connection.beginTransaction()
  try {
    codeBlock
    connection.commit()
  } catch {
    case e:Exception => {
      connection.rollback()
      throw e
    }
  }
}

Try with resource or simple resource handling, ie. file reading
Java 7 introduced try with resources statement that facilitated usage of external resources that have to be handled with care. In example they have to be properly closed to be reused. Before that resources handling was error prone because programmers often forgot to close the resource. So let's look how we could simplify it in Scala with the example of file reading. One of the easiest way to read file could be like that:

//possible usage
readFile("file.txt") {reader =>
  println("First line " + reader.readLine())
  println("Second line " + reader.readLine())
  println("Third line " + reader.readLine())
}

And the fileRead implementation should properly open a file, and at the end close it properly. That could be implemented in this way:

//implementation
def readFile(filename:String)(codeBlock: BufferedReader => Unit) {
  val reader = new BufferedReader(new FileReader((filename)))
  try {
    codeBlock(reader)
  } finally {
     if(reader != null) {
       reader.close()
     }
  }
}

Environment change
For the last example let's assume that we have a parts of application that depend on some specific environment configuration. What if we have to change it temporarily to do something specific, for example for test purposes.
So let's assume that our environment is accessible for us by the singleton object that holds String to String map:

object Environment {
  var environment = Map[String, String]()
}

And for our example let's assume that our environment contains an entry that holds ip address for some name server: "nameServer" -> "192.168.10.210". If we would like to alternate it temporarily to redirect request to localhost we would like to do something like that:

//possible usage
println(Environment.environment("nameServer"))

changeEnvironment("nameServer" -> "127.0.0.1") {
  println(Environment.environment("nameServer"))
}

println(Environment.environment("nameServer"))

and that should give us that output:

192.168.10.210
127.0.0.1
192.168.10.210

To achive this, one possible implementation of changeEnvironment could look like this:

//implementation
  def changeEnvironment(change: (String, String))(codeBlock: => Unit) {
    val oldEnvironment = Environment.environment
    Environment.environment = Environment.environment + change
    codeBlock
    Environment.environment = oldEnvironment
  }

The last example was inspired by Tomasz Nurkiewicz in his blog article Fake system clock pattern in Scala with implicit parameters. He proposed a solution for switching a Clock object, that is used within application, for the purpose of test that might require testing against given date. In the comment to that article I've proposed a different solution, than given by Tomasz, based on environment changing described above.

Conclusion
I hope I've given you an idea that Scala can be used for metaprogramming with very simple constructs. When we'll use it properly, it can easily separate a business logic of an application from technical details of the implementation and this will greatly improve the way the source code can be read and managed.

Previous article: Neat and simple way to measure code performance in Scala

Neat and simple way to measure code performance in Scala

When we write a source code we often have to be aware of the performace of our solution. The easiest way to achieve this is by measuring duration of the execution by taking the system time before and after our block code, ie.

Where is the problem?

val startTime = System.nanoTime
timeConsumingOperations()
val endTime = System.nanoTime

println("Operations took " + (endTime - startTime) + " nano seconds")

This is most basic approach that can be used in the simplest cases. But what if we want to measure times of multiple different operations? This simple solution would become a little complex and harder to maintain, ie.

val startTime = System.nanoTime
operation1()
val middleTime1 = System.nanoTime
operation2()
val middleTime2 = System.nanoTime
operation3()
val endTime = System.nanoTime

println("Operation1 took " + (middleTime1 - startTime) + " ns")
println("Operation2 took " + (middleTime2 - middleTime1) + " ns")
println("Operation3 took " + (endTime - middleTime2) + " ns")

That code is becoming hard to read, maintain and, in my opinion the worst, it almost hides our business code.
Now let's compilcate it even more by assuming that we need to run those operations multiple times (ie. in a for loop) and we need to measure their entire time of execution. We could try to do something like that:

var operation1Duration = 0L
var operation2Duration = 0L
var operation3Duration = 0L

for(i <- 1 to 10) {
  val startTime = System.nanoTime
  operation1()
  val middleTime1 = System.nanoTime
  operation2()
  val middleTime2 = System.nanoTime
  operation3()
  val endTime = System.nanoTime

  operation1Duration += middleTime1 - startTime
  operation2Duration += middleTime2 - middleTime1
  operation3Duration += endTime - middleTime2
}
println("Operation1 took " + operation1Duration + " ns")
println("Operation2 took " + operation2Duration + " ns")
println("Operation3 took " + operation3Duration + " ns")

And that is an ugly piece of code.

Solution Proposal

I propose a simple solution to that problem, a simple stopwatch. With this stopwatch we can refactor our third case into this:

clearStopwatchResults()

for(i <- 1 to 10) {
  stopwatch("First operation") {
    operation1()
  }
  stopwatch("Second operation") {
    operation2()
  }
  stopwatch("Third operation") {
    operation3()
  }
}

println(stopwatchResults)

And the result of this measurement would be something like this:

Third operation -> 48 ms 355 us 124 ns 
First operation -> 136 ms 219 us 210 ns 
Second operation -> 644 ms 69 us 657 ns

Basic idea for that approach is to create a Stopwatch that can measure execution time of a block of code and store it under given identifier (ie. "First operation"). It will accumulate a time of execution for given identifier, and in the end it will write out the measurement results in a readable format.

Solution Implementation

So here is the implementation of my Stopwatch:

import collection.mutable
import scala.StringBuilder

class Stopwatch {

  private val measurements = mutable.HashMap[Any, Long]()

  def clearResults() {
    measurements.clear()
  }

  def apply(identifier:Any)(codeBlock: => Unit) {
    val start = System.nanoTime
    codeBlock
    val end = System.nanoTime
    val oldValue = measurements.getOrElse(identifier, 0L)
    measurements += identifier -> (oldValue + end - start)    
  }

  def results():String = {
    ResultsFormatter.format(measurements)
  }
}

And there is also a companion object to provide default Stopwatch and convenient methods to use it.

object Stopwatch {
  private val defaultStopwatch = new Stopwatch

  def stopwatch(identifier:Any)(codeBlock: => Unit) {
    defaultStopwatch(identifier)(codeBlock)
  }

  def stopwatchResults() = defaultStopwatch.results()

  def clearStopwatchResults() {
    defaultStopwatch.clearResults()
  }
}

To complete the solution we also need a class to format our measurements results into well formatted String:

object ResultsFormatter {
  def format(measurements: mutable.HashMap[Any, Long]):String = {
    val sb = new StringBuilder
    measurements.foreach(appendResult(sb))
    sb.toString()
  }

  private def appendResult(sb: StringBuilder)(result: (Any, Long)) {
    val identifier = result._1
    val value = result._2
    sb.append(identifier).append(" -> ")

    appendIfNotZero(sb, extractSeconds(value), "s")
    appendIfNotZero(sb, extractMills(value), "ms")
    appendIfNotZero(sb, extractMicro(value), "us")
    appendIfNotZero(sb, extractNano(value), "ns")

    sb.append('\n')
  }

  private def extractNano(value: Long): Long = value % 1000
  private def extractMicro(value: Long) = (value / 1000) % 1000
  private def extractMills(value: Long) = (value / 1000000) % 1000
  private def extractSeconds(value: Long) = value / 1000000000

  private def appendIfNotZero(sb:StringBuilder, value:Long, suffix:String) {
    if (value > 0) {
      sb.append(value).append(" ").append(suffix).append(" ")
    }
  }
}

I have to mention that this is not thread safe implementation and one instance of Stopwatch should be use within single thread.

Implementation description

Stopwatch class
The main point of the implementation is a Map called measurements. It is a mutable HashMap, for higher performance and it is used to map identifier into execution duration.

The Stopwatch class provides three public methods:
- apply(identifier:Any)(codeBlock: => Unit) - This method takes an identifier and a code block that will be measured. It simply calls the codeBlock, calculates how long it took to execute it and in the end it accumulates the result in the measurements map.
I think the method declaration requires a little more explanation. First it uses a feature called currying. For our purpose we can assume that it allows us to define function parameters in multiple parentheses pairs (of course currying is much more and it can be used for other purposes, but this is topic for other aricle) instead of one. Also codeBlock: => Unit part defines a function that takes no parameters, or just a code block surrounded by curly brackets { ... }.
Thanks to that we could call apply method in this way (full syntax):

apply("some computation")({complexComputation()})

or we can omit latter parentheses and write simply:

apply("some computation"){complexComputation()}

We wouldn't be able to do this, in such a nice way, if we would use only one parameters block, ie. apply(identifier:Any, codeBlock: => Unit)
- clearResults() - This method simply clears the measurements map to allow new measurements to be performed.
- result() - Returns a well formatted String representation of measurements result.

As you can see, the core imlpementation of this solution is very clear and simple. Also this is very easy to add new functionalities to this class.


Stopwatch companion object
This companion object is used to increase the ease of using Stopwatch class. It provides default instance of Stopwatch and provides a convenient methods to use it. To use those methods we have to import this object into current namespace by:

import Stopwatch._

This import statement will include all methods from Stopwatch object into current namespace, so we can call it directly, without passing Stopwatch name.


ResultsFormatter class
This class is simpy used to create a well formatted String from Map containing measurement results.

Conclusion

I think that this approach to code performance measurement is well suited for many use cases, when you don't want to use external libraries for microbenchmarking or use of external profilers. Scala is very flexible language that allows us to create simple and very elegant solution for that kind of problems.
Of course my Stopwatch is very simple, and I can imagine many ways to improve it. In example it can be rebuilt to be thread safe, or internal map can be replaced by simple array to increase its performance. But I also think that this is a good point to start for most of the projects.

Next article: Metaprogramming in Scala with higher order functions
Previous article: Scala - Parentheses and Curly Brackets in Anonymous Functions

Scala - Parentheses and Curly Brackets in Anonymous Functions

Scala gives a lot of flexibility in defining anonymous functions, and that might lead to a confussion. Jacek Laskowski asked an interesting question on stackoverflow.com regarding of calling a map method on collection. To summarize it (given a list lst):

Why lst map {c:Char => 1} and lst map ((c:Char) => 1) work fine, but lst map (c:Char => 1) gives us compilation error:

 error: identifier expected but integer literal found.
       lst map (c:Char => 1)

To answer this question we should look into Scala Language Specification, into part 6.23 Anonymous Functions.There is a description how anonymous function can be defined:

Expr ::= (Bindings | [‘implicit’] id | ‘_’) ‘=>’ Expr
ResultExpr ::= (Bindings | ([‘implicit’] id | ‘_’) ‘:’ CompoundType) ‘=>’ Block
Bindings ::= ‘(’ Binding {‘,’ Binding} ‘)’
Binding ::= (id | ‘_’) [‘:’ Type]

As you can see Bindings requires to be placed inside two surrounding parentheses. So if anonymous function defines the type of the parameter, as in our example, it has to be defined in this way:

(c:Char) => 1

And the call to map should look like that:

lst map((c:Char) => 1)

Also in the same part of reference documentation we can find:

If an anonymous function (x: T) => e with a single typed parameter appears as the result expression of a block, it can be abbreviated to x: T => e. 

So if anonymous function is defied as last expression in a code block, and has exacly one parameter, you can use abbreviated syntax, without parenthesis around c:Char, to define anonymous function. So, in our example, we can write c:Char => 1, but only when we place it inside a code block {c:Char => 1}. And we can call map function this way:

lst map({c:Char => 1})

or with abbreviated syntax without parenthesis:

lst map {c:Char => 1}

And that explains main question why lst map {c:Char => 1} is legal, and lst map (c:Char => 1) is not.

This is summarized in changelog at the end of the documentation (Changes in Version 2.1.7 (19-Jul-2006)):

Closure Syntax

The syntax of closures has been slightly restricted (§6.23). The form

x: T => E

is valid only when enclosed in braces, i.e. { x: T => E }. The following is illegal, because it might be read as the value x typed with the type T => E:

val f = x: T => E

Legal alternatives are:

val f = { x: T => E }
val f = (x: T) => E

Another way to specify anonymous functions:

If we look closer at specification we can see that it allows us to use another way to define anonymous function:

Expr ::= (Bindings | [‘implicit’] id | ‘_’) ‘=>’ Expr

We can see that we can define your anonymous function without parameter binding in those two ways (if we don't need to specify argument type):

lst map (c => 1)
// or
lst map (_ => 1)

I hope that this article clarified how we can declare anonymous functions and it shouldn't cause a confusion any more.

Next article: Neat and simple way to measure code performance in Scala
Previous article: Named and Default parameters inconsistency in Scala

Named and Default parameters inconsistency in Scala

While I was reading Scala in Depth I've run into an interesting problem related to named method parameters and class inheritance. What will happen, when in child class we'll override method and we will change parameters names in this method? How will it change the way that this method should be called? And what about default parameters, will those behave simillary to named parameters? It turns out that they will not behave the same. For this reason inheritance of default parameters may result in difficult to detect errors in your application behavior.

I will start by summarizing ways that Scala gives us to pass parameters to method calls. How we can use named and default parameters which were introduced in Scala 2.8.

Positional parameters (likewise in Java).
Usually parameters are passed to function by passing multiple parameters in the order they have been declared in a function declaration. ie.:

scala> def process(x1:Int, x2:Int) = x1 * 2 + x2

scala> process(2, 5)
res0: Int = 9

Named parameters.
If we need to change the order of parameters in function call, or we want to improve readability of function call, or we want to pass only some of the parameters (if function allows that), we can use named parameters. ie.:

scala> def process(x1:Int, x2:Int) = x1 * 2 + x2

// passing parameters without change in ordering
scala> process(x1 = 2, x2 = 5) 
res1: Int = 9 

// passing parameters with change in ordering
scala> process(x2 = 5, x1 = 2) 
res2: Int = 9

It is also possible to call a function by combining positional parameters with named parameters. But in this case it is required that named parameters (if we change ordering of passed parameters) should be passed after positional parameters. ie.:

// some parameters with name
scala> process(2, x2 = 5) 
res3: Int = 9 

// first parameter named, BUT ordering was not changed
scala> process(x1 = 2, 5) 
res4: Int = 9 

// first parameter named, AND ordering was changed
scala> process(x2 = 5, 2) 
<console>:9: error: positional after named argument.
              process(x2 = 5, 2)
                              ^

Default parameters.
If we want allow a user of our function, not to pass all of the parameters, we can define, in a function declaration, a value that will be assigned to a parameter, if that parameter won't be passed in a function call. ie.:

scala> def sum(x1:Int, x2:Int, x3:Int = 0) = x1 + x2 + x3 
 
scala> sum(1, 2, 3)
res5: Int = 6 
 
scala> sum(1, 2)
res6: Int = 3

It is worth to notice, that default parameters don't have to be declared at the end of the parameters list. In that case the only way to call a function without passing theirs value is to use named parameters:

scala> def sum(x1:Int, x2:Int = 0, x3:Int) = x1 + x2 + x3 
 
// only to parameters have been passed
scala> sum(1, 3) 
<console>:9: error: not enough arguments for method sum: (x1: Int, x2: Int, x3: Int)Int.
Unspecified value parameter x3.
              sum(1, 3) 
 
// defined parameters were passed by name
scala> sum(x1 = 1, x3 = 3) 
res7: Int = 4

Named parameters and class inheritance.
Let's check how named parameters behave in the case of class inheritance and method overwriting. Let us look onto those example classes:

class Calculator {
  def process(x1:Int, x2:Int) = x1 * 2 + x2
}

class BrokenCalculator extends Calculator {
  override def process(a:Int, b:Int) = super.process(a, b) + 1
}

It's important to notice that parameter names of method process has been channged from x1 and x2 to a and b.
In the next step let's create instances of those classes, but in the case of BrokenCalculator instances we will assign them to references of different types:

val calculator = new Calculator
val brokenCalculator = new BrokenCalculator
val brokenCalculatorAsCalculator:Calculator = new BrokenCalculator

Does assigning of BrokenCalculator to reference of type Calculator have an influance on method behavior? It turns out that it depends on the way how the parameters are passed:

scala> calculator.process(2, 5)
res8: Int = 9
scala> brokenCalculator.process(2, 5)
res9: Int = 10
scala> brokenCalculatorAsCalculator.process(2, 5)
res10: Int = 10

In the case when we passed parameters as positional parameters all of the calls depends on the class of the instatiated object, therefore brokenCalculator and brokenCalculatorAsCalculator have behaved exacly the same.
What if we want to use named parameters in method call?

scala> calculator.process(x2 = 5, x1 = 2)
res11: Int = 9 
 
// parameter passed with the names from Calculator class
scala> brokenCalculator.sum(x2 = 5, x1 = 2)
<console>:11: error: value sum is not a member of BrokenCalculator
              brokenCalculator.sum(x2 = 5, x1 = 2)
                                       ^ 
 
scala> brokenCalculator.process(b = 5, a = 2)
res12: Int = 10 
 
// parameter passed with the names from BrokenCalculator class
scala> brokenCalculatorAsCalculator.sum(b = 5, a = 2)
<console>:11: error: value sum is not a member of Calculator
              brokenCalculatorAsCalculator.sum(b = 5, a = 2)
                                           ^ 
 
scala> brokenCalculatorAsCalculator.process(x2 = 5, x1 = 2)
res13: Int = 10

In this case, as you can see, it is important what reference type we are using. In our example objects calculator and brokenCalculatorAsCalculator required parameter names x1 and x2. When we've tried to pass the names a and b we've got compilation error. Analogous in the case of brokenCalculator object we had to use names a and b, and when we've tried to use x1 and x2 we've also got compilation error.

I think that for proper use of named parameters we have to assume that method's contract (the way how method can be called) is determined by the type of reference we use, and this allows compiler to verify the correctness of a method call.

Default parameters and class inheritance.
Let's now change our classes, by defining a default parameter values. In the case of BrokenCalculator we'll change default value of x2 parameter:

class Calculator {
  def process(x1:Int, x2:Int = 0) = x1 * 2 + x2
}

class BrokenCalculator extends Calculator {
  override def process(x1:Int, x2:Int = 1) = super.process(x1, x2)
}

Now let's check how method behavior depends on object type and reference type that it is assigned to:

scala> calculator.process(2)
res14: Int = 4 // default value 0
scala> brokenCalculator.process(2)
res15: Int = 5 // default value 1
scala> brokenCalculatorAsCalculator.process(2)
res16: Int = 5 // default value 1

Those results are quite surprising (!), it seems that if a child class changes the default value of a parameter than default values of parameters are indendent of the reference type. During the call of brokenCalculatorAsCalculator parameter x2 had been assigned default value of 1, although the contract from Calculator class defined a default value of 0. I think that this might cause problems, especially because IDE (in my case IntelliJ IDEA) shows to a developer that default value of x2 in the call of brokenCalculatorAsCalculator is 0!

One more case left. What if BrokenCalculator class won't declare any default value for x2 parameter?

class BrokenCalculator extends Calculator {
  override def process(x1:Int, x2:Int) = super.process(x1, x2)
}

Can we now call the process method and pass it only 1 parameter?

scala> calculator.process(2)
res17: Int = 4
scala> brokenCalculator.process(2)
res18: Int = 4
scala> brokenCalculatorAsCalculator.process(2)
res19: Int = 4

Yes we can! In this case BrokenCalculator has inherited default value of x2 parameter, so if child class doesn't define default parameter value, this value is inherited from parent class.

By this example you can see huge inconsistency in Scala design. What if some programmer will use the Calculator reference? By looking at method defined in Calculator class he cannot know the default parameter value! He has to look into concrete implementation of object he will have. But this is not always possible.

So you have to remember that child class always inherits default values of parameters and it can always change them. And when you call the method you need to know the default values defined in concrete class, not only in reference type you are using.

Next article: Scala - Parentheses and Curly Brackets in Anonymous Functions
Previous article: List sorting in Scala