When writing some Java wrappers around some CGI requests at work, I began with a normal implementation of the builder design pattern, but when I realised I was going to have to do this for about 50 CGI requests, and some of them were nested (CGI requests with query parameters to be sent on to a further CGI request on another machine), and that many of the parameters had interesting constraints, I realised that while the API might be fine, the implementation we were looking at, Josh Bloch's, encouraged repetition of logic.
Anyway, here's an example to get us started. The problem:
Person person = new Person("John", "Jackson", 1979, 11, 10, "AC2193");
We wanted something more like:
Person person = new Person.Builder()
.forename("John")
.surname("Jackson")
.yearOfBirth(1979)
.monthOfBirth(11)
.dateOfBirth(10)
.nationalInsuranceNumber("AC2193").build();
To keep the code short, we'll use a simpler class as an example, a Person consisting of name and age. As you'll see, even this can be large enough to be interesting.
public class Person
{
private final String name;
private final int age;
private Person(Builder builder)
{
this.builder = builder;
}
public static class Builder
{
private String name;
private int age;
public Builder name(String name)
{
this.name = name;
return this;
}
public Builder age(int age)
{
this.age = age;
return this;
}
public Person build()
{
return new Person(this);
}
}
public String getName()
{
return name;
}
public int getAge()
{
return age;
}
}
Even for 2 parameters, this is quite a lot of code, though thus far there isn't really any logic to be duplciated. Now let's look at a really simple constraint, that values cannot be set twice.
The most obvious way of trying this would be to have a boolean alongside each field in the builder, e.g.:
And then in the name(String) and age(int) methods in the Builder you would check the value of that boolean, and throw an IllegalStateException if the boolean had already been set. This is clearly a repetition, which can lead to copy-and-paste errors or just make things hard to change.
In object-orientated programming the usual way of handling this would be to package the field with its boolean in an object and call it, say, MaxOnce. There is a good reason not to go down this path, though, it's difficult to chain MaxOnce with other such types, for example when we want BoundedInt, which prevents values outside a certain range, to work with MaxOnce. So we have a problem that the classes don't work together well. Time for another approach.
It would help if MaxOnce and BoundedInt were more like filters that data gets passed through (or not, if the data is invalid). Enter Parameter.
private final Parameter<String> name = maxOnce("name", null);
private final Parameter<Integer> age = bound(maxOnce("age", 0), 0, Integer.MAX_VALUE);
Notice how bound and maxOnce are chained together in the age parameter It's easy to see how you might write other filters. Here's a largely useless example:
Parameter<Integer> number = not(5, bound(maxOnce(0, "a number from one to ten, but not five"), 1, 10));
For a Parameter that has no default, it might be handy to store the value as an Option, rather than use null, or an empty String or some other sentinel. In another case we want to store the value as a TreeMap (for sparse arrays, mentioned later). So generally we'd like to be able to specify an input type and an output type for a Parameter.
private final Parameter<String, Option<String>> name = maxOnce("name");
private final Parameter<Integer, Option<Integer>> age = bound(maxOnce("age"), 0, Integer.MAX_VALUE);
Note that bound and maxOnce work together for the age parameter, as two filters.
In a few cases, the Parameters that we use are allowed to take multiple indexed values. They are effectively sparse arrays. The Parameter's input type is a Pair<Integer, T> and the output type is a TreeMap<Integer, T> - each incoming Pair gets added to the TreeMap.
private final Parameter<Pair<Integer, String>, TreeMap<Integer, String>> = ...;
We can see that the Parameter is more a declaration than it is an actual value. Then it's quite handy that, actually, Parameter holds no mutable state - we store that in a Map<Parameter, Object> but with slightly better types, wrapped up as a GenericBuilder, and we don't modify that Map, we copy it when we add values, like CopyOnWriteArrayList does in the Java libraries.
Here's the original Person class with a new implementation:
public class Person
{
private final GenericBuilder finalValues;
private static final Parameter<String, Option<String>> nameParam = param("name", "The name of the person", Conversion.<String>identity());
private static final Parameter<Integer, Option<Integer>> ageParam = notNegative(param("age", "The age of the person", Conversion.stringToInt));
private Person(GenericBuilder finalValues)
{
if (realBuider.isDefault(nameParam) || realBuilder.isDefault(ageParam))
throw new IllegalStateException();
this.finalValues = finalValues;
}
public static final class Builder
{
private GenericBuilder realBuilder = new GenericBuilder();
public Builder name(String name)
{
realBuilder = realBuilder.with(nameParam, name);
return this;
}
public Builder age(int age)
{
realBuilder = realBuilder.with(ageParam, age);
return this;
}
public Person build()
{
return new Person(realBuilder);
}
}
public String getName()
{
return finalValues.get(nameParam);
}
public int getAge()
{
return finalValues.get(ageParam);
}
}
There are a couple of extra bells and whistles in the real code, such as building and parsing URLs containing the parameters. I have another post taking this one step further (using Parameters from code generation) in the pipeline.
Previous Topic
