Below is the provider XML document:

<provider>
  <name>Provider Name</name>
  <properties>
    <property>
      <name>address</name>
      <value>194.132.9.45</value>
    </property>
    <property>
      <name>username</name>
      <value>testuser</username>
    </property>
    <property>
      <name>secret</name>
      <value>433395868950ifkjjrif9985848rufj</value>
    </property>
  </properties>
</provider>

And then the Provider class:

package com.tomasmalmsten.example.jaxb;

import java.util.Map;

public class Provider {
  private String name;
  private Map<String, String> properties;

  void setProperties(Map<String, String> properties) {
    this.properties = properties;
  }

  String name() {
    return name;
  }

  Map<String, String> properties() {
    return properties;
  }

  void setName(String name) {
    this.name = name;
  }
}

JAXB sees the properties object in the XML document as a list of property entries. Therefore we need to transform the list into a map. To do this we need three supporting classes. The first one is the class containing the entry, or property:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;

class Property {
  @XmlElement(name = "name")
  private String name;

  @XmlElement(name = "value")
  private String value;

  Property() {
  }

  Property(String name, String value) {
    this.name = name;
    this.value = value;
  }

  String value() {
    return value;
  }

  String name() {
    return name;
  }
}

Next we need the class that contains the list of entries, or the properties:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlElement;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

class Properties {
  @XmlElement(name = "property")
  private List<PropertyEntry> entries = new ArrayList<>();

  List<PropertyEntry> entries() {
    return Collections.unmodifiableList(entries);
  }

  void addEntry(PropertyEntry entry) {
    entries.add(entry);
  }
}

To transform the list into a map we need an XmlAdapter. An XmlAdapter is a class that instructs JAXB on how to marshal and unmarshal an object that does not conform to the JAXB standard. This could for example be a class without a public no args constructor, or as in our case the provider properties map:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.adapters.XmlAdapter;
import java.util.HashMap;
import java.util.Map;

class PropertyAdapter extends XmlAdapter<Properties, Map<String, String>> {

  @Override
  public Map<String, String> unmarshal(Properties in) throws Exception {
    HashMap<String, String> hashMap = new HashMap<>();
    for (PropertyEntry entry : in.entries()) {
      hashMap.put(entry.name(), entry.value());
    }
    return hashMap;
  }

  @Override
  public Properties marshal(Map<String, String> map) throws Exception {
    Properties props = new Properties();
    for (Map.Entry<String, String> entry : map.entrySet()) {
      props.addEntry(new PropertyEntry(entry.getKey(), entry.getValue()));
    }
    return props;
  }

}

Now what is left is to tell JAXB to use the XmlAdaptor when handling the properties field. To do this we use the @XmlJavaTypeAdapter annotation. Below is the fully annotated Provider class:

package com.tomasmalmsten.example.jaxb;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import java.util.Map;

@XmlRootElement(name = "provider")
@XmlAccessorType(XmlAccessType.FIELD)
public class Provider {
  @XmlElement(name = "name")
  private String name;
  @XmlElement(name = "properties")
  @XmlJavaTypeAdapter(PropertyAdapter.class)
  private Map<String, String> properties;

  void setProperties(Map<String, String> properties) {
    this.properties = properties;
  }

  String name() {
    return name;
  }

  Map<String, String> properties() {
    return properties;
  }

  void setName(String name) {
    this.name = name;
  }
}

To make Maven find Java 7 the JAVA_HOME variable is required again. This hasn’t been used for a while since Maven have been able to find Java anyway. But with the switch to 7 Maven still uses Java 6 by default.

I always use .bash_profile to change my environment variables since I tend not to need them else were. It is located in the users home directory (I.E. ~/.bash_profile).

The path to the new Java install is ‘/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home/’. So the complete setting should look like this:

$JAVA_HOME=/Library/Java/JavaVirtualMachines/1.7.0.jdk/Contents/Home/

When this has been configured Maven will use Java 7.

I am very happy to be back and this is in part thanks to my new position. I have left mBlox and joined of Avega Group. Avega Group is a Swedish consultancy firm with a focus on seniority and expertise. This means that I am available as an expert consultant within programming, technical team lead and architecture. Get in contact with Peter Blomsterberg if you are interested.

As I start with coding again I am sure I will find new and interesting things to write about.

Cheers!

A comment from Steven Jeuris about a week ago on my blog made me want to revisit the subject again.

Since I wrote the original article I have leant a lot about creating clean functions that does one thing. And as I replied in to his comment I would not design the code in the original article the same way now.

The key to applying the guidelines in the book is pragmatism. There are a number of benefits from working as is suggested there. I will cover some of them below. But it cannot be followed religiously. It is after all software we are creating, not religion.

