The Canonical Constructor

Imagine a FullName class that normally stores two pieces of information: a first name and a last name. Most people have both, so the usual way to create an object takes both values. But some people go by only one name, and a program that models people should still be able to represent them. This is the problem additional constructors solve. They give a class more than one way to be built, each suited to a different kind of input.

In this article you will trace a small constructor chain step by step, predict which fields end up holding which values, and then see how the main constructor can be customized to reject bad input. Try to reason about each prediction yourself before reading the explanation that follows it.

The two kinds of constructor differ in what they accept, and in who does the final setting of the fields. The canonical constructor takes the full set of values and assigns them to the fields. An additional constructor takes a different set of inputs, and its job is to get those inputs into a form the canonical constructor can use. In the FullName example, the canonical constructor takes two parameters, a first name and a last name, while the additional constructor takes only one.

Suppose a caller writes new FullName('Ada'). The one-parameter constructor runs first, with onlyName holding the value 'Ada'. Its only statement is this(onlyName, null). The keyword this followed by parentheses refers to a constructor of the same class rather than to a method or a field. Here it selects the two-parameter constructor, which is the canonical one in this class, and passes it two arguments: 'Ada' and null.

Control now moves to the canonical constructor. That constructor sets the firstName field to the value of its first argument, which is 'Ada', and the lastName field to its second argument, which is null. When it finishes, control returns to the one-parameter constructor, which has nothing left to do. The result is an object whose firstName is 'Ada' and whose lastName is null.

Notice that the one-parameter constructor never assigns either field directly. It delegates that assignment entirely to the canonical constructor. This is why the pattern is called constructor chaining: one constructor calls another, which in turn may do the real work. Delegating keeps the field assignments in one place, which reduces duplication and makes later changes safer. If the canonical constructor later needs to set a field differently, that change is made once, and every additional constructor that chains to it benefits.

Now compare the one-name route with the two-name route. A caller who supplies both a first and last name uses the canonical constructor directly, so no chaining happens at all. Both routes end at the same place, the canonical constructor, which means both produce objects that are set up the same way. The only difference is how the arguments reached it.

A canonical constructor can be extended with extra code. The customized form omits the parameter list. In the source's syntax, the definition is written as public FullName followed by a block of code, with no parentheses after the class name. This can look as though the parameters have disappeared, but they have not. A call to the constructor still requires two arguments, and those arguments still initialize firstName and lastName.

Parameters initialize the fields before the constructor's own code is executed. This ordering explains why validation in the body works. The arguments are first used to fill the fields, and only then does the constructor's extra code run. So when the check tests whether firstName is null, the value it tests is the one the caller supplied.

The diagram reads as a sequence. The call supplies values, the values fill the fields, the body performs its extra work, and only then is the object handed back. The body is the only place where you can enforce rules about what the fields contain, and it runs after the fields have been filled.

Consider two calls to the customized FullName record. In the first, new FullName(null, 'Lovelace') is called. The fields are initialized first, so firstName receives null. The check then tests firstName, finds it null, and the throw statement runs. The failure happens inside the constructor body, during the construction call itself. No object is returned to the caller.

In the second call, only the first argument changes, to new FullName('Ada', 'Lovelace'). The fields are initialized the same way, but the test is false, the throw statement is skipped, and the constructor completes normally. The same code path produces both outcomes, and the difference comes entirely from the value the caller passed in.