How to Flatten Array in Java: Complete Guide with Code Examples

Last verified: April 2026

Executive Summary

Flattening nested arrays is one of the most common data structure operations Java developers encounter, sitting at the intersection of collection handling and algorithmic problem-solving. Whether you’re working with multi-dimensional arrays, lists of lists, or deeply nested structures, understanding the right approach can mean the difference between elegant, performant code and something that leaves your team scratching their heads during code review.

This guide covers four production-ready techniques: the modern streams API (our top recommendation for Java 8+), traditional nested loops, recursive approaches, and using Apache Commons Lang. We’ll walk through concrete examples, edge cases that trip up even experienced developers, and performance considerations so you can choose the best fit for your specific problem.

Main Data Table

Approach	Time Complexity	Space Complexity	Best Use Case	Readability
Streams API (flatMap)	O(n)	O(n)	Modern Java (8+), mixed structures	Excellent
Nested For Loops	O(n)	O(n)	Simple 2D arrays, maximum clarity	Good
Recursion	O(n)	O(n + h)	Deeply nested arbitrary structures	Fair
Apache Commons Lang	O(n)	O(n)	Projects using Commons, batch operations	Good

Breakdown by Experience Level and Approach

Different Java skill levels benefit from different techniques. Beginners grasp nested loops immediately, while intermediate developers should master the streams API, and advanced developers might reach for recursive solutions when dealing with truly arbitrary nesting.

Experience Level	Recommended Approach	Learning Difficulty	Industry Adoption
Beginner (0-1 year)	Nested For Loops	Very Easy	Still widely used in legacy codebases
Intermediate (1-3 years)	Streams API (flatMap)	Easy-Moderate	95%+ adoption in modern projects
Advanced (3+ years)	Recursion + Streams Hybrid	Moderate-Hard	Used in specialized scenarios

Method 1: Streams API with flatMap (Recommended)

The streams API is the modern standard for Java 8 and later. It’s concise, composable, and handles collections elegantly.

import java.util.*;
import java.util.stream.Collectors;

public class ArrayFlattener {
    // Simple 2D array flattening
    public static List<Integer> flatten2DArray(int[][] input) {
        return Arrays.stream(input)
            .flatMapToInt(Arrays::stream)
            .boxed()
            .collect(Collectors.toList());
    }
    
    // List of lists flattening
    public static <T> List<T> flattenListOfLists(List<List<T>> input) {
        return input.stream()
            .flatMap(List::stream)
            .collect(Collectors.toList());
    }
    
    // Practical example with null handling
    public static List<String> flattenWithNullSafety(
            List<List<String>> input) {
        return input.stream()
            .filter(Objects::nonNull)  // Skip null inner lists
            .flatMap(list -> list.stream()
                .filter(Objects::nonNull))  // Skip null elements
            .collect(Collectors.toList());
    }
    
    public static void main(String[] args) {
        // Example 1: 2D primitive array
        int[][] grid = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}};
        List<Integer> result = flatten2DArray(grid);
        System.out.println(result);  // [1, 2, 3, 4, 5, 6, 7, 8, 9]
        
        // Example 2: List of lists
        List<List<String>> data = Arrays.asList(
            Arrays.asList("a", "b"),
            Arrays.asList("c", "d"),
            Arrays.asList("e", "f")
        );
        List<String> flattened = flattenListOfLists(data);
        System.out.println(flattened);  // [a, b, c, d, e, f]
    }
}

Method 2: Traditional Nested Loops

When you need maximum clarity or are working with legacy code, nested loops get the job done.

public class LoopFlattener {
    // Standard nested loop approach
    public static List<Integer> flattenWith2DLoop(int[][] input) {
        List<Integer> result = new ArrayList<>();
        
        for (int[] row : input) {
            for (int value : row) {
                result.add(value);
            }
        }
        
        return result;
    }
    
    // With input validation
    public static List<Integer> flattenWithValidation(int[][] input) {
        if (input == null || input.length == 0) {
            return Collections.emptyList();
        }
        
        List<Integer> result = new ArrayList<>();
        
        for (int[] row : input) {
            if (row != null) {  // Handle sparse arrays
                for (int value : row) {
                    result.add(value);
                }
            }
        }
        
        return result;
    }
}

Method 3: Recursive Solution for Arbitrary Nesting

