Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

Staged builder through interfaces

Staged builder through interfaces splits object construction into typed steps. Each stage-transition method returns the next stage's interface, so an ordinary call chain exposes `build()` only after the required inputs have been supplied. This does not replace runtime validation of those inputs.

Version: Java SE 21; repository runtime, production runtime not attested

Syntax

Start builder() → Start.host(String) : PortStep → PortStep.port(int) : Ready → Ready.build() : Endpoint

Staged builder through interfaces is a design pattern, not a separate Java language construct. Interfaces describe the available operations at each stage. A method's return type guides the caller to the next stage; the implementation can be a single object implementing all stage interfaces.

In the example, builder() returns Start, host(String) returns PortStep, and port(int) returns Ready. Only Ready declares build(). Consequently, builder().build() does not compile, whereas builder().host("localhost").port(8080).build() creates an Endpoint. An ordinary fluent builder supports chained calls, but returning this alone does not enforce this ordering.

The types enforce call order here, not argument validity. The methods still check for a blank host and the range of port. The protection applies when using the declared stage types: explicit casts can bypass the intended path because the object implements every stage. Therefore, build() also checks that required values are present.

The private implementation hides details, but the mutable builder is not intended for sharing between threads. Retained references to earlier stages can still modify it; stages are not consumed exactly once. The resulting Endpoint stores its own final fields. Use this pattern for a few meaningful steps; many combinations of required fields can substantially increase the number of interfaces.

Examples

public final class Main {
    public interface Start {
        PortStep host(String host);
    }

    public interface PortStep {
        Ready port(int port);
    }

    public interface Ready {
        Endpoint build();
    }

    public static final class Endpoint {
        private final String host;
        private final int port;

        private Endpoint(String host, int port) {
            this.host = host;
            this.port = port;
        }

        @Override
        public String toString() {
            return host + ":" + port;
        }
    }

    private static final class Builder implements Start, PortStep, Ready {
        private String host;
        private int port;

        @Override
        public PortStep host(String host) {
            if (host == null || host.isBlank()) {
                throw new IllegalArgumentException("host must not be blank");
            }
            this.host = host;
            return this;
        }

        @Override
        public Ready port(int port) {
            if (port < 1 || port > 65535) {
                throw new IllegalArgumentException("port out of range");
            }
            this.port = port;
            return this;
        }

        @Override
        public Endpoint build() {
            if (host == null || port == 0) {
                throw new IllegalStateException("missing required values");
            }
            return new Endpoint(host, port);
        }
    }

    public static Start builder() {
        return new Builder();
    }

    public static void main(String[] args) {
        Endpoint endpoint = builder().host("localhost").port(8080).build();
        System.out.println(endpoint);
        // builder().build(); // Does not compile: Start has no build().
    }
}

Result

localhost:8080

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources