Java BiConsumer: Syntax, Usage, and Common Patterns

java biconsumer requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.

Java's BiConsumer is a functional interface that accepts two arguments and returns no result. It is part of the java.util.function package and is commonly used with collections, streams, and other APIs that require side-effecting operations on pairs of values. Unlike BiFunction, which returns a result, BiConsumer is designed for actions like logging, updating state, or iterating over map entries.

What BiConsumer Represents

The BiConsumer interface declares a single abstract method accept(T t, U u). It takes two parameters of possibly different types and performs an operation without returning anything. Because it is a functional interface, it can be used as the target for lambda expressions or method references. The interface also provides a default method andThen(BiConsumer<? super T, ? super U> after) that composes two consumers, executing the current one first and then the specified one.

Basic Syntax and Lambda Usage

The simplest way to use BiConsumer is with a lambda expression. For example, the following code prints a key-value pair:

BiConsumer<String, Integer> printEntry = (key, value) -> System.out.println(key + " = " + value);
printEntry.accept("count", 42);

Here, the lambda receives a String and an Integer, and the accept method triggers the printing. The type parameters are inferred from the context, but you can also specify them explicitly if needed. This pattern is useful when you need to pass a two-argument operation as a parameter to another method.

Using Method References with BiConsumer

Method references can make BiConsumer code more concise and readable. If you already have a method that matches the signature (T, U) -> void, you can reference it directly. For instance, consider a class with a static method that formats a pair:

public class PairPrinter {
    public static void print(String key, Integer value) {
        System.out.printf("%s: %d%n", key, value);
    }
}

BiConsumer<String, Integer> printer = PairPrinter::print;

The method reference PairPrinter::print works because the method's parameter list and return type align with BiConsumer's contract. Instance methods can also be referenced, but they require an instance to be bound, as shown later.

Common Use Cases: Map Iteration and Pair Processing

One of the most frequent uses of BiConsumer is iterating over a Map. The Map.forEach method accepts a BiConsumer that receives each key and value. This eliminates the need for an explicit entrySet() loop:

Map<String, Integer> scores = new HashMap<>();
scores.put("Alice", 90);
scores.put("Bob", 85);

scores.forEach((name, score) -> System.out.println(name + " has " + score + " points"));

Another common scenario is processing pairs from two lists or arrays. You can combine two streams into a BiConsumer operation, though this often requires manual index management. For example, to zip two lists:

List<String> names = List.of("Alice", "Bob");
List<Integer> ages = List.of(30, 25);

BiConsumer<String, Integer> recordAge = (name, age) -> System.out.println(name + " is " + age + " years old");
for (int i = 0; i < names.size(); i++) {
    recordAge.accept(names.get(i), ages.get(i));
}

This approach works when both lists have the same length. In production code, you should validate the sizes to avoid IndexOutOfBoundsException.

Chaining Operations with andThen()

The andThen method allows you to combine two BiConsumer instances into one. The composed consumer executes the first operation, then the second, even if the first one throws an exception. Here is an example that logs and then updates a counter:

BiConsumer<String, Integer> log = (key, value) -> System.out.println("Log: " + key + "=" + value);
BiConsumer<String, Integer> increment = (key, value) -> counter += value;

BiConsumer<String, Integer> combined = log.andThen(increment);
combined.accept("visits", 5);

Note that andThen does not handle exceptions. If the first consumer throws, the second one is never executed. If you need exception handling, wrap the logic inside each consumer individually.

BiConsumer vs BiFunction and Other Functional Interfaces

It's easy to confuse BiConsumer with BiFunction because both accept two arguments. The critical difference is the return type: BiFunction returns a value, while BiConsumer returns void. This distinction determines when to use each. For transformations or computations that produce a result, use BiFunction. For side effects like printing, updating state, or sending events, use BiConsumer.

The table below summarizes the most relevant two-argument functional interfaces in java.util.function:

BinaryOperator is a specialization of BiFunction where both inputs and the output share the same type. It is useful for operations like summing numbers or concatenating strings.

Handling Exceptions Inside BiConsumer

The accept method does not declare any checked exceptions. If your operation can throw a checked exception, you must handle it inside the lambda or method reference. For example, if you write to a file that throws IOException, you cannot propagate it directly:

BiConsumer<String, String> writeToFile = (path, content) -> {
    try {
        Files.write(Path.of(path), content.getBytes());
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
};

Wrapping checked exceptions in an unchecked exception like UncheckedIOException is a common pattern. Alternatively, you can handle the exception locally, log it, or ignore it if the operation is best-effort. The key is that the functional interface contract does not allow checked exceptions to escape, so you must decide how to deal with them.

Performance and Maintainability Considerations

BiConsumer itself introduces no runtime overhead beyond the cost of the operation it performs. The main performance consideration is whether you use a lambda that captures variables or creates unnecessary objects. A lambda that captures a mutable variable, such as a counter, may have slightly higher overhead than a static method reference, but in most applications this is negligible.

For maintainability, prefer method references when the operation is already defined elsewhere. This keeps the code DRY and makes the intent clearer. Also avoid using BiConsumer for operations that logically return a value; that would force you to use mutable state or side effects, which can make the code harder to test and reason about.

When composing multiple consumers with andThen, be aware that the order matters. If the operations are not independent, chaining them may produce unexpected results. For example, if the first consumer modifies the input object and the second reads it, the second will see the modified state. Ensure that the sequence is intentional and well-documented.