When dealing with unknown depth or object-based structures, recursion provides flexibility.

import java.util.*;

public class RecursiveFlattener {
    // Recursive flattening for arbitrary nesting
    public static List<Integer> flattenRecursive(Object obj) {
        List<Integer> result = new ArrayList<>();
        
        if (obj == null) {
            return result;
        }
        
        if (obj instanceof Integer) {
            result.add((Integer) obj);
        } else if (obj instanceof int[]) {
            for (int value : (int[]) obj) {
                result.addAll(flattenRecursive(value));
            }
        } else if (obj instanceof Object[]) {
            for (Object element : (Object[]) obj) {
                result.addAll(flattenRecursive(element));
            }
        } else if (obj instanceof Iterable) {
            for (Object element : (Iterable<?>) obj) {
                result.addAll(flattenRecursive(element));
            }
        }
        
        return result;
    }
    
    public static void main(String[] args) {
        Object nested = new Object[]{
            1,
            new int[]{2, 3},
            new Object[]{4, new int[]{5, 6}},
            Arrays.asList(7, 8, 9)
        };
        
        List<Integer> result = flattenRecursive(nested);
        System.out.println(result);  // [1, 2, 3, 4, 5, 6, 7, 8, 9]
    }
}

Comparison Section

Let’s compare array flattening approaches side-by-side with related data structure operations:

Technique	Syntax Complexity	Performance	Null Safety	Maintainability
flatMap + streams	Low (1-2 lines)	Excellent (optimized)	Good (explicit filters)	Excellent (idiomatic)
Nested for loops	Low (explicit)	Excellent (direct)	Fair (requires manual checks)	Good (familiar pattern)
Recursion	Moderate	Good (but stack overhead)	Fair (multiple type checks)	Fair (harder to debug)
Apache Commons	Very Low (1 call)	Good (tested library)	Excellent (built-in)	Good (external dependency)
Custom utility class	Depends on implementation	Variable	Excellent (you control it)	Excellent (internal standard)

Key Factors When Choosing Your Approach

1. Java Version Compatibility

The streams API arrived in Java 8 (2014). If you’re supporting Java 7 or earlier, stick with nested loops or Apache Commons. For any project started in the last five years, streams should be your default. We strongly recommend upgrading if you’re still on Java 7—the language has evolved significantly, and modern frameworks often require Java 11 or later anyway.

2. Data Structure Regularity

Regular, rectangular 2D arrays? Nested loops are crystal clear and perform identically to streams. Irregular structures, jagged arrays, or deeply nested collections? Streams shine because they compose elegantly, and recursion becomes necessary if depth varies unpredictably. Mixing both—using streams for the outer structure and recursion for internal traversal—often yields the cleanest code.

3. Memory Constraints

All our approaches use O(n) space for the output list. However, streams have a subtle advantage: they can be chained with terminal operations like forEach that don’t materialize intermediate collections. If you’re flattening massive datasets and only need to process elements (not collect them), avoid creating a full list.

4. Error Handling Requirements

The most common mistake developers make: forgetting null checks. Your input might contain null inner arrays or null elements. Streams make this elegant with filter(Objects::nonNull). Loops require explicit if-checks. Recursion demands careful type checking. Plan your null handling strategy before writing code—it’s harder to bolt on afterward.

5. Team Familiarity and Project Standards

Code is read more often than it’s written. If your team hasn’t adopted functional programming patterns yet, teach streams gradually. Start with simple flatMap examples in code review. If you’re in a strict enterprise environment with established style guides, follow them—consistency matters more than the marginal performance difference between methods.

Historical Trends

Java array flattening has evolved dramatically. Pre-2014, nested loops and Apache Commons were the only options—developers spent cycles on what should have been trivial. Java 8’s streams API changed everything. Initial adoption was slow (2014-2016) as teams learned functional concepts, but by 2018, flatMap became the idiomatic approach in modern codebases.

Interestingly, nested loops haven’t disappeared entirely. They’re still preferred in teaching contexts and when readability is paramount. We’ve seen a resurgence of traditional loops in performance-critical sections, suggesting developers are moving away from premature optimization assumptions about streams.

Apache Commons Lang usage has plateaued—it’s still in legacy projects, but new code rarely pulls in a dependency for array operations Java now handles natively. The future likely belongs to record types (Java 14+) and sealed classes, which may enable even more elegant solutions for complex nested structures.

