Builder

Código en:JavaC#PythonJavaScript

En resumen: Builder arma un objeto complejo paso a paso, con un nombre para cada campo, lo valida en build() y devuelve un objeto terminado e inmutable.

Problema

Nueve parámetros y dos palabras intercambiadas

La tienda envía un correo cuando un pedido sale. El correo tiene nueve campos: a quién va, la dirección para las respuestas, el asunto, el texto, una copia, una copia oculta, un adjunto, si es importante y si se rastrea su apertura.

class Email {
    private final String to;
    private final String replyTo;
    private final String subject;
    private final String body;
    private final String cc;
    private final String bcc;
    private final String attachment;
    private final boolean highPriority;
    private final boolean trackOpens;

    public Email(String to, String replyTo, String subject, String body, String cc,
                 String bcc, String attachment, boolean highPriority, boolean trackOpens) {
        this.to = to;
        this.replyTo = replyTo;
        this.subject = subject;
        this.body = body;
        this.cc = cc;
        this.bcc = bcc;
        this.attachment = attachment;
        this.highPriority = highPriority;
        this.trackOpens = trackOpens;
    }

    public void send() {
        System.out.println("Para: " + to);
        if (replyTo != null) {
            System.out.println("Responder a: " + replyTo);
        }
        System.out.println("Asunto: " + subject);
        if (attachment != null) {
            System.out.println("Adjunto: " + attachment);
        }
        if (highPriority) {
            System.out.println("Prioridad alta");
        }
    }
}

Así se envía la confirmación del pedido 1042:

Email email = new Email("support@shop.example", "maria@example.com", "El pedido 1042 ha sido enviado",
        "Tu paquete está en camino.", null, null, "invoice-1042.pdf", true, false);
email.send();

Salida

Para: support@shop.example
Responder a: maria@example.com
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Prioridad alta

El correo fue al soporte de la tienda, y María no recibió nada. Los dos primeros argumentos están intercambiados. Los dos son texto, así que el compilador no tiene forma de saberlo. ¿Y cuál es true y cuál false al final? Para averiguarlo, cuentas posiciones en el constructor. Dos null guardan el lugar de campos que este correo no tiene.

Cada campo nuevo, digamos el idioma del correo, cambia el constructor y cada lugar que lo llama.

La idea

Builder: por nombre, por pasos, con comprobación

El objeto no se crea con una llamada de nueve posiciones, sino por pasos, cada uno con un nombre: .to(…), .subject(…). Los pasos van a un objeto aparte, el builder. Él reúne los valores, y al final build():

• comprueba los campos obligatorios (aquí: destinatario, asunto y texto) y lanza una excepción si falta alguno;
• crea un objeto inmutable: después el correo ya no puede cambiar.

Este es el patrón Builder. Los papeles:

• el producto: Email, inmutable, con un constructor privado, así que no hay otra forma de crear uno;
• el builder: Email.Builder, con un método para cada campo. El método devuelve el propio builder, así que las llamadas se alinean una tras otra en una cadena;
• build(): el único lugar donde se comprueba y se crea el producto.

Míralo

La cadena y build()

class Email {
    private final String to;
    private final String replyTo;
    private final String subject;
    private final String body;
    private final String cc;
    private final String bcc;
    private final String attachment;
    private final boolean highPriority;
    private final boolean trackOpens;

    private Email(Builder b) {
        to = b.to;
        replyTo = b.replyTo;
        subject = b.subject;
        body = b.body;
        cc = b.cc;
        bcc = b.bcc;
        attachment = b.attachment;
        highPriority = b.highPriority;
        trackOpens = b.trackOpens;
    }

    public boolean highPriority() {
        return highPriority;
    }

    public void send() {
        System.out.println("Para: " + to);
        if (replyTo != null) {
            System.out.println("Responder a: " + replyTo);
        }
        System.out.println("Asunto: " + subject);
        if (attachment != null) {
            System.out.println("Adjunto: " + attachment);
        }
        if (highPriority) {
            System.out.println("Prioridad alta");
        }
    }

    static class Builder {
        private String to;
        private String replyTo;
        private String subject;
        private String body;
        private String cc;
        private String bcc;
        private String attachment;
        private boolean highPriority;
        private boolean trackOpens;

        public Builder to(String value) { to = value; return this; }
        public Builder replyTo(String value) { replyTo = value; return this; }
        public Builder subject(String value) { subject = value; return this; }
        public Builder body(String value) { body = value; return this; }
        public Builder cc(String value) { cc = value; return this; }
        public Builder bcc(String value) { bcc = value; return this; }
        public Builder attachment(String value) { attachment = value; return this; }
        public Builder highPriority() { highPriority = true; return this; }
        public Builder trackOpens() { trackOpens = true; return this; }

