Tolerant Reader

About 3 min

Intent

Allows a system to be more resilient to changes in the data structures it consumes by ignoring elements that it does not recognize.

Explanation

Real-world example

Imagine a postal system that delivers letters and packages to recipients. In this system, postal workers deliver mail regardless of additional information or stickers that might be present on the envelopes or packages. If a package has extra labels or instructions that the postal system does not recognize, the postal worker ignores these and focuses only on the essential information like the address. This approach ensures that the delivery process remains functional even when senders use different formats or include unnecessary details, similar to how the Tolerant Reader pattern works in software by ignoring unrecognized data elements to maintain functionality and compatibility.

In plain words

Tolerant Reader pattern is used to create robust communication mechanisms between services.

Robustness Principleopen in new window says

Be conservative in what you do, be liberal in what you accept from others.

Programmatic Example

We are persisting RainbowFish objects to file. Later on they need to be restored. What makes it problematic is that RainbowFish data structure is versioned and evolves over time. New version of RainbowFish needs to be able to restore old versions as well.

Here's the versioned RainbowFish. Notice how the second version introduces additional properties.

@Getter
@RequiredArgsConstructor
public class RainbowFish implements Serializable {

    private static final long serialVersionUID = 1L;

    private final String name;
    private final int age;
    private final int lengthMeters;
    private final int weightTons;
}

@Getter
public class RainbowFishV2 extends RainbowFish {

    @Serial
    private static final long serialVersionUID = 1L;

    private boolean sleeping;
    private boolean hungry;
    private boolean angry;

    public RainbowFishV2(String name, int age, int lengthMeters, int weightTons) {
        super(name, age, lengthMeters, weightTons);
    }

    public RainbowFishV2(String name, int age, int lengthMeters, int weightTons, boolean sleeping,
                         boolean hungry, boolean angry) {
        this(name, age, lengthMeters, weightTons);
        this.sleeping = sleeping;
        this.hungry = hungry;
        this.angry = angry;
    }
}

Next we introduce the RainbowFishSerializer. This is the class that implements the Tolerant Reader pattern.

@NoArgsConstructor
public final class RainbowFishSerializer {

    public static void writeV1(RainbowFish rainbowFish, String filename) throws IOException {
        var map = Map.of(
                "name", rainbowFish.getName(),
                "age", String.format("%d", rainbowFish.getAge()),
                "lengthMeters", String.format("%d", rainbowFish.getLengthMeters()),
                "weightTons", String.format("%d", rainbowFish.getWeightTons())
        );

        try (var fileOut = new FileOutputStream(filename);
             var objOut = new ObjectOutputStream(fileOut)) {
            objOut.writeObject(map);
        }
    }

    public static void writeV2(RainbowFishV2 rainbowFish, String filename) throws IOException {
        var map = Map.of(
                "name", rainbowFish.getName(),
                "age", String.format("%d", rainbowFish.getAge()),
                "lengthMeters", String.format("%d", rainbowFish.getLengthMeters()),
                "weightTons", String.format("%d", rainbowFish.getWeightTons()),
                "angry", Boolean.toString(rainbowFish.getAngry()),
                "hungry", Boolean.toString(rainbowFish.getHungry()),
                "sleeping", Boolean.toString(rainbowFish.getSleeping())
        );

        try (var fileOut = new FileOutputStream(filename);
             var objOut = new ObjectOutputStream(fileOut)) {
            objOut.writeObject(map);
        }
    }

    public static RainbowFish readV1(String filename) throws IOException, ClassNotFoundException {
        Map<String, String> map;

        try (var fileIn = new FileInputStream(filename);
             var objIn = new ObjectInputStream(fileIn)) {
            map = (Map<String, String>) objIn.readObject();
        }

        return new RainbowFish(
                map.get("name"),
                Integer.parseInt(map.get("age")),
                Integer.parseInt(map.get("lengthMeters")),
                Integer.parseInt(map.get("weightTons"))
        );
    }
}

And finally, here's the full example in action.

public static void main(String[] args) throws IOException, ClassNotFoundException {
    // Write V1
    var fishV1 = new RainbowFish("Zed", 10, 11, 12);
    LOGGER.info("fishV1 name={} age={} length={} weight={}", fishV1.getName(),
            fishV1.getAge(), fishV1.getLengthMeters(), fishV1.getWeightTons());
    RainbowFishSerializer.writeV1(fishV1, "fish1.out");
    // Read V1
    var deserializedRainbowFishV1 = RainbowFishSerializer.readV1("fish1.out");
    LOGGER.info("deserializedFishV1 name={} age={} length={} weight={}",
            deserializedRainbowFishV1.getName(), deserializedRainbowFishV1.getAge(),
            deserializedRainbowFishV1.getLengthMeters(), deserializedRainbowFishV1.getWeightTons());
    // Write V2
    var fishV2 = new RainbowFishV2("Scar", 5, 12, 15, true, true, true);
    LOGGER.info(
            "fishV2 name={} age={} length={} weight={} sleeping={} hungry={} angry={}",
            fishV2.getName(), fishV2.getAge(), fishV2.getLengthMeters(), fishV2.getWeightTons(),
            fishV2.isHungry(), fishV2.isAngry(), fishV2.isSleeping());
    RainbowFishSerializer.writeV2(fishV2, "fish2.out");
    // Read V2 with V1 method
    var deserializedFishV2 = RainbowFishSerializer.readV1("fish2.out");
    LOGGER.info("deserializedFishV2 name={} age={} length={} weight={}",
            deserializedFishV2.getName(), deserializedFishV2.getAge(),
            deserializedFishV2.getLengthMeters(), deserializedFishV2.getWeightTons());
}

Program output:

15:38:00.602 [main] INFO com.iluwatar.tolerantreader.App -- fishV1 name=Zed age=10 length=11 weight=12
15:38:00.618 [main] INFO com.iluwatar.tolerantreader.App -- deserializedFishV1 name=Zed age=10 length=11 weight=12
15:38:00.618 [main] INFO com.iluwatar.tolerantreader.App -- fishV2 name=Scar age=5 length=12 weight=15 sleeping=true hungry=true angry=true
15:38:00.619 [main] INFO com.iluwatar.tolerantreader.App -- deserializedFishV2 name=Scar age=5 length=12 weight=15

Applicability

Use when a system needs to consume data from external sources that may change over time.
Applicable when backward compatibility is required in API design.
Suitable for integration scenarios where different systems exchange data and evolve independently.

Known Uses

JSON or XML parsers that skip unknown elements.
API clients in microservices architectures that interact with multiple versions of a service.

Consequences

Benefits:

Increases the robustness and flexibility of the system.
Allows independent evolution of producers and consumers in a distributed system.
Simplifies versioning by enabling backward compatibility.

Trade-offs:

May result in silent failures if important data is ignored.
Can complicate debugging and tracing of issues due to missing or unrecognized data.

Adapteropen in new window: Both patterns deal with data transformation and integration, but the Adapter Pattern focuses on converting interfaces, while Tolerant Reader focuses on ignoring unrecognized data.
Facadeopen in new window: Simplifies interactions with complex systems, similar to how Tolerant Reader simplifies data consumption by ignoring irrelevant data.
Strategyopen in new window: Can be used in conjunction with Tolerant Reader to dynamically switch between different data handling strategies.