Expert Tips

Tip 1: Use flatMap as Your Starting Point

Unless you have a specific reason (Java 7 compatibility, performance-critical inner loops), default to streams. It’s readable, composable, and becomes more powerful when chained with filter, map, and other operations. Your future self will appreciate not having to debug nested loop indices.

Tip 2: Build Null Safety Into Your Method Signature

Don’t just assume inputs won’t be null. Document your expectations with annotations (@NonNull, @Nullable from jetbrains.annotations or javax.annotation), and return Optional<List<T>> or use defensive checks. A null pointer exception in production after flattening is embarrassing.

Tip 3: Benchmark Before Optimizing

Developers often assume loops outperform streams. Testing with JMH (Java Microbenchmark Harness) consistently shows they’re comparable, and streams often win due to CPU-level optimizations. Profile your actual code, not theoretical complexity. A poorly-written loop beats a fancy stream—but a well-written stream beats a poorly-written loop.

Tip 4: Consider Your Terminal Operation

Do you need a List? Use collect(Collectors.toList()). Need to process each element sequentially? Use forEach(). Need a Set to eliminate duplicates while flattening? Use collect(Collectors.toSet()). The terminal operation often matters more than the flattening itself.

Tip 5: Document Edge Cases in Your Tests

Write unit tests for: empty input, null inner structures, single-element arrays, and maximum-depth nesting. These tests document your assumptions and prevent regression. A comprehensive test suite is your insurance policy against “but it worked yesterday” bugs.

FAQ Section

Q1: What’s the difference between flatMap and map for flattening?

The critical distinction: map transforms each element into a stream and returns a Stream<Stream<T>>. You’d then need a second flatMap call to flatten the streams themselves. flatMap does this in one step—it maps each element to a stream and automatically flattens the result into a single Stream<T>. In practice, flatMap is 99% of what you want. Example:

// ❌ Wrong: creates Stream<Stream<Integer>>
Arrays.stream(array)
    .map(Arrays::stream)  // Oops, nested streams
    .collect(Collectors.toList());

// ✓ Correct: automatically flattens
Arrays.stream(array)
    .flatMap(Arrays::stream)  // Single Stream<Integer>
    .collect(Collectors.toList());

Q2: How do I flatten an array into a primitive int array instead of a List?

Use flatMapToInt (or flatMapToLong, flatMapToDouble) instead of flatMap. This avoids boxing and unboxing overhead:

int[] result = Arrays.stream(input)
    .flatMapToInt(Arrays::stream)
    .toArray();  // Returns primitive int[]

Q3: Does stream().flatMap() maintain the original order?

Yes. Streams preserve encounter order unless you’re using parallel streams on an unordered source. For flattening nested structures, order is preserved left-to-right. If you’re flattening and expecting a specific order, parallel streams might reorder elements—stick with sequential streams unless you’ve explicitly designed your code to handle reordering.

Q4: What happens if I try to flatten a null array?

NullPointerException. The streams API doesn’t handle null inputs gracefully. Always check before calling: if (input != null) { ... } or use Optional wrapping. Better yet, use a method that documents its null policy and fails fast with clear error messages.

Q5: Is flattening arrays more efficient than keeping them nested?

Not inherently. Flattening has O(n) space and time complexity—you create a new structure. Keep arrays nested if you don’t need them flat. Flattening is useful for passing to APIs expecting flat collections, for algorithms like sorting the entire dataset, or for deduplication across sub-arrays. If you’re only iterating once, nested loops might be more memory-efficient than creating a flattened copy.

Conclusion

Flattening arrays in Java has never been simpler. For modern projects (Java 8+), flatMap is your go-to solution—it’s expressive, maintainable, and performs excellently. For 2D rectangular arrays where maximum clarity matters, nested loops remain a solid choice. For deeply nested or heterogeneous structures, recursion handles the complexity elegantly.

The common mistake developers make is overthinking this decision. Start with streams. Add null checks. Write tests for edge cases. Benchmark only if you suspect a real performance problem. Your code will be cleaner, your team will understand it, and your project will be better for it.

Choose the approach that matches your Java version, data structure, and team practices. Then move on to solving the interesting parts of your problem.