        public Email build() {
            if (to == null) {
                throw new IllegalStateException("Falta el destinatario");
            }
            if (subject == null) {
                throw new IllegalStateException("Falta el asunto");
            }
            if (body == null) {
                throw new IllegalStateException("Falta el texto");
            }
            return new Email(this);
        }
    }
}

Un builder cuesta código: cada campo se escribe tres veces: en el correo, en el builder y en su método. Por eso no se hace para cada clase.

Email.Builder es una clase anidada: ve el constructor privado de Email, y nadie más. Los campos de Email son final.

Email email = new Email.Builder()
        .to("maria@example.com")
        .subject("El pedido 1042 ha sido enviado")
        .body("Tu paquete está en camino.")
        .attachment("invoice-1042.pdf")
        .highPriority()
        .build();
email.send();

Email.Builder draft = new Email.Builder()
        .to("peter@example.com")
        .body("Tu paquete está en camino.");
try {
    draft.build();
} catch (IllegalStateException e) {
    System.out.println(e.getMessage());
}

Salida

Para: maria@example.com
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Prioridad alta
Falta el asunto

Email email = new Email.Builder()
        .to("maria@example.com")
        .subject("El pedido 1042 ha sido enviado")
        .body("Tu paquete está en camino.")
        .attachment("invoice-1042.pdf")
        .highPriority()
        .build();
email.send();

Email.Builder draft = new Email.Builder()
        .to("peter@example.com")
        .body("Tu paquete está en camino.");
try {
    draft.build();
} catch (IllegalStateException e) {
    System.out.println(e.getMessage());
}

Paso a paso, en palabras

1. new Email.Builder(): un plano vacío con nueve casillas. Las tres obligatorias (to, subject, body) están marcadas.
2. .to(…) rellena una casilla y devuelve el mismo builder, así que la cadena continúa.
3. Cada llamada tiene un nombre: un valor no puede acabar en la casilla equivocada, como pasaba con las posiciones del constructor.
4. .body(…): las tres casillas obligatorias están rellenas.
5. Los campos opcionales se escriben solo cuando hacen falta. highPriority() no lleva argumento: ya no hay un true en el octavo lugar.
6. build() comprueba las casillas obligatorias y estampa un Email. Sus campos son final: el objeto ya no cambia.
7. El correo sale hacia María, con la factura, con prioridad alta.
8. Un builder nuevo, un plano vacío nuevo. Aquí alguien olvidó el asunto.
9. draft.build() llega a la casilla vacía subject y se detiene con una excepción. Un correo sin asunto ni siquiera llega a existir.
10. El error dice qué falta. No se ha enviado nada.

El correo sin asunto nunca llega al correo postal: build() lo detiene ya en el armado.

Míralo

Sin builder: lo que ofrece el lenguaje

Java no tiene argumentos con nombre. Un record escribe los campos, el constructor y los accesores, y el objeto es inmutable, pero nueve parámetros siguen siendo nueve posiciones. Por eso los casos comunes reciben un método de fábrica con nombre (como en la lección Factory), y la comprobación va en el constructor compacto:

record Email(String to, String replyTo, String subject, String body, String cc,
             String bcc, String attachment, boolean highPriority, boolean trackOpens) {
    Email {
        if (to == null || subject == null || body == null) {
            throw new IllegalArgumentException("Falta el destinatario, el asunto o el texto");
        }
    }

    static Email orderShipped(String to, int orderId, String invoice) {
        return new Email(to, "support@shop.example", "El pedido " + orderId + " ha sido enviado",
                "Tu paquete está en camino.", null, null, invoice, false, false);
    }
}

Email email = Email.orderShipped("maria@example.com", 1042, "invoice-1042.pdf");
System.out.println(email.to() + " / " + email.subject() + " / " + email.attachment());

Salida

maria@example.com / El pedido 1042 ha sido enviado / invoice-1042.pdf

Para todo lo demás, el código Java usa un builder. La propia biblioteca estándar lo hace: HttpRequest.newBuilder().uri(…).header(…).build(). La biblioteca Lombok escribe el builder por ti con la anotación @Builder.

Cuándo vale la pena un builder de todos modos:

• el correo se arma por pasos, en distintas partes del código: el adjunto se añade solo si hay factura, la copia solo para empresas;
• hay una comprobación entre campos: por ejemplo, la copia oculta no puede ser la dirección del destinatario;
• hay muchos campos, la mayoría opcionales, y el lenguaje no tiene argumentos con nombre.

Pruébalo

Predice la salida

Un builder, dos llamadas a build(). ¿Qué imprime el programa?

Email.Builder builder = new Email.Builder()
        .to("maria@example.com")
        .subject("El pedido 1042 ha sido enviado")
        .body("Tu paquete está en camino.");
Email first = builder.build();
builder.highPriority();
Email second = builder.build();
System.out.println(first.highPriority() + " " + second.highPriority());