Steven Jeuris writes, in his blog on the subject, that a perfectly good way to make code in a function readable is to create blocks with comments. This to me is an anti pattern. There are few reasons to ever create blocks in a function, if they are required it generally indicates that the function is to long. Comments are almost always a bad idea. If a comment is required the block should be put within a function bearing a name that explains what the block does.

Steven Jeuris further writes that new small functions litters the name space of the class. I can see where he is coming from but again I have to disagree. If the name space of a class is littered by explanatory function names then it sounds like the class is to big and needs to be refactored. To me it sounds very much like it does more then one thing.

There is also an interesting side effect to creating smaller more atomic functions that does one thing. It is easier to find commonalities between the other, higher level, functions within the same class, or even related classes. This actually makes it easier to keep the code DRY (Don’t Repeat Yourself).

Another very important factor to keep in mind when working like this is what patterns the rest of the team are used to. The size of functions and the way to work with them are not a one size fits all. If a team is used to procedural code the step to extract till you drop style functions will be really confusing. If, on the other hand, the team is used to atomic, do one thing only, functions it is hell to work with larger functions littered with comments and artificial blocks.

In any case, I know that if I would do the same exercise to day as I did when writing my original article on the subject it would look different, and the original definitely takes a good thing way to far.

The first thing to keep in mind is what a HTTP based REST protocol is and what it is not. It is not a domain, it’s a protocol. It is easy to forget when modelling the domain that it’s representation is only a snapshot view onto it. The REST protocol provides this snapshot view. This makes a tiered architecture fitting, with clear boundaries between presentation, I.E the REST API, domain, and then any other technical aspects such as data storage.

Next thing to keep in mind is: What is REST over HTTP? It’s a way to access resources, or documents. That’s what we do when using the web. We don’t access domain objects. Remembering this helps when thinking about the interface as well. Most of the time when we create enterprise software we create abstract documents representing real life object. For example, when creating an e-commerce system that sells shoes it’s not the shoes that are transitioned through the work flow. It’s documents that represent the shoes or the whereabouts of them. With this frame of mind it’s much simpler to define the REST interface onto the domain.

Then there are the three levels of REST. Resources, verbs and hyper media controls. As described in this article, by Martin Fowler, about the Richardson Maturity Model.

The first level is resources. This is where the document thinking comes in. When thinking about the domain model it is usually pretty simple to see how different states of it can map onto a document representation. This becomes a resource. It could be the result of an operation just as well as the state of an object.

The second level are the HTTP verbs. I used GET, PUT, POST and DELETE in my API.

GET will get the representation of a resource. A key aspect with get is that it can be called any number of times with the exact same result. It has not side effects.

POST and PUT are used to change things. POST is used when a resource is created or modified in such a manner that the resource path changes. One obvious use is when creating a new object that can later be addressed using it’s ID. This returns a response of 201, Created with a location header that points to where the new resource is located. POST is also used if a resource is changed in such a manner that it’s path changes.

An example is if you have a set of products that are accessed based on a category name. When the category name changes the product paths will also change. This kind of side effect requires a POST rather then a PUT. The response is either 200, if it contains a body, or 204 if it does not. In either case the location header needs to be present to point the client to the new location of the resource.

POST is also used for submitting data to a computation. If the API displays a currency converter I would use POST as the method with the amount, the from and the to currencies in the body. Here the response code is 200, the result in the body but it no location header is provided.

PUT is used to modify a resource. What is important here is that resource paths are not allowed to change as a side effect of the modification. It can expose ways to change properties on objects or replacing a whole object as long as the path does not change. Response is usually 204, but if a response body is retuned it’s 200.

DELETE is simply used to remove a resource. Response is almost exclusively 204 since a removed resource have little in the form of content to offer.

The third level is hypermedia controls also referred to as HATEOAS (Hypermedia as the Engine of Application State). Hypermedia controls are links to actions that can be performed on the document. My thinking on what links to provide is to point forward from the current state. The client will be responsible for keeping track of it’s history as well as weather that history is valid traversable. History validity is based on expire headers so don’t forget to provide them in each response.

When defining links I have used the following JSON syntax:

{"links": [
    {"GET": "/uri/to/resource"},
    ...
    {"PUT" : "/uri/to/other/resource"}
]}

This exposes what actions are available on the current resource in an easy manner, using the HTTP verb/method as the key and the path as the value.

I am sure I will have good reason to change and rethink the above above points as I design other APIs in the future but for this application it has worked really well. And each of the above points are important to think about when defining a REST API, weather the conclusions are the same or not.

I am not complaining. I like writing code. But it takes time, especially since it’s only me on the project at the moment.

Thankfully it’s all written in Python so it’s not to verbose, though even Python is verbose when you have to write this amount of repetitive code.

