Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Understanding the Java Canonical Constructor

Learn how the canonical constructor works in Java records, including explicit and compact constructors, validation, normalization, and defensive copies.

~6 min readJava
#Java#Records#Constructors#Compact Constructors
Diagram of a Java record with components flowing into a canonical constructor, emphasizing validation and field assignment.

Java records use a canonical constructor to initialize every record component. This article explains what the canonical constructor is, how to write it in explicit and compact forms, and when to use it for validation, normalization, and defensive copies.

In Java, the canonical constructor is the constructor of a record that takes one parameter for each record component, in the same order they are declared. When you declare a record, the compiler automatically generates this constructor, which assigns each parameter to the corresponding private final field. You can also define the canonical constructor explicitly to add validation, normalization, or defensive copies. Understanding how it behaves is essential for working with records effectively, especially when you need to enforce invariants on the data they hold.

What the Canonical Constructor Is

A record is a special kind of class designed to carry immutable data. Every record has a list of components, which are the fields you declare in the header. For example:

java
public record Point(int x, int y) {}

Here, x and y are the record components. The compiler generates a constructor that accepts an int for x and an int for y, in that order. That generated constructor is the canonical constructor. It is equivalent to writing:

java
public Point(int x, int y) { this.x = x; this.y = y; }

A record always has a canonical constructor, either written explicitly or generated by the compiler. You can add additional constructors, but they must delegate to the canonical constructor, either directly or through another constructor. This design ensures that every record instance is fully initialized through a single path, which simplifies validation and invariant enforcement.

Declaring an Explicit Canonical Constructor

You can write the canonical constructor yourself when you need to perform checks or transformations before the fields are assigned. The explicit constructor must have the same parameter list as the record components. Inside it, you assign each parameter to its corresponding field, typically after validating the input.

Consider a record that represents a non-empty string:

java
public record Username(String value) { public Username(String value) { if (value == null || value.isBlank()) { throw new IllegalArgumentException("Username must not be blank"); } this.value = value; } }

In this explicit canonical constructor, the validation runs every time a Username is created. If the validation fails, the constructor throws an exception, and no instance is produced. This is the most straightforward way to enforce constraints on record data.

One detail to note: the parameter name in the explicit constructor can be anything, but it is conventional to use the same name as the component. If you use a different name, you must still assign the parameter to the field using this.componentName. The compiler will not allow you to skip assigning any component, because the fields are final and must be set exactly once.

Using a Compact Constructor for Validation

Java records support a compact constructor, which is a shorter form of the canonical constructor. Instead of writing the parameter list again, you write only the body. The parameters are implicitly declared with the same names as the record components, and the fields are assigned automatically at the end of the body. This is ideal for validation because you do not need to repeat the assignment statements.

The same Username record can be written more concisely:

java
public record Username(String value) { public Username { if (value == null || value.isBlank()) { throw new IllegalArgumentException("Username must not be blank"); } } }

In the compact constructor, value refers to the component parameter, not the field. After the body completes, the compiler assigns this.value = value; automatically. This removes boilerplate and reduces the risk of forgetting an assignment, especially when a record has many components.

Compact constructors are the preferred way to add validation to a record. They make the intent clear: the constructor exists to check the incoming data, not to manipulate fields manually. You can also modify the parameter value inside the compact constructor before the implicit assignment, which is useful for normalization.

Normalizing Data in the Canonical Constructor

Beyond validation, the canonical constructor can normalize input before it is stored. For example, you might want to trim a string or convert a value to a canonical form. In a compact constructor, you can reassign the parameter variable, and the implicit assignment will use the updated value.

java
public record Email(String address) { public Email { address = address == null ? "" : address.trim().toLowerCase(); if (!address.matches("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$")) { throw new IllegalArgumentException("Invalid email address"); } } }

Here, the address parameter is trimmed and lowercased before validation. The final stored value is the normalized version. This ensures that all Email instances have a consistent format, which simplifies comparisons and equality checks later.

Normalization in the canonical constructor is particularly useful for value objects that represent domain concepts. Instead of relying on callers to pass well-formed data, the record guarantees it at construction time. This is a form of defensive programming that reduces the chance of invalid state leaking into the rest of the application.

When an Explicit Canonical Constructor Is Necessary

There are situations where a compact constructor is not enough. If you need to perform a defensive copy of a mutable component, you must use an explicit canonical constructor. For example, consider a record that holds an array:

java
public record IntArray(int[] values) { public IntArray(int[] values) { this.values = values.clone(); } }

A compact constructor cannot clone the array because the implicit assignment happens after the body, and you cannot override the assignment. With an explicit constructor, you control exactly what gets stored. This prevents the caller from mutating the array after the record is created, preserving the immutability contract of the record.

The same applies to other mutable objects like ArrayList or Date. If a component is mutable, you should copy it in the canonical constructor to avoid external modifications. This is a key reason to choose an explicit constructor over a compact one, even though the compact form is more convenient for simple validation.

Common Mistakes and Their Consequences

One common mistake is forgetting to assign all fields in an explicit canonical constructor. The compiler will reject the code because the final fields must be initialized. This is a compile-time error, so it is caught early, but it can be confusing if you are not expecting it.

Another mistake is using the component name in the explicit constructor without this. For example:

java
public record Point(int x, int y) { public Point(int x, int y) { x = x; // no effect y = y; // no effect } }

This code does not compile. The parameters shadow the fields, so x = x assigns the parameter to itself. The fields are never assigned, and the compiler rejects the constructor because the final fields are not initialized. Use this.x = x; and this.y = y; instead.

A more subtle issue is throwing an exception from the canonical constructor after some fields have been assigned. Since the object is not fully constructed, it is not visible outside the constructor, so this is safe. However, if you call a non-final method from the constructor, you risk invoking an overridden method on a partially constructed object. Records are final, so this is not a problem for records, but it is worth remembering if you ever refactor to a class.

Runtime Cost and Maintainability

The canonical constructor runs on every record instantiation. Any validation or normalization you add therefore adds a small runtime cost. For most applications, this is negligible, but if you create millions of records in a hot loop, a complex regular expression or a defensive copy could become measurable. You should keep validation logic simple and avoid expensive operations unless they are necessary.

From a maintainability perspective, the canonical constructor centralizes invariant enforcement. Instead of scattering validation across callers or utility methods, you place it in one well-defined location. This makes the record self-contained and reduces the chance of inconsistent data entering the system. It also makes the code easier to review, because the constructor's body clearly states what conditions must hold for a valid instance.

When you need to change validation rules, you modify only the record. Callers do not need to change unless they were relying on invalid data being accepted. This is a significant advantage over plain classes where validation is often duplicated or forgotten.

As a standard Java language feature, records and their canonical constructors are available in Java 16 and later. If you are working on an older Java version, you cannot use records, but you can achieve similar behavior with a class and a private constructor plus static factory methods. The canonical constructor concept is specific to records, so upgrading to a modern Java version is the cleanest path to using it.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.