Respuesta

true true

false true

false false

Comprobar

Pruébalo

Encuentra el error

La tienda envía los correos de los pedidos enviados en un bucle. Solo el primer pedido tiene factura:

List<Order> orders = List.of(
        new Order("maria@example.com", 1042, "invoice-1042.pdf"),
        new Order("peter@example.com", 1043, null));
Email.Builder builder = new Email.Builder().replyTo("support@shop.example");
for (Order order : orders) {
    builder.to(order.email())
            .subject("El pedido " + order.id() + " ha sido enviado")
            .body("Tu paquete está en camino.");
    if (order.invoice() != null) {
        builder.attachment(order.invoice());
    }
    builder.build().send();
}

Salida

Para: maria@example.com
Responder a: support@shop.example
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Para: peter@example.com
Responder a: support@shop.example
Asunto: El pedido 1043 ha sido enviado
Adjunto: invoice-1042.pdf

Peter recibió la factura de María. ¿En qué línea está el error?

Elige la línea con el error.

1List<Order> orders = List.of(2 new Order("maria@example.com", 1042, "invoice-1042.pdf"),3 new Order("peter@example.com", 1043, null));4Email.Builder builder = new Email.Builder().replyTo("support@shop.example");5for (Order order : orders) {6 builder.to(order.email())7 .subject("El pedido " + order.id() + " ha sido enviado")8 .body("Tu paquete está en camino.");9 if (order.invoice() != null) {10 builder.attachment(order.invoice());11 }12 builder.build().send();13}

Comprobar

La idea

Cuándo no lo necesitas

Builder duplica el código de la clase. No compensa cuando:

• hay dos o tres campos y todos son obligatorios: un constructor simple es más claro;
• basta un record con un método de fábrica para los casos comunes;
• el objeto no tiene nada que comprobar y no se arma por pasos.

Compensa cuando hay muchos campos y la mayoría son opcionales, cuando hay una comprobación entre ellos, o cuando el objeto se arma por pasos, en distintas partes del código.

Ejercicio

Un paquete para el mensajero

Resuelve la tarea en tu editor.

Un builder para un paquete. El mensajero quiere un paquete con destinatario, teléfono, dirección y peso (obligatorios), y opcionalmente: frágil y contra reembolso. Escribe Shipment y un builder para él. build() comprueba que los campos obligatorios estén puestos y que el peso sea mayor que 0 y de hasta 30 kg. Crea un paquete para María (2,5 kg, frágil, contra reembolso 42,90 €), imprímelo y prueba un paquete de 45 kg:

Salida

Paquete para María, 0888 123 456
Dirección: Calle Mayor 5, Madrid
Peso: 2.5 kg, frágil
Contra reembolso: 42.90 €
El peso debe ser mayor que 0 y de hasta 30 kg

Más tareas

• Arregla el bucle. Arregla el programa de «Encuentra el error» para que cada correo lleve solo su propia factura. La dirección de respuesta debe quedar para todos los correos.
• Una copia con un cambio. Añade un método que convierta un correo terminado en un builder con los mismos valores (en Java suele llamarse toBuilder()). Envía el mismo correo a otro destinatario.
• El camino del lenguaje. Escribe Shipment como en la tarjeta «Sin builder» y compara las dos versiones. ¿Cuál es más corta, y qué pierdes?

Test

Ponte a prueba

1. new Email("support@…", "maria@…", …) compila, y el correo va a otro sitio. ¿Por qué no ayudó el compilador?

El compilador no comprueba cadenasLos dos parámetros son String: una posición no tiene nombre, así que el intercambio es código válidoEl constructor está mal escrito

2. ¿Qué hace build()?

Comprueba los campos obligatorios y crea un objeto inmutableEnvía el correoVacía el builder para el siguiente correo

3. El builder se crea antes del bucle y se usa para cada correo. El segundo correo recibió el adjunto del primero. ¿Por qué?

El adjunto se guarda en un campo compartido de la claseHay un solo builder, y recuerda los valores del último armadobuild() copia los correos antiguos

4. ¿Cuándo vale la pena Builder de todos modos?

Siempre, en cuanto hay más de dos camposCuando el objeto se arma por pasos, en distintos lugares del código, o hay una comprobación entre camposCuando la clase es inmutable

5. ¿Por qué Builder es más común en Java que en C# y Python?

Java no tiene constructoresBuilder es más rápido en JavaJava no tiene argumentos con nombre, y un record con muchos campos sigue siendo posicional

Comprobar

Empezar la lección de nuevo

Lecciones relacionadas

• Se basa en: Clases anidadas · record, switch y patrones · Patrones de diseño · Factory Method y Simple Factory
• Continúa en: La tienda: qué patrón dónde
• Ejercicios sobre el tema: Patrones de diseño