Which is how we come to the value of clean code. The code is slowly transforming by refactoring and transformations. The effect of this is that there is no repetition in production code, it is completely DRY. In tests there is little repetition, this to make the tests document the production code.

The effect of this is that although the upfront cost, before any abstractions had been created, was slightly higher the cost of adding new features now is very small. To create a function that initially required 40 lines of code excluding tests now requires 5 to 10 lines. The test abstractions are so easy to use that it takes next to no time even though some repetition (sequentially calling the same methods in each test method to explain the steps required to use the function) is needed.

The conclusion to this is that the returns of clean code is rather immediate. Many seems to think that the returns are slow and far in the future. I know this to be the opposite. The returns are almost immediate and are currently cutting development time radically. And that is on a code base which has only a couple of thousand lines of production code.

But it has more neatness then this. With a simple option it will also print test coverage for the project: --with-coverage, and if coverage should be calculated base on specific packages then use --cover-package which takes a list of packages to calculate coverage on. This is useful when there are library packages for a virtual env or similar within the same directory as you run nose.

I don’t like to leave lose ends so to ensure that there are no lingering compiled *.pyc files sitting around I run the following script before commit:

#!/bin/sh
#find all .pyc files and remove them
find <source-dir> ... <source-dir> -name '*.pyc' -exec rm {} \;
#Execute tests
nosetests --with-coverage --cover-package=<package>

Where <source-dir> should be replaced with directories where source files are. This is a space delimited list. And <package> is replaced with packages which should have coverage statistics calculated.

When working with python I have found a very nice tool called Clone Digger that helps finding repetitions in code. It is easy to set up and work with and the report is clear and easy to read.

Install it with pip:

pip install clonedigger

When installed it is automatically added to the tool chain. To run it use the following command:

clonedigger package

Package is the directory where the python code is to be found. Clone digger takes a list of packages separated with space. –help will show help on options and configuration.

Clone digger will work it’s way through all files in each package and compare them, both within each package and across package listed in the same invocation. If there is code, such as auto generated code, that is not modifiable, it needs to be removed from the packages added in order for the tool not to analyse them.

It will generate a report looking like the one below to output.html (this is configurable).

Working with tools like this makes it easy to spot where new abstractions should be added to remove code duplication. Both in test and production code. Where ever repetition is found which does not fill an important documenting function (which is sometimes the case in tests) it is easy to spot where and how a method should be added to pull the functionality together. It will also help in naming such methods. There are of cause some false positives. Especially in the test code where method bodies are often descriptive rather then dry. But even here it helps to find common assertions which can be pulled up and made into new descriptive methods. This becomes especially valuable when working with given-when-then in tests.

Lets start with looking at the two strategies available. SQLAlchemy offers a Data Mapper out of the box. It is also possible to use an Active Record approach by using the Declarative Base ORM extension.

The Active Record approach is a very attractive way of working. It adds metadata to the domain objects that tells the engine how to save them to the database. It’s quick and easy to use and avoids extra classes or configurations that handles the database mapping. It’s a perfect fit for most web applications. The main drawback is that storage logic is tightly coupled with the domain objects. This can make the domain difficult to work with over time. It also means that any changes required in storage logic will force changes into the domain breaking the Single Responsibility Principle. Active Record will also prove very costly if the project finds that a change of storage technology would be beneficial. A not to unlikely event with such a variation in industry strength storage technologies available.

Data Mappers provides high decoupling by keeping all meta data for mapping objects to tables separate from the domain. The mapping can be placed in its own module which makes it easy to divide the domain into coherent modules with no need to cater for storage concerns. It also makes it easy to model more advanced relational concepts in a large database. Since it allows for complete separation of concerns for domain and data access it is also easy to change or swap out the data storage technology completely without any needs to change the domain. It does however increase the complexity of the application since it adds an extra module/package.

If the project in question is going to use a clean implementation of Domain Driven Design only the Data Mapper works. It is also the only possible choice if it is likely that the project will be changing storage technology.

If, however, the project is a traditional web application with a domain model that is simple or close to non-existing then Active Record is a good choice. It will provide more speed of development. Making a clear distinction between domain logic tests and data access tests will make it easier to later extract data access out into Data Mappers if needed.

It is based on the Embury’s 8:2:1 formula but instead of using simple syrup I used Monin’s Vanilla Syrup. This makes for a lovely smooth vanilla infused daiquiri.

Recipe:
2 shots Ron Barceló rum
1/2 shot lime juice
1/4 shot Monin Vanilla syrup

Pour all ingredients into shaker. Shake well, and if you are using big blocks of ice allow to dilute a little extra. Fine strain into cocktail glas and garnish with a lime wedge on the rim.

Enjoy!