In Java, there are three fundamental abstractions for grouping data:

1. List<E>: Index-ordered collection that allows duplicates. Elements maintain their insertion position (ArrayList, LinkedList).

2. Set<E>: Collection of unique elements. Can be unordered (HashSet) or ordered by insertion (LinkedHashSet) or natural ordering (TreeSet).

3. Map<K,V>: It is not a Collection, but a number of key-value pairs with unique keys. Similarly: unordered (HashMap), insertion-ordered (LinkedHashMap), or natural (TreeMap).

These interfaces have been widely used since JDK 1.2 (1998), with few structural changes since JDK 5 (2004, generics). However, they had a critical gap: there was no common abstraction for collections with defined "encounter order" (clear first/last element) that unified:

List/Deque     vs     LinkedHashSet/SortedSet  (¡no common supertype!)
(duplicates OK)          (unique)

Java 21 (JEP 431) introduces SequencedCollection, SequencedSet, and SequencedMap, the first fundamental interfaces in many years, resolving this historic inconsistency.

Ordered Sets

The Need for SequencedSet<E>

Before Java 21, developers faced a structural inconsistency: collections with defined encounter order + unique elements existed (LinkedHashSet, NavigableSet), but shared no common interface. Set<E> is unordered by definition, forcing API designers to return concrete LinkedHashSet types, violating interface segregation.

Pre-Java 21:

// PROBLEM 1: No abstraction for ordered+unique
public LinkedHashSet<String> getOrderedUniqueItems() {  // Concrete type! Bad API design, an interface should be used
    return new LinkedHashSet<>(items);
}

// PROBLEM 2: Accessing first/last requires hacks
LinkedHashSet<String> set = new LinkedHashSet<>(List.of("C", "A", "B"));
String first = set.iterator().next();        
String last  = null;
Iterator<String> it = set.iterator();
while (it.hasNext()) last = it.next();       // Manual scan!
set.remove(last);                           // Order may shift

// PROBLEM 3: Reverse iteration? Copy to List first
List<String> reversed = new ArrayList<>(set);
Collections.reverse(reversed);              // O(n) copy + reverse

Java 21 solution - SequencedSet<E> (extends SequencedCollection<E>):

SequencedSet<String> set = new LinkedHashSet<>();
set.addLast("C"); set.addLast("A"); set.addLast("B");  // [C, A, B]

String first = set.getFirst();    // "C" - O(1)
String last  = set.getLast();     // "B"  - O(1)
set.removeFirst();                // [A, B]

// Reordering existing elements (NEW!)
set.addFirst("A");                // Moves A to front: [A, B]
set.addLast("B");                 // Moves B to end:   [A, B]

// Reverse stream - uniform across all sequenced types
set.reversed().stream()
   .forEach(System.out::println);  // B, A

Why No SequencedList<E> equivalent?

List<E> and Deque<E> already share the exact operations SequencedCollection provides (getFirst(), removeLast(), etc.). SequencedCollection<E> sits between Collection<E> and both:

graph TB
    Collection --> SC[SequencedCollection]
    SC --> List["List<E>"]
    SC --> Deque["Deque<E>"]
    
    classDef sequenced fill:#bbdefb,stroke:#01579b,stroke-width:2px
    classDef standard fill:#f5f5f5
    class SC sequenced
    class List,Deque standard

List gained SequencedCollection methods for free. No need for a SequencedList wrapper—List<E> is already sequenced.

Why Tail Elements Matter

Accessing first/last elements (tail elements) is a fundamental operation in ordered collections, yet in pre-Java 21 it could be error-prone. Developers constantly needed temporary variables just to compute indices, leading to off-by-one errors.

Pre-Java 21:

List<String> items = fetchItemsFromDatabase();  // Simulate expensive fetch
int lastIndex = items.size() - 1;              // Temp var #1: index calculation
String lastItem = items.get(lastIndex);        // Temp var #2: store result
processLastItem(lastItem);                     // Finally use it

// Or inline 
String firstItem = items.isEmpty() ? null : items.get(0);  // Null check + index

// Example - Processing latest log entry:

List<LogEntry> logs = readLogFile();  // 10k+ entries
if (!logs.isEmpty()) {
    int lastIdx = logs.size() - 1;               // Temporary variable for index
    LogEntry latest = logs.get(lastIdx);         // Another temporary variable
    sendAlert(latest.getLevel(), latest.getTime()); 
}

Post-JDK 21:

List<LogEntry> logs = readLogFile();
if (!logs.isEmpty()) {
    LogEntry latest = logs.getLast();         // Direct! No temporary variables
    sendAlert(latest.getLevel(), latest.getTime());
}

// Even inlines perfectly:
processLastItem(fetchItemsFromDatabase().getLast());  // Zero boilerplate

Why this matters technically:

• Eliminates size()-1 bug (most common List off-by-one error)

• Uniform API across List, Deque, LinkedHashSet via SequencedCollection

Ordered Maps

The Need for SequencedMap<K,V>

As it has been explained with Set, Pre-Java 21, Map<K,V> implementations with defined encounter order (LinkedHashMap, NavigableMap) lacked a common interface, forcing concrete types in APIs and inconsistent endpoint operations. Map naming conventions were also fragmented (firstEntry() vs pollFirstEntry() vs no operations at all).

Pre-Java 21:

// PROBLEM 1: Concrete types in APIs
public LinkedHashMap<String, Integer> getOrderedScores() {  // Bad API design, an interface should be used
    return new LinkedHashMap<>();
}

// PROBLEM 2: No consistent first/last access
LinkedHashMap<String, Integer> map = new LinkedHashMap<>();
map.put("C", 3); 
map.put("A", 1); 
map.put("B", 2);  // Order: C,A,B

// First entry? Iterator hack
Map.Entry<String, Integer> first = map.entrySet().iterator().next();  // O(n)

// Last entry? Manual scan
Map.Entry<String, Integer> last = null;
for (Map.Entry<String, Integer> e : map.entrySet()) {
    last = e;
}

Java 21 solution - SequencedMap<K,V>:

SequencedMap<String, Integer> map = new LinkedHashMap<>();
map.putLast("C", 3); 
map.putLast("A", 1); 
map.putLast("B", 2);  // [C,A,B]

Map.Entry<String, Integer> first = map.firstEntry();   // O(1) - "C"=3
Map.Entry<String, Integer> last  = map.lastEntry();    // O(1) - "B"=2

// Remove + return (poll semantics from NavigableMap)
Map.Entry<String, Integer> removed = map.pollLastEntry();  // "B"=2, map=[C,A]

// Reordering existing keys (NEW!)
map.putFirst("A", 99);  // Updates A, moves to front: [A, C]

Sequenced Map Views

Unique to maps: Three sequenced projections that preserve order:

SequencedMap<String, Integer> scores = new LinkedHashMap<>();
scores.put("Z", 26); 
scores.put("A", 1); 
scores.put("M", 13);

// Traditional views (unordered!)
Set<String> keys = scores.keySet();           // HashSet - order lost!

// NEW: Sequenced views preserve encounter order
SequencedSet<String> seqKeys = scores.sequencedKeySet();    // [Z, A, M]
seqKeys.removeFirst();  // Removes "Z" from original map!

Real-world example - LRU Cache simulation:

SequencedMap<String, Integer> cache = new LinkedHashMap<>();
cache.putLast("key1", 100);
cache.putLast("key2", 200);

// "Touch" key1 (move to end)
cache.putLast("key1", 150);  // Now: [key2, key1]

// Evict oldest
cache.pollFirstEntry();      // Removes key2

Map Hierarchy

graph TB
    Map --> SM["SequencedMap<K,V>"]
    SM --> SortedMap
    SortedMap --> NavigableMap
    LHM["LinkedHashMap"]
    SM -.-> LHM
    
    classDef new fill:#bbdefb,stroke:#01579b
    classDef impl fill:#f3e5f5
    class SM new
    class LHM impl

Key Technical Differences

Reverse Streams

Pre-Java 21 hacks:

Stream<String> reversed = IntStream.range(0, list.size())
    .mapToObj(i -> list.get(list.size()-1-i));

Java 21 solution - Works everywhere:

// List, Set, Map views - uniform!
list.reversed().stream()
linkedHashSet.reversed().stream()
map.sequencedKeySet().reversed().stream()
    .filter(s -> s.startsWith("A"))
    .forEach(System.out::println);

Example: Log processing:

logEntries.reversed().stream()    // Newest first
    .filter(LogEntry::isError)
    .limit(5)
    .forEach(LogAnalyzer::process);

Why "Sequenced" Instead of "Ordered"?

Not "OrderedSet" because:

1. SortedSet already exists (natural/comparator order, like TreeSet)

2. "Encounter order" ≠ sorted order:

   NavigableSet<Integer> sorted = new TreeSet<>(List.of(3, 1, 2));  // [1,2,3]
   LinkedHashSet<Integer> seqd  = new LinkedHashSet<>(List.of(3,1,2)); // [3,1,2]
   

3. SequencedSet preserves insertion order (or stable order), not sorted order

4. Terminology consistency: Matches Stream API's "encounter order" concept [JEP 431]

Key distinction:

SequencedSet<Integer> seq = new LinkedHashSet<>(List.of(3, 1, 2));  // [3,1,2]
SortedSet<Integer> sorted = new TreeSet<>(seq);                    // [1,2,3]

Collection Hierarchy

Java requires specifying the data type when declaring a variable.
This has two goals:

• To know how many memory locations are used.

• To know which operations can be performed on the data. The basic operations are addition, subtraction, multiplication, division and remainder or modulo: +, -, *, /, %.

A primitive type is a data type that is defined directly in the Java programming language.

Primitive types

As in almost all programming languages, Java has the following primitive data types:

• For integer numbers: byte, short, int, long.

• For floating‑point numbers: float and double.

• For characters: char.

• For logical values (only two possible values): boolean.

In total, Java has eight primitive types: byte, short, int, long, char, float, double and boolean.

String is the only basic predefined data type that is widely used but is not a primitive type; it is a class.

Wrapper types

A wrapper type is a predefined class that encapsulates a value of a primitive type:

• Integer wraps the primitive type int.

• Long wraps the primitive type long.

• Character wraps the primitive type char.

• Float wraps the primitive type float.

• Double wraps the primitive type double.

• Boolean wraps the primitive type boolean.

• Byte wraps the primitive type byte.

• Short wraps the primitive type short.

Difference between primitive types and other data types

Primitive types are not objects and therefore do not have an associated class directly.

int monthNumber = 5;
System.out.println(monthNumber);

In data structures that require objects, such as map keys, you must use wrapper types. For example, the key can be of type Integer, but not of type int.

The following is incorrect:

Map<int, String> months = new HashMap<>();   // Incorrrect, because a map's key must be an object

This, however, is correct:

int monthNumber = 5;
Map<Integer, String> months = new HashMap<>();
months.put(monthNumber, "May");

In this and similar cases, the compiler automatically converts the primitive type int into the wrapper type Integer. This technique is called autoboxing (and the reverse conversion is called unboxing).

All Java objects inherit from the Object class. Since primitive types are not objects, they cannot use methods from Object, such as equals(), wait() or notify().

Objects and references

Objects are normally created with the new keyword (or via constructors and factories). Primitive types are declared simply using their type and the variable name.

int monthNumber = 5;
Integer otherMonthNumber = new Integer(5); // nowadays Integer.valueOf(5) is preferred

In other words, a reference‑type variable stores a reference to a memory area where the object is located. A primitive‑type variable stores the value directly in the memory associated with that variable.
A reference is conceptually similar to a pointer in the C language, although in Java it cannot be manipulated explicitly.

Data types and memory

• The data type that uses the least memory is byte, which occupies only one byte. Its value range goes from -128 to 127.

• short occupies two bytes and its range goes from -32,768 to 32,767 (Short.MIN_VALUE to Short.MAX_VALUE).

• int occupies four bytes and its range goes from -2,147,483,648 to 2,147,483,647 (Int.MIN_VALUE to Int.MAX_VALUE).

• long occupies eight bytes and its range goes from Long.MIN_VALUE to Long.MAX_VALUE.

Notice the symmetry in signed integer types: the total number of negative values is equal to the total number of positive values, considering that zero is counted on the positive side.
Unlike languages such as C or C++, Java does not have unsigned integer types.

• char occupies two bytes and represents values from 0 to 65,535 (Unicode characters).

• float occupies four bytes.

• double occupies eight bytes.

• The specification does not fix the physical size of boolean; logically it represents only two possible values (true and false).

Syntax for long, float and double literals

• A long literal may have the suffix L or l (it is recommended to use L to avoid confusion with the digit 1).

• A float literal must have the suffix F or f.

• A double literal may have the suffix D or d, although it is usually omitted because double is the default type for floating‑point literals.

long   x = 1L;
float  f = 1.0f;
double y = 1.0;

Digit separator

• The separator between integer and fractional part is the dot, and it is mandatory in decimal numbers.

• The thousands separator may be an underscore _. It is optional, but improves readability of large numbers. It was introduced in Java 7.

long   x = 1_000_000L;
double y = 1_000_000.0;

Scientific notation

• The exponent is written using the letter e or E.

• In scientific notation, the literal becomes a double by default, unless it is explicitly marked as float.

double y = 1e6;   // 1.0 × 10^6
double z = 1e6D;  // equivalent to the line above
float  f = 1e6f;  // float

(Using e with a long literal is not correct; 1e6 is a floating‑point literal, not a long.)

Precision of decimal numbers

• To use float, the literal must end with f or F.

• To use double, you may use d or D, but in practice it is usually omitted, since double is the default type.

float  f = 3.1415927f;
double d = 3.141592653589793;

The float and double types represent floating‑point numbers in binary, and therefore they cannot represent exactly most decimal fractions that are simple in base 10.

Type promotion

Java performs numeric promotion automatically when primitive numeric types are used in expressions with operators like +, -, *, /, %, or in comparisons.

Core Rules

• byte, short, char → always promoted to int first

• If any operand is long → both promoted to long

• If any operand is float → both promoted to float

• If any operand is double → both promoted to double

byte b = 100;
short s = 200;
// b + s promotes to int (compile error if assigned to byte/short)
int result = b + s;  

long big = 1_000_000L;
int small = 42;
long total = big + small;  // int -> long

BigInteger and BigDecimal classes

The BigInteger and BigDecimal classes are used to represent very large numbers or to perform calculations with high numeric precision.

In the case of BigDecimal, numbers are represented in decimal form (not as binary floating point), which allows arithmetic operations without the typical rounding errors of float and double when working, for example, with money.

// float/double PROBLEM (binary floating point)
double money = 0.1 + 0.2;  // 0.30000000000000004 ❌

// BigDecimal SOLUTION (decimal arithmetic)  
BigDecimal bd1 = new BigDecimal("0.1");
BigDecimal bd2 = new BigDecimal("0.2");
BigDecimal money = bd1.add(bd2);  // 0.3 exactly ✅

BigDecimal stores decimal digits + scale, not fractions p/q or rational numbers: 1/3 becomes "0.333333" (truncated/rounded), not the exact rational 1/3.

• Therefore, division operations always require scale and rounding modes.

Identity and equality

For primitive types, the value is the data itself; two primitive variables are “equal” if they contain the same value.
For reference types (objects), identity is determined by the reference (the logical address of the object), and logical equality is usually defined by the equals() method.

Autoboxing

As the official documentation says:

The result of all this magic is that you can largely ignore the distinction between int and Integer, with a few caveats. An Integer expression can have a null value. If your program tries to autounbox null, it will throw a NullPointerException. The == operator performs reference identity comparisons on Integer expressions and value equality comparisons on int expressions. Finally, there are performance costs associated with boxing and unboxing, even if it is done automatically.

When to use primitive types

• The use of primitive types in modern Java is not just about maintaining backward compatibility (autoboxing and unboxing techqniques were introduced in Java 5).

• In some cases, it's preferable to use primitive types for performance reasons, for example in big loops or in web applications with a very large volume of users.

Kotlin Data Types

Kotlin only works with objects, not with primitives in the Java sense.

• Types like Int, Long, Double, Boolean, Char, etc. are regular classes from the Kotlin point of view, and you can call methods and properties on them (10.toString()).

• There is no separate int/Integer distinction in the syntax like in Java; you always write Int, Long, Double, and so on.

What happens at runtime

• On the JVM, the compiler optimizes these types to real JVM primitives (int, long, double, etc.) whenever possible, so performance is equivalent to using primitives in Java.

• When a primitive‑like value must behave as an object (for example, when used in a generic type or stored in a List<Int>), the compiler uses the corresponding wrapper (java.lang.Integer, java.lang.Long, etc.), boxing and unboxing automatically. Primitive representations exist only as an implementation detail for efficiency on the JVM platform.

Unsigned types

Kotlin supports unsigned integer types (UInt, ULong, etc.) for positive-only values without sign bit. Java lacks these, as we have explained above.

We will explain how to create an object in Java. It has evolved from the old Javabeans to the use of features in the latest versions of the language.

Setters and getters

We have a Person with three attributes: name, age and gender.

import java.util.Objects;

public class Person {

    private String name;
    private int age;
    private String gender;

    public Person(String name, int age, String gender) {
        this.name = name; 
        this.age = age;
        this.gender = gender;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

    public Gender getGender() {
       return gender;
    }

    public void setName(String name) {
        this.name = name;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    @Override
    public String toString() {
        return "Person{" + "name='" + name + '\'' + ", age=" + age + ", gender='" + gender + '\'' + '}';
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) return true;
        if (obj == null || getClass() != obj.getClass()) return false;
        Person person = (Person) obj;
        return age == person.getAge() && name.equals(person.getName()) && gender.equals(person.getGender());
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age, gender);
    }
}

Any IDE can generate all the above methods. But...... we can do it better.

Validation

Imagine the client wants to create a Person with a negative age or a with no name. Our API must take care of that in the constructor:

public Person(String name, int age, String gender) {
    if (name == null || name.isBlank()) {
        throw new IllegalArgumentException("Invalid name");
    }
    if (age < 0) {
        throw new IllegalArgumentException("Age cannot be negative");
    }
    if (gender == null || gender.isBlank()) {
        throw new IllegalArgumentException("Invalid gender");
    }
    this.name = name;
    this.age = age;
    this.gender = gender;
}

Static factory methods

Instead of having the client call the traditional constructor, our API can provide a number of descriptive methods, so that the client can choose the most appropriate one. This pattern is very common in the JDK. For example, the Instance class (from the Java Time API) includes static factory methods such as now(), of(), from(), and parse().

    public static Person of(String name, int age, Gender gender) {
        return new Person(name, age, gender);
    }

    public static Person createATwentyYearOldMale(String name) {
        return new Person(name, 20, Gender.MALE);
    }

    public static Person createATwentyYearOldFemale(String name) {
        return new Person(name, 20, Gender.FEMALE);
    }

public enum Gender {
    MALE,
    FEMALE
}

Thanks to the enumeration class, we change the gender parameter from String type to Gender type. This allows to catch errors in compilation time.

    Person person = Person.of("John", 25, Gender.MALE);
    var person2 = Person.createATwentyYearOldMale("John");
    var person3 = Person.of("John", 25, "men");     // Compilation error

It is important to note that the constructor is now private, so that the client cannot create directly objects of this class:

    var person = new Person("Alice", 25, Gender.FEMALE);     // Compilation error

Other benefit of having the constructor private is that the client cannot extend the Person class:

    class Woman extends Person {  // Compilation error
        ...................
    }

This is a good thing, because we want to be able to control what the client can do with our API.

Non extensible class

However, to make the intent clear in the Javadoc documentation, we can use the final modifier:

    public final class Person {
        ...................
    }

We will talk about restricted inheritance later.

No setters

Although the setter methods were heavily used in the Javabeans days, programmers came to realize that immutable objects made in in many cases the code easier to read, especially in concurrent applications. In other words, creating an object every time an attribute changes its value. This is quite similar to how purely functional languages work.

    public Person withName(String newName) {
        return new Person(newName, this.age, this.gender);
    }

    public Person withAge(int newAge) {
        return new Person(this.name, newAge, this.gender);
    }

    public Person withGender(Gender newGender) {
        return new Person(this.name, this.age, newGender);
    }

and make the attributes immutable, too:

    private final String name;
    private final int age;
    private final Gender gender;

The with prefix is a common convention and these methods are called withers.

Records

A record is a class that is immutable(its attributes cannot be changed) and final. It was introduced as a preview feature in Java 14 and the first LTS version that included it was Java 17.

public record Person(String name, int age, Gender gender) {}

The record class automatically generates private final attributes, and implements the equals(), hashCode(), and toString() methods.

We only have to write this code:

public record Person(String name, int age, Gender gender) {
    
    // Validation rules
    public Person {   // The compact constructor doesn't have any parameters
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Name cannot be null or blank");
        if (age < 0)
            throw new IllegalArgumentException("Age cannot be negative");
        if (gender == null || gender.isBlank()) 
            throw new IllegalArgumentException("Invalid gender");
    }

    // Static factory methods
    public static Person of(String name, int age, Gender gender) {
        return new Person(name, age, gender);
    }

    public static Person createATwentyYearOldMale(String name) {
        return new Person(name, 20, Gender.MALE);
    }

    public static Person createATwentyYearOldFemale(String name) {
        return new Person(name, 20, Gender.FEMALE);
    }

    // Wither-methods
    public Person withName(String newName) {
        return new Person(newName, this.age, this.gender);
    }

    public Person withAge(int newAge) {
        return new Person(this.name, newAge, this.gender);
    }

    public Person withGender(Gender newGender) {
        return new Person(this.name, this.age, newGender);
    }
}

The public accessor methods generated for each component have the same name as the corresponding attribute, they are not getters anymore:

    var personJohn = Person.of("John", 25, Gender.MALE);
    System.out.println("Name: " + personJohn.name());     // Accesor method if Person is a record
    System.out.println("Name: " + personJohn.getName());  // Compiler error if Person is a record

There are two caveats with records:

• The public constructor of a record, called canonical constructor, is part of the interface. It can't be made private. As a consequence, the client is not forced to call the static factories.

• The wither methods are not yet generated by the compiler.
  The JEP ("Java Enhancement Proposal") 468 introduces derived record creation, which consists of generating “wither” methods automatically. But this technique, as of July 2025, is not even in preview yet.

When not to use records

If we have a class with a complex business logic (many static factories, for example), regular classes are better suited than records, as they are more flexible.

Summary

We have explained the best practices for declaring objects in Java.

Since the (not so good) old Java Beans, the principles of immutability and inheritance prohibition have been applied.

The implementation of records in Java 17 have greatly simplified the creation of objects without having to use libraries similar to Lombok.

However, in some cases it is still more convenient to use a regular class.

When creating a class in Java, there are three methods that are commonly overridden:

• equals()

• hashCode()

• toString()

This article focuses on the hashCode() method.

How a hash table works

Java uses the value returned by the hashCode() method to determine the position of an object in a hash table. But what is a hash table ?

Hash tables are data structures designed to store and retrieve elements efficiently, avoiding the sequential order of traditional arrays.

Imagine a table with 19 slots. The position (or index) of each value in the hash table is determined by a function such as:

@Override
public int hashCode() {
    return value % tableSize;
}

A common and simple way to define the hashCode() method is to return the remainder of the division between the value to be stored and the table size.

For example, to store the value 20:

@Override
public int hashCode() {
    return 20 % 19;  // remainder of 20 / 19
}

To store the value 21:

@Override
public int hashCode() {
    return 21 % 19;
}

So, the value 20 is stored at index 1, also called first bucket; the value 21 at index 2, and so on.

This approach ensures that the hash code is always within the bounds of the table, distributing the objects across the available slots.

For example, if the table size is 19 and we need to store the first sixty natural numbers, the hash table might look like this:

graph TD
    subgraph Hash Table
        slot0["Slot 0"]
        slot1["Slot 1"]
        slot2["Slot 2"]
        slot3["Slot 3"]
        slot4["Slot 4"]
    end

    slot0 --> A1["19"]
    A1 --> A2["39"]
    A2 --> A3["59"]

    slot1 --> B1["20"]
    B1 --> B2["40"]
    B2 --> B3["60"]

    slot2 --> C1["21"]
    C1 --> C2["41"]

    slot3 --> D1["22"]
    D1 --> D2["42"]

    slot4 --> E1["23"]
    E1 --> E2["43"]

The first two slots has an associated linked list of three elements and the rest of the slots have linked lists of two elements.

Using prime numbers for the hash functions

We chose 19 as the table size because it is a prime number. The possible remainders (hash values) are all the integers from 0 up to 18, inclusive. This means every input value will be mapped to one of 19 possible slots. Choosing a prime number as the table size ensures that the hash values are distributed uniformly across the slots, minimizing collisions.

Collisions

A collision occurs when more than one value is mapped to the same slot or bucket.

The solution, as shown in the previous example, is using a linked list for each slot (a technique called separate chaining). This way, multiple values can coexist in the same bucket, and the hash table can still function correctly. However, the performance can degrade if too many collisions occur.

Other considerations for hash functions

Prime numbers are often used when the hash function is simple, but there are reasons why they are not always chosen:

• Computational performance Many modern implementations prefer table sizes that are powers of 2 (e.g., 32, 64, 128) because they allow calculating the hash index using bitwise operations, which are faster than using the modulo operation. If the hash function distributes values well, primes may not be necessary.

• Dynamic resizing Some resizing strategies (like doubling the table size) produce sizes that are powers of 2, not primes. This strategy simplifies memory management and reduces computational overhead.

Commonly used hash functions

The pattern of multiplying by 31 and combining field values is widely used and recommended in the Java community.

• The use of 31 as a multiplier is standard because it is an odd prime, which helps produce a good distribution of hash codes.

• This approach combines the values of all the class fields in a way that reduces the likelihood of collisions.

• The general pattern is:

public int hashCode() {
    int result = 1;
    result = 31 * result + field1;
    result = 31 * result + field2;
    // ... and so on for more fields
    return result;
}

Since Java 8, the Objects.hashCode() method can also be used to generate hash codes:

@Override
public int hashCode() {
    return Objects.hash(firstField, secondField, ..., nField);
}

• This method is more concise and automatically combines the hash codes of the provided fields.

• Internally, it creates an array of the arguments and then calls Arrays.hashCode() on that array.

• It handles null values gracefully, returning 0 for any null field.

Which one to use

Objects.hash() improves readability and reduces boilerplate, especially for classes with many fields.

Manual hash code gives you more control and may be preferred in performance-sensitive or very large-scale scenarios. Read this Spanish article for a very interesting case where a customized redefinition of hashCode() fixed a poor performance issue.

Hash Tables in the Java Collections Framework

The Java Collections Framework uses hash tables in several classes:

• HashMap: The most widely used implementation of the Map interface, using a hash table internally.

• HashSet: Implements the Set interface and is backed by a HashMap, using the hash table mechanism to ensure uniqueness of elements.

The hash code determines the bucket or slot where the object is stored in these hash-based colllections.

Equals() and hashCode()

• If two objects are considered equal by the equals() method, they must have the same hash code as returned by hashCode(). This ensures that equal objects can be found in the same bucket in hash-based collections.

• If two objects have the same hash code, they are not necessarily equal. Hash collisions can occur, so equals() is used as a second check to confirm actual equality.

• If you override equals(), you must also override hashCode(). Failing to do so can lead to unexpected behavior in collections, such as not being able to retrieve objects that were added earlier.

Conclusion

The data structure called Hash Table was briefly introduced in this article. The most used strategies for hash functions minimize collisions and improve performance. Finally, the relationship between hashCode() and equals() is crucial, as they are used together to ensure correct behavior in hash-based collections.

The == operator is used to compare references, while the equals method is used to compare the contents of objects.

Comparison for predefined types

Primitive types

The comparison operator works with predefined types, such as integers, booleans, and characters:

int num = 2;
if (num == 2) {
    System.out.println("num equals two");
}

boolean gameIsOver = true;
if (gameIsOver) {  // Equivalent to: if (gameIsOver == true)
    System.out.println("The game is over");
}

Strings

However, there is a widely used predefined type that does not follow these rules: the String type.

String station = "SUMMER";
if (station.toLowerCase() == "summer") {  // INCORRECT!!
    System.out.println("It's summer");
}

This does not display the expected message.
The reason is that the == operator, when applied to strings, compares references, that is, memory locations. In principle, each variable is at a different memory location.

To compare the contents of strings, you should use the equals method defined in Java:

if (station.toLowerCase().equals("summer")) {
    System.out.println("It's summer");
}

How to compare objects

For objects of user-defined classes, you also use the equals method:

class Person {
    String name;
    int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    // getters and setters
}

Person person1 = new Person("Sara", 23);
Person person2 = new Person("Sara", 23);
if (person1.equals(person2)) {
    System.out.println("person1 and person2 are the same person");
}

The message is not displayed, so you can deduce that they are considered different people. This is because, by default, the equals method in the Object class only compares references, not the content of the fields.

The solution is to compare all the relevant fields:

if (person1.getName().equals(person2.getName()) && person1.getAge() == person2.getAge()) {
    System.out.println("person1 and person2 are the same person");
}

To avoid repeating these conditions every time, you can define the equals() method:

public boolean equals(Person person) {
    if (person.getName().equals(this.getName()) && person.getAge() == this.getAge()) {
        return true;
    } else {
        return false;
    }
}

Overriding equals()

All classes created in Java inherit methods from the Object class. One of these methods is:

public boolean equals(Object object);

By default, equals() in Object checks if two references point to the same object (i.e., using ==). Overriding equals() allows you to define equality based on the object's content:

@Override
public boolean equals(Object object) {
    // Explicit cast from Object to the type we're interested in
    Person person = (Person) object;
    return person.getName().equals(this.getName()) && person.getAge() == this.getAge()) {
}

The equals method must return false when one of the objects is null:

@Override
public boolean equals(Object object) {
    if (object == null) {
        return false;
    }
    // ...
}

Using instanceof

You can use instanceof to check the type before casting:

@Override
public boolean equals(Object object) {
    if (!(object instanceof Person)) {
        return false;
    }
    Person person = (Person) object;
    // ...
}

The null check is unnecessary because the instanceof operator returns false if its first operand is null.

Using Objects.equals()

When comparing object fields, the previous approach is not null-safe. That means the condition will throw a NullPointerException if a field is null.
To avoid this, we use the Objects.equals() method, which returns false if either object is null and true if both are null:

@Override
public boolean equals(Object object) {
    if (!(object instanceof Person)) return false;
    Person person = (Person) object;
    return Objects.equals(name, person.name) && age == person.age;
}

The disadvantage of using Objects.equals() is that it is not type-safe, so type checks are still necessary.

Preserve the equality when subclassing

The equals() method generated by many IDEs uses getClass() instead of instanceof.
When you use getClass(), you are performing a strict comparison. This means that derived classes or subclasses cannot be compared-they will not be considered equal to the parent class. If you want to compare subclasses with the parent class, you need to use the instanceof operator.

Some authors prefer using instanceof to allow subclasses to be compared, because inheritance is one of the fundamental properties of object-oriented programming. Additionally, symmetry is maintained, since this.equals(employee) gives the same result as employee.equals(this)

Let's take a look at an example when comparing two objects of the same class hierarchy.

class Person {
    protected String name;
    protected int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    @Override
    public boolean equals(Object obj) {
        // Check for reference equality
        if (this == obj)
            return true;

        // if (obj == null || getClass() != obj.getClass())
        // return false;
        if (!(obj instanceof Person)) {
            return false;
        }

        // Field comparison
        Person other = (Person) obj;
        return getAge() == other.getAge() && Objects.equals(getName(), other.getName());
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

}

class Employee extends Person {

    public Employee(String name, int age) {
        super(name, age);
    }

    @Override
    public boolean equals(Object obj) {
        // Check for reference equality
        if (this == obj)
            return true;

        // if (obj == null || getClass() != obj.getClass())
        if (!(obj instanceof Person))
            return false;

        // Field comparison
        Person other = (Person) obj;
        return getAge() == other.getAge() && Objects.equals(getName(), other.getName());
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }
}

import java.util.List;
import java.util.ArrayList;
import java.util.Objects;

public class SubclassComparison {
    public static void main(String[] args) {
        // List of objects of the parent class
        List<Person> personsList = new ArrayList<>();
        Person alice = new Person("Alice", 30);
        Person bob = new Person("Bob", 25);
        personsList.add(alice);
        personsList.add(bob);

        // List of objects of the subclass
        List<Employee> employeesList = new ArrayList<>();
        Employee aliceEmployee = new Employee("Alice", 30);
        Employee bobEmployee = new Employee("Bob", 25);
        employeesList.add(aliceEmployee);
        employeesList.add(bobEmployee);

        // Compare the lists
        boolean areEqual = personsList.equals(employeesList);
        System.out.println("Employee lists are equal: " + areEqual); 
    }
}

HashCode

The hashCode() method is used to generate a hash code for an object.
The hash code is a unique value that represents the object in hash-based collections.

Overriding hashCode() is crucial because it ensures that objects behave correctly when used in hash-based collections like HashMap, HashSet, and Hashtable.

Records

If you use a record, introduced in Java 16, the compiler implicitly creates the constructor, getters, equals(), hashCode(), and toString() methods.

record Person(String name, int age) { }

Conclusion

Understanding the difference between the == operator and the equals() method is essential.

The == operator compares object references, while equals() should be overridden to compare the actual content of objects.

When overriding equals(), always override hashCode() as well to ensure correct behavior in hash-based collections.

Using instanceof in your equals() implementation allows for greater flexibility and supports inheritance, which is a core principle of object-oriented programming.

For modern Java applications, records offer a concise way to create immutable data classes with proper equality and hashing behavior generated automatically by the compiler.

This article may seem too basic, but I decided to write it after seeing that many programmers do not know how to use interfaces in Java. This topic is related to design patterns in object-oriented programming (OOP).

An apparently simple class

We all have seen code similar to this one:

enum EnergyPlan {
    PlanA, PlanB, PlanC
}

class EnergyCalculator {

    BigDecimal calculateEnergy(EnergyPlan plan) {
        if (plan == EnergyPlan.PlanA) {
            System.out.println("Calculating energy for Plan A");
            return new BigDecimal(100);
        } else if (plan == EnergyPlan.PlanB) {
            System.out.println("Calculating energy for Plan B");
            return new BigDecimal(300);
        } else if (plan == EnergyPlan.PlanC) {
            System.out.println("Calculating energy for Plan C");
            return new BigDecimal(400);
        }
        else {
            throw new IllegalArgumentException("Unknown plan");
        }
    }
}

An enumeration is used and the EnergyCalculator class has only one method, which is not hard to follow.

Although it's probably easier to read if a switch statement is used:

class EnergyCalculator {

    BigDecimal calculateEnergy(EnergyPlan plan) {
        switch (plan) {
            case PlanA:
                System.out.println("Calculating energy for Plan A");
                return new BigDecimal(100);
            case PlanB:
                System.out.println("Calculating energy for Plan B");
                return new BigDecimal(300);
            case PlanC:
                System.out.println("Calculating energy for Plan C");
                return new BigDecimal(400);
            default:
                throw new IllegalArgumentException("Unknown plan");
        }
    }
}

Starting from Java 14 a switch expression can be used:

class EnergyCalculator {

    BigDecimal calculateEnergy(EnergyPlan plan) {
        BigDecimal result = switch (plan) {
            case PlanA -> {
                System.out.println("Calculating energy for Plan A");
                yield new BigDecimal(100);
            }
            case PlanB -> {
                System.out.println("Calculating energy for Plan B");
                yield new BigDecimal(300);
            }
            case PlanC -> {
                System.out.println("Calculating energy for Plan C");
                yield new BigDecimal(400);
            }
        };
        return result;
    }
}

The problem

You might be thinking: So what? I don't see any issue. And you're right...... until the logic for the different plans start to grow:

class EnergyCalculator {

    BigDecimal calculateEnergy(EnergyPlan plan) {
        BigDecimal result = switch (plan) {
            case PlanA -> {
                // Step 1
                // Step 2
                // Step 3
                yield new BigDecimal(100);
            }
            case PlanB -> {
                // Step 1
                // Step 2
                // Step 3
                yield new BigDecimal(300);
            }
            case PlanC -> {
                // Step 1
                // Step 2
                // Step 3
                yield new BigDecimal(400);
            }
        };
        return result;
    }
}

Imagine that each step is different for each plan and you easily end up having a one-hundred line class. One week later, you have to add a new plan and in one month you have up to six different plans.

The number of lines is now three hundred and you have to maintain it. It's very hard to read and to modify. It's not an exaggeration, this has happened to me.

Precisely this is what we are referring to when we say that the traditional if/else or switch block is not scalable.

Some of you may be thinking: But it's not too bad, since the logic is contained in methods from other classes. Even in that case, a long method is hard to maintain. Not to mention how you are going to test it. You have to mock all the classes that are involved in the logic. It's a mess.

The solution

Instead of having a very big block for each case, wouldn't it be better to create a class per plan and execute the same method:

class EnergyCalculator {
    public BigDecimal calculateEnergy(EnergyPlan plan) {
        EnergyPlanStrategy strategy;
        switch (plan) {
            case PlanA -> strategy = new PlanAStrategy();
            case PlanB -> strategy = new PlanBStrategy();
            case PlanC -> strategy = new PlanCStrategy();
            default -> throw new IllegalArgumentException("Unknown plan: " + plan);
        }
        return strategy.calculateEnergy();
    }
}

A number of classes with the same calculateEnergy() method. Does this sound familiar? It's like ArrayList and LinkedList implementing the same get() method (see my previous article).

Exactly, they are different implementations of the same interface:

interface EnergyPlanStrategy {
    BigDecimal calculateEnergy();
}

// Implementations for each plan
class PlanAStrategy implements EnergyPlanStrategy {
    @Override
    public BigDecimal calculateEnergy() {
        // Steps 1, 2, 3
    }
}

class PlanBStrategy implements EnergyPlanStrategy {
    @Override
    public BigDecimal calculateEnergy() {
        // Steps 1, 2, 3
    }
}

class PlanCStrategy implements EnergyPlanStrategy {
    @Override
    public BigDecimal calculateEnergy() {
        // Steps 1, 2, 3
    }
}

This is the diagram for the Energy Plan Strategy Pattern:

%% Title: Energy Plan Strategy Pattern
classDiagram
    title Energy Plan Strategy Pattern

    class EnergyPlanStrategy {
        <<interface>>
        +calculateEnergy(): BigDecimal
    }

    class PlanAStrategy {
        +calculateEnergy(): BigDecimal
    }
    class PlanBStrategy {
        +calculateEnergy(): BigDecimal
    }
    class PlanCStrategy {
        +calculateEnergy(): BigDecimal
    }

    EnergyPlanStrategy <|.. PlanAStrategy
    EnergyPlanStrategy <|.. PlanBStrategy
    EnergyPlanStrategy <|.. PlanCStrategy

The logic is contained in the different implementations of the EnergyPlanStrategy interface. They are different classes, as a result the code is easier to read and easier to test.

If a plan must be added, only one class needs to be added and a single line inside the switch/case block. We say this technique is scalable.

Notice we are not even using lambda expressions (see my article here) or any other feature introduced in Java 8. Except the new syntax for the switch/case block, this is all about using interfaces in a clever way.

Formal Definition

This technique is used so often that is a design pattern called Strategy Pattern. The main idea is to use interfaces to define a family of algorithms, encapsulate each one of them in a different class, and make them interchangeable.

Disadvantages

For complex logic, this pattern results in a more testable and maintainable code. This is a concise way of saying that the code is easier to read and easier to test.

The main disadvantage is that the code is more verbose. Every time a plan (algorithm) is added, a new class implementing the interface must be added, in addition to the line inside the switch/case block.

Summary

The interface pattern defines behaviors through interfaces and provides concrete implementations via classes. Interfaces act as contracts that specify method/s to be implemented, enabling abstraction and decoupling between the definition and the implementation of behaviors.

This pattern enhances flexibility, scalability, and the ability to extend implementations without affecting client code (the open to extension, closed to modification principle).

It relies solely on interfaces and classes, promoting the principle of program to an interface, not an implementation. This allows multiple classes to implement the same interface, encouraging code reuse and maintainability.

As a secondary goal, the evolution of the switch/case block was shown.

List is an interface in Java Collections that represents an ordered sequence of elements.

Features of a List:

• Access elements by position (index).

• Store duplicate elements, because a Set does not store duplicates.

• Insert or remove elements at any position.

This is the canonical definition of a List in Java.

The most common implementation

List being an interface, the most used implementation is the java.util.ArrayList class:

List<String> list = new ArrayList<>();
list.add("This");
list.add("is");
list.add("a");
list.add("list");

we can access elements by index:

String element = list.get(1);
System.out.println(element); // prints "is"

It is also possible to remove elements by index:

list.remove(2);
for (String element : list) {
    System.out.println(element);  // prints "This", "is", "list"
}

It is quite simple. It is like an array, but we do not have to worry about resizing it. The ArrayList class takes care of that. The notation is also different. We use get() instead of [] to access elements by index.

List Methods

Most of the methods are self-explanatory. The main ones are:

• add(): adds an element to the end of the list.

• remove(): removes an element from the list.

• get(): returns the element at the specified index.

• size(): returns the number of elements in the list.

• isEmpty(): returns true if the list is empty, false otherwise.

• contains(): returns true if the list contains the specified element, false otherwise.

• indexOf(): returns the index of the first occurrence of the specified element in the list, or -1 if the element is not found.

• lastIndexOf(): returns the index of the last occurrence of the specified element in the list, or -1 if the element is not found.

Two methods are going to be explained, because they are a bit confusing.

add()

add() is an overloaded method. It has two versions:

list.add(element);
list.add(index, element);

The first version adds the element to the end of the list, while the second version adds the element at the specified index. The second one would have rather been called insertAt().

set()

set(int index, E element) replaces the element at the specified index with the given element. It return the element that was previously at the specified position.

• The list must have an element at the specified index, otherwise it throws an exception.

• It changes the element in place, so it does not change the size of the list.

The LinkedList class

Why not use the ArrayList implementation always?

The ArrayList class is a good choice for most cases, in fact most of the programmers have only used that class when creating a List.

But there is one thing that the ArrayList class does not do very well: inserting and removing elements in random list positions. Why? Because every time an element is inserted or removed, the remaining elements starting from the modified position have to be shifted, since all the array elements must be stored in contiguous memory.

As a consequence, an LinkedList should be faster than an ArrayList for adding or removing elements in the middle of the list. Unless you have to use a cache memory, in which case you will prefer a list whose elements are contiguous in memory.

List<String> list = new LinkedList<>();
list.add("This");
list.add("is");
list.add("a");
list.add("list");

Since both classes implement the List interface, we can use them interchangeably.

Let's see how a simplified LinkedList looks like:

class LinkedList {
    private Node head = null;  // Start of the list
    private int size = 0;      // Number of nodes
    private int index = 0;
}

class Node {
    private String data;        // Element stored in this node
    private Node next = null;     // Link to the next node
    private Node previous = null; // Link to the previous node
}

As we can see, it is a doubly linked list. A node has three attributes: the data itself, and references to the next and previous nodes.

These nodes are not contiguous in memory. Therefore, when an element is inserted or removed, the remaining elements do not have to be shifted. A node has to modify only its two references, resulting in much faster operations.

graph LR
    subgraph MyLinkedList [Linked List]
        A[10] --> B[20]
        B --> C[30]
    end

After removing 20:

graph LR
    subgraph MyLinkedList [Linked List after removing Node B]
        A[10] --> C[30]
        B[20]  
    end

ArrayList vs LinkedList

The ArrayList class is faster for adding and removing elements in the middle of the list, while the LinkedList class is faster for adding and removing elements at the beginning or end of the list.

Let's see an example for measuring the time it takes to add and remove elements in the middle of the list:

import java.util.List;
import java.util.ArrayList;
import java.util.LinkedList;

public class ListInsertionBenchmark {
    public static void main(String[] args) {
        final int ELEMENT_COUNT = 10_000; // Number of insertions to test

        // Test ArrayList
        List<Integer> arrayList = new ArrayList<>();
        long arrayListTime = timeInsertInMiddle(arrayList, ELEMENT_COUNT);

        // Test LinkedList
        List<Integer> linkedList = new LinkedList<>();
        long linkedListTime = timeInsertInMiddle(linkedList, ELEMENT_COUNT);

        System.out.println("\nResults:");
        System.out.printf("ArrayList insertion time: %d ms\n", arrayListTime);
        System.out.printf("LinkedList insertion time: %d ms\n", linkedListTime);
    }

    private static long timeInsertInMiddle(List<Integer> list, int insertions) {
        // Pre-fill the list to avoid starting empty
        for (int i = 0; i < 1_000_000; i++) {
            list.add(i);
        }

        long startTime = System.currentTimeMillis();
        for (int i = 0; i < insertions; i++) {
            int middleIndex = list.size() / 2;
            list.add(middleIndex, i); // Insert at middle
        }
        long endTime = System.currentTimeMillis();

        return endTime - startTime;
    }
}

If we run this program, it turns out that the LinkedList insertion time is much greater than the ArrayList one, although all the insertions are done in the middle of the list.

It seems that the time it takes to traverse the list from head/tail to reach a middle index is higher for the LinkedList. This happens because the ArrayList data structure is optimized for shifting contiguous elements by using System.arraycopy(); whereas traversing all the nodes is slow because nodes are scattered in memory. Each pointer access can result in a memory cache miss, which makes the process even slower. In other words, insertion in a LinkedList without an iterator is a O(n) operation.

System.arraycopy() copies memory blocks from one part of an array to another. It's a native method, that is, its core logic is implemented in a lower-level language like C (or C++) for performance reasons. If a traditional loop were used to copy every single list element, the traversing time would be much higher.

ArrayList is faster due to contiguous memory and optimized block copying, not because it's a faster algorithm in terms of complexity.

The benchmark highlights that algorithmic complexity alone does not determine real-world performance. ArrayList’s optimized memory operations make it a strong contender even for middle insertions. We should profile our specific use case to make the most informed decision.

The missing piece: ListIterator

We said

The LinkedList class is faster for adding and removing elements at the middle of the list.

but the results obtained in the benchmark did not match that statement.

We can use a ListIterator and move it to a position once and then do many insertions/removals at that spot. In this way, we don't need to traverse the list each time.

    public static void main(String[] args) {
        final int ELEMENT_COUNT_WITH_ITERATOR = 3000;

        long arrayListIteratorTime = timeInsertUsingAnIterator(arrayList, ELEMENT_COUNT_WITH_ITERATOR);

        long linkedListIteratorTime = timeInsertUsingAnIterator(linkedList, ELEMENT_COUNT_WITH_ITERATOR);
        // ArrayList vs LinkedList
        System.out.println("\nResults:");
        System.out.printf("ArrayList insertion time: %d ms\n", arrayListTime);
        System.out.printf("LinkedList insertion time: %d ms\n", linkedListTime);

        System.out.printf("ArrayList iterator insertion time: %d ms\n", arrayListIteratorTime);
        System.out.printf("LinkedList iterator insertion time: %d ms\n", linkedListIteratorTime);
    }

    private static long timeInsertUsingAnIterator(List<Integer> list, int insertions) {
        // Pre-fill the list to avoid starting empty
        for (int i = 0; i < 10_000; i++) {
            list.add(i);
        }

        long startTime = System.currentTimeMillis();
        ListIterator<Integer> iterator = list.listIterator(5000);
        for (int i = 0; i < insertions; i++) {
            iterator.add(i);
        }
        long endTime = System.currentTimeMillis();

        return endTime - startTime;
    }
}

The insertions time for the LinkedList is very close to zero, and it's much faster than the ones for the ArrayList.

Multiple insertion and removals are faster when using a LinkedList, provided an iterator at the correct position is used. In these cases, insertion in a LinkedList is a O(1) operation.

A LinkedList is suitable for use cases where we need to add and remove elements at a known same position and we don't need to access elements by index often. Examples are undo/redo stacks and managing history.

LinkedList implements both the Queue and Deque interfaces, which means that it is a good choice for use cases where we need to add and remove elements from both ends of the list.

Conclusion

The Java List is an interface with methods for adding, removing, and accessing elements. It has two different implementations: ArrayList and LinkedList.

ArrayList offers excellent general-purpose performance, especially for random access and adding/removing at the end. LinkedList provides faster insertion and deletion if an iterator at the correct position is used. As always, the optimal choice depends on your application's specific needs and access patterns.

Collect is an extremely useful terminal operation to transform the elements of the stream into a different kind of result, like a List, a Set or a Map.

Java supports various built-in collectors via the Collectors class.

A very common use case is to convert a list into another list, after filtering the elements.

List<Integer> listOfNumbers = Arrays.asList(1, 2, 3, 4, 5);

List<Integer> listOfEvenNumbers = listOfNumbers.stream()
    .filter(n -> n % 2 == 0)
    .collect(Collectors.toList());

Formal definition

The official java doc for java.util.stream.Collector defines it as follows:

A Collector is a mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed.

What is a mutable reduction operation

A mutable reduction operation, such as Stream.collect(), collects the stream elements into a mutable result container as it processes them. On the other hand, a non-mutable reduction operation, such as Stream.reduce() uses immutable result containers and as a result needs to create a new (instance of the) container at every intermediate step of reduction. This degrades performance.

How a Collector works

As explained above, a collector collects the elements of a stream into a mutable container. There are five steps to this process:

• Step 1 - Supplier provides the mutable empty result container It is an instance of the Supplier functional interface which provides an instance of a Collection(or Map) to hold the collected elements.

• Step 2 - Accumulator adds individual elements into the result container It is an instance of the BiConsumer functional interface. It adds individual elements of stream encountered by it into the result container. This step is known as a fold in functional programming parlance.

• Step 3 - Combiner combines two partial results It is an instance of a BinaryOperator functional interface which combines two partial results returned by two separate groups of accumulations done in parallel.

• Step 4 - Optional Finisher to put the processed elements in a desired form It is an instance of a Function interface. If required, a Finisher can be used to map the collected elements in the result container to a different required form.

• Step 5 - Final Result The final collected elements are returned by the Collection in the result container i.e. Collection instance.

A Collector consists of four different operations: a supplier, an accumulator, a combiner and a finisher.

The Collector Interface

It is defined as follows:

public interface Collector<T, A, R>

• T is the element type being processed by the Stream.

• A is the type of the accumulated result container which keeps on getting elements (of type T) added throughout the collecting process.

• R is the type of the result container, or the collection, which is returned back as the final output by the collector.

Predefined Collectors

Java provides static methods in the java.util.stream.Collectors class for the most common mutable reduction operations.

joining()

To convert a list of numbers to a string, separated by commas:

String numbersJoined = listOfNumbers.stream()
    .map(Object::toString)
    .collect(Collectors.joining(", "));

summingInt()

To sum the elements of a list:

int total = listOfNumbers.stream()
    .collect(Collectors.summingInt(Integer::intValue));

groupingBy() and partitioningBy()

Aggregations on the elements of a stream are quite common:

Map<String, List<Employee>> employeesByDepartment = 
                 listOfEmployees.stream()
                 .collect(Collectors.groupingBy(Employee::getDepartment));

Partition is other common collector, which is used to partition elements based on a condition:

Map<Boolean, List<Employee>> partitionedEmployees = 
   listOfEmployees.stream()
                  .collect(Collectors.partitioningBy(e -> e.getDepartment() == CHOSEN_DEPARTMENT));

// To get only the employees in the chosen department:
List<Employee> employeesByDepartment = partitionedEmployees.get(true);

count()

For counting items in a list after a certain condition:

long countEvenNumbers = listOfNumbers.stream()
    .filter(n -> n % 2 == 0)
    .count();

Other predefined collectors are toSet(), toMap(), maxBy(), minBy(), reducing(), averaginInt(), counting(), mapping()

Custom Collectors

A new collector is created by using the Collector.of() method. It receives four parameters: a supplier, an accumulator, a combiner and a finisher.

For example, let's create a collector that prints the duplicates of each element separated by commas:

Collector<Integer, StringJoiner, String> numberJoinerCollector = 
    Collector.of(
        () -> new StringJoiner(", "),                         // supplier
        (sj, num) -> sj.add(num.toString()),            // accumulator
        StringJoiner::merge,                                    // combiner
        StringJoiner::toString);                                // finisher

String result = listOfNumbers
    .stream()
    .collect(numberJoinerCollector);

Since strings in Java are immutable, a helper class like StringJoiner is needed to let the collector construct a string. The combiner knows how to merge two StringJoiners into one.

Conclusion

The definition of collectors was explained in detail in this article. After that, the most common predefined collectors were introduced with examples. Finally, how to create custom collectors, using the Collector<T, A, R> interface, was shown.

Comparison-based stream operations

We will explain several common methods, some of them were mentioned in the previous article.

sorted

It sorts the elements of the stream based on the comparator provided.

List<Employee> listOfEmployeesSortedByName = listOfEmployees
    .stream()
    .sorted((e1, e2) -> e1.getName().compareTo(e2.getName()))
    .collect(Collectors.toList());

min and max

var youngestEmployee = listOfEmployees
    .stream()
    .min((e1, e2) -> e1.getAge() - e2.getAge())
    .orElseThrow(NoSuchElementException::new);

Defining the comparison can be avoided by using Comparator.comparing():

var oldestEmployee = listOfEmployees
    .stream()
    .max(Comparator.comparing(Employee::getAge))
    .orElseThrow(NoSuchElementException::new);

distinct

It does not take any arguments and returns a stream with distinct elements, eliminating duplicates. It uses the equals() method to decide whether two elements are equal. A common pattern is to use Sets to remove duplicates. distinct() achieves the same result in a more elegant way.

List<Integer> listOfDistinctNumbers = 
Arrays.asList(1, 2, 3, 4, 5, 1, 2, 6, 7, 3)
    .stream()
    .distinct()
    .collect(Collectors.toList());

allMatch, anyMatch and noneMatch

These operations are used to check if all, any or none of the elements in the stream match a certain condition. They take a predicate and return a boolean. The processing is stopped as soon as the answer is determined. This technique, also used by the Java logical operators, is called short-circuiting:

boolean allEven = listOfNumbers.stream()
                     .allMatch(n -> n % 2 == 0);
boolean atLeastOneEven = listOfNumbers.stream()
                     .anyMatch(n -> n % 2 == 0);
boolean noneEven = listOfNumbers.stream()
                     .noneMatch(n -> n % 2 == 0);

Stream Specializations

We worked with Stream<T> so far. But there are other stream types, which are used in specific situations. The most used ones are:

• IntStream

• LongStream

• DoubleStream

These specialized streams are used to perform operations on primitive types. They extend BaseStream<T> type, not Stream<T>.

IntStream extends BaseStream<Integer>
LongStream extends BaseStream<Long>
DoubleStream extends BaseStream<Double>
Stream<T> extends BaseStream<T>

To create a specialized stream, we use the static factory method of() of the corresponding type.

IntStream intStream = IntStream.of(1, 2, 3, 4, 5);
LongStream longStream = LongStream.of(1L, 2L, 3L, 4L, 5L);
DoubleStream doubleStream = DoubleStream.of(1.0, 2.0, 3.0, 4.0, 5.0);

Map variants: mapToInt, mapToLong and MapToDouble

The map() operation, as explained in the previous article, returns a Stream type. But when dealing with numerical data to achieve statistics results, returning a number is more convenient.

A default value is not required for the sum() operation on an IntStream, because sum() returns 0 for an empty stream. Therefore, sum() is a terminal operation.

List<Integer> listOfNumbers = Arrays.asList(1, 2, 3, 4, 5);

int sum = listOfNumbers
    .stream()
    .mapToInt(n -> n)
    .sum();

Unlike sum(), the average() method returns an OptionalDouble to account for empty streams. Attempting to assign this directly to a double without handling the empty case will result in a compilation error. Other methods with a similar behavior -they do not return a primitive value- are min() and max().

OptionalInt optionalMinimum = listOfNumbers
    .stream()
    .mapToInt(Integer::intValue)
    .min();

There are three possible solutions:

• Use the orElse() method to provide a default value.

• Use the orElseThrow() method to throw an explicit error.

• Use getAsDouble() if we assume the list will never be empty.

Notice the two first methods are part of the Optional<T> API.

int minimum = listOfNumbers
    .stream()
    .mapToInt(Integer::intValue)  // Convert to IntStream
    .min()
    .orElse(0);

double average = listOfNumbers
    .stream()
    .mapToInt(Integer::intValue)  // Convert to IntStream
    .average()                    // Convert to OptionalDouble
    .orElseThrow(() -> new IllegalArgumentException("List is empty"));

double average = listOfNumbers
    .stream()
    .mapToDouble(Integer::intValue)  
    .average()     // Convert to OptionalDouble 
    .getAsDouble();

Statistics

The summaryStatistics() method provides combined statistics like count, sum, min, average, and max.

IntSummaryStatistics stats = listOfNumbers
    .stream()
    .mapToInt(Integer::intValue)
    .summaryStatistics();

System.out.println("Count: " + stats.getCount());
System.out.println("Sum: " + stats.getSum());
System.out.println("Min: " + stats.getMin());
System.out.println("Max: " + stats.getMax());
System.out.println("Average: " + stats.getAverage());

File operations

Streams can also be used in file operations. For example, to read a file line by line and print those lines:

Stream<String> lines = Files.lines(Paths.get("file.txt"));
lines.forEach(System.out::println);

Improvements in Java 9

We will explore new methods like takeWhile and dropWhile that are used to perform operations on infinite streams.

Stream<Integer> infiniteStream = Stream.iterate(1, n -> n + 1);

List<Integer> listOfNaturalNumbers = infiniteStream
    .takeWhile(n -> n <= 10)
    .map(x -> x * x)
    .forEach(System.out::println);  
    // Prints 1, 4, 9, 16, 25, 36, 49, 64, 81, 100

In that example, using filter() instead of takeWhile() yields the same result. But the two methods opperates differently: takeWhile() stops processing as soon as the predicate is false, whereas filter evaluates the entire stream.

dropWhile() is the opposite of takeWhile(). Instead of taking elements while a condition is true, dropWhile skips elements while the condition is true and starts returning elements when the condition becomes false.

These two methods already existed in the Scala and Kotlin APIs, but not in Java.

Streams are a sequence of elements that can be processed in a lazy way.

The Stream API is a feature introduced in version 8 of the Java platform that provides an efficient way to process collections. In Java 9, several improvements were made.

The Stream API is based on the concept of a pipeline of operations that can be applied to a stream of elements. This pipeline can be divided in three parts:

• Stream creation

• Intermediate operations

• Terminal operations

A stream pipeline consists of a stream source, followed by zero or more intermediate operations, and finally a terminal operation. Notice that the terminal operation is the only one that returns a value.

Example of a stream pipeline without any intermediate operation:

streamOfEmployees
   .foreach(e -> System.out.println(Employee::getName));

That was the formal definition of a stream. In practice, it can replace many loops, resulting in a much more readable and less error-prone code.

public List<Integer> getEvenNumbers(List<Integer> listOfNumbers) {
    List<Integer> listOfEvenNumbers = new ArrayList<>();
    for (Integer number : listOfNumbers) {
        if (number % 2 == 0) {
            listOfEvenNumbers.add(number);
        }
    }
    return listOfEvenNumbers;
}

Using streams:

public List<Integer> getEvenNumbers(List<Integer> listOfNumbers) {
    return listOfNumbers
        .stream()
        .filter(n -> n % 2 == 0)
        .collect(Collectors.toList());
}

This is called a declarative way of writing code, because we are writing what result we want to achieve, without worrying about how to do it.

Stream creation

A stream can be created from an array or a collection.

private Employee[] employees = {
    new Employee("Jason", 30),
    new Employee("Maria", 32),
};

var streamOfEmployees = Stream.of(employees)

private List<Employee> employeesList = Arrays.asList(employees);

var streamOfEmployees = employeesList.stream()

We can use factory methods to create streams.

var streamOfIntegers = Stream.of(1, 2, 3, 4, 5)

var streamOfEmployees = Stream.of(
    new Employee("Jason", 30),
    new Employee("Maria", 32)
)

or using Stream.builder()

Stream.Builder<Employee> streamBuilder = Stream.builder();
streamBuilder.accept(new Employee("Jason", 30));
streamBuilder.accept(new Employee("Maria", 32));
var streamOfEmployees = streamBuilder.build();

Stream operations

forEach

It is used to perform an action by calling the supplied transformation (lambda expression) on each element of the stream.

streamOfEmployees.forEach(e -> e.getName());

forEach() is a terminal operation.

map

It produces a new stream whose elements are the results of applying the given function to the elements of an existing stream.

var streamOfNames = streamOfEmployees
    .map(Employee::getName)      // or .map(e -> e.getName())
    .collect(Collectors.toList());

Notices map is an intermediate operation, therefore we have to use a Collector after the transformation.

filter

It is similar to map but it filters the elements of the stream.

var streamOfNames = streamOfEmployeesInTheirThirties
    .filter(e -> e != null)
    .filter(e -> e.getAge() >= 30)
    .collect(Collectors.toList());

findFirst

It returns an Optional containing the first element of the stream.

var employee = streamOfEmployees
    .map(employeeRepository::findById)
    .findFirst()
    .orElse(null);

findFirst() is a terminal operation.

flatMap

It is similar to map but it flattens the elements of the stream. An example is converting a list of lists to a list of elements.

var ListOfNames = listOfEmployees
    .stream()
    // .map(Employee::getName)
    .flatMap(Collection::stream)
    .collect(Collectors.toList());

Other stream operations

The following ones are only mentioned because they are very common. Their names are self explanatory:

• distinct()

• sorted()

• limit()

• skip()

• peek()

• anyMatch()

• allMatch()

• noneMatch()

• min()

• max()

Terminal operations

count

It returns the number of elements in the stream.

var numberOfEmployees = streamOfEmployees.count();

reduce

It reduces the stream to a single value.

var sumOfAges = streamOfEmployees
    .map(Employee::getAge)
    .reduce(0, Integer::sum);

Unlike other languages, reduce must receive a starting value.

A reduction operation, also called a fold, takes a sequence of elements and combines them into a single value by repeated applications of a combining operation. Other reduction operations are findFirst(), min() and max().

var listOfNumber = List.of(1, 2, 3, 4, 5);

var sumOfNumbers = listOfNumber
    .stream()
    .reduce(0, Integer::sum);

or

var sumOfNumbers = listOfNumber
    .mapToInt(Integer::intValue)
    .sum();

collect

It is used to collect the elements of the stream into a container.

The strategy for this operation is provided via the Collector interface. There are several implementations of this interface, but the most common ones are the ones related to the three collection types:

• Collectors.toList()

• Collectors.toSet()

• Collectors.toMap()

toArray

It returns an array containing the elements of the stream.

Employee[] ArrayOfEmployees = streamOfEmployees
    .toArray(Employee[]::new);

Lazy evaluation

In the beginning of the article we mentioned that the Stream API is lazy. This means that the stream pipeline is not executed until the terminal operation is called.

Why should we care? Let's see an example.

Stream<Integer> infiniteStream = Stream.iterate(0, n -> n + 1);

List<Integer> listOfNaturalNumbers = infiniteStream
    .skip(3)
    .limit(10)
    .collect(Collectors.toList());

System.out.println(listOfNaturalNumbers);

The output is [4, 5, 6, 7, 8, 9, 10, 11, 12, 13].

The stream pipeline above will be executed only when the terminal operation is called. So all intermediate operations are lazy. This technique allows computations on finite streams to be completed in finite time. In other words, the evaluation of the functions is separated from the description of the transformation. This is the definition of lazy evaluation.

One of the most important characteristics of the streams is that they allow for significant optimizations through lazy evaluations.

Parallel Streams

Parallel streams are streams that are executed in parallel.

Stream<Integer> parallelStream = Stream.of(1, 2, 3, 4, 5)
    .parallel()
    .map(n -> n * n);

As is the case when writing multi-threaded code, we need to be aware of a few things while using parallel streams:

• We need to ensure that the code is thread-safe. Take special care if the operations performed in parallel modify shared data.

• We should not use parallel streams if the order in which operations are performed or the order returned in the output stream matters. For example, operations like findFirst() may generate different results in the case of parallel streams.

• Also, we should ensure that it’s worth making the code execute in parallel. Understanding the performance characteristics of the operation in particular, but also of the system as a whole, is naturally very important.

Infinite Streams

Also called unbounded streams, infinite streams are used to perform operations while the elements are still being generated. However, when using map, all the elements are already populated.

There are two ways to generate infinite streams:

generate

// Print ten random numbers
Stream.generate(Math::random)
    .limit(10)
    .forEach(System.out::println);

iterate

It takes an initial value, called the seed and a function that generates the next element using the previous value. iterate() is statefull, therefore it may not be useful in parallel streams:

Stream<Integer> evenNumbersStream = Stream.iterate(2, i -> i * 2)

public getFirstEvenNumbers(int size) {
    return Stream.iterate(2, i -> i * 2) // evenNumbersStream 
        .limit(size)
        .collect(Collectors.toList());
}

limit() is the terminating condition.

Summary

The motivations behind Java streams were explained and several examples were presented. Several of the most common transformation were explained or mentioned.

The lazy evaluation technique was explained, which is used by many methods of the Stream API and allows to perform operations on infinite streams in a finite time. Parallel streams were created, which are streams that are executed in parallel.

The stream API is a powerful tool that can be used to perform operations on collections in a declarative way. It is remarkable change for any Java programmer.

Java Records are a special kind of class introduced in Java 14, established as a standard feature in Java 16.

They are designed to encapsulate data, generating private final fields, an all-args constructor and the necessary methods for any regular class: public getters or accessor method, equals(), hashCode() and toString(). Setters are not generated, because the data are immutable.

Records extend the java.lang.Record class, therefore they cannot extend any other class. And they can't be extended -they are final classes-.

record Person(String name, int age) { }

is equivalent to:

class Person {
    private final String name;
    private final int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public String name() { return name; }
    public int age() { return age; }

    @Override
    public String toString() {
        // Implementation 
    }

    @Override
    public boolean equals(Object o) {
        // Implementation 
    }

    @Override
    public int hashCode() {
        // Implementation 
    }
}

As we can see, records take out the verbosity of traditional Java classes.

Although IDEs can automatically generate these methods, the class has to be updated every time a new field is added.

Immutable Data

Record fields are immutable, which means that once created, they cannot be changed. Using the Person record declared above:

Person person1 = new Person("Jose", 30);

The following code will cause a compilation error:

person1.age = 22;

This immutability makes it easier to reason about the state of the objects and makes testing easier. However, this rule only applies to scalar fields. If there is a non-primitive or mutable field, its element can be modified:

record Person(String name, List<String> friends) { }

Elements of the friends list can be modified.

Constructors

The all-arguments constructor is generated as shown above. It's also called the canonical constructor.

The explicit constructor is called compact constructor, and it allows developers to add custom logic during object initialization. A common use case is implementing validation rules.

record Person(String name, int age) {
    // Unlike a class constructor, there is no a parameter list. 
    public Person {
        Objects.requireNonNull(name);
        Objects.requireNonNull(age);
        if (age < 0) {
            throw new IllegalArgumentException("Age must be a positive number.");
        }
    }
}

Records can have a default constructor that initializes all components to their default values. This must delegate to the canonical constructor:

record Person(String name, int age) { 
    public Person {
        // call to the canonical constructor
        this("Jose", 33);
    }
}

// Usage
Person person = new Person();  // name = "Jose", age = 33

Custom constructors can also be created by mixing the canonical constructor and default constructors.

public record Person(String name, int age) {

    public Person(int age) {
        this("Jose", age);
    }
}

// Usage
Person person = new Person("Philip", 52)
Person person = new Person(33);  // name = "Jose", age = 33

This mimics the behaviour of languages thas has default values for their constructor parameters.

Accessing Records Components

The dot notation is used, as in any other class, but followed by the field name.

record Person(String name, int age) { }
Person person = new Person("Jose", 33);
String name = person.name();
int age = person.age();

The parentheses indicate that a getter method is being called.

Overriding Methods

The toString, equals and hashCode methods can be overridden.

Implementing Methods inside Records

As with regular classes, static variables and methods can be defined inside records.

For example, something very close to a factory method can be achieved

record Person(String name, int age) {
    public Person withName(String name) {
        return new Person(name, age);
    }
}

// Usage
Person person = person.withName("Jose");
Person otherPerson = person.withName("Philip");

or a validation method

record Person(String name, int age) {
    public boolean isAdult() {
        return age >= 18;
    }
}

// Usage
Person person = new Person("Jose", 33);
boolean isAdult = person.isAdult(); // true

How to ensure that Records are immutable

Use defensive copies

record Person(String name, List<String> friends) { }

List<String> friends = new ArrayList<>();
Person person1 = new Person("Jose", friends);
friends.add("Philip");
friends.add("Steve");

Person person2 = new Person("Jose", List.copyOf(friends);
person.friends().add("Mafalda");

When to use Records

Use records for simple data carriers where immutability is required. For example, to represent configuration settings or for Data Transfer Objects (DTO) in RESTful services.

Disadvantages of Records

• Records are final, which means they cannot be extended. This might be a limitation to use some Java frameworks.

• The mixture of traditional classes and records is a bit confusing, since the getters do not use the same notation.

• Being all the fields final might not be what we want in some cases. In languages like Kotlin, you can choose if a given field is going to be immutable:

// age is a mutable field and name is immutable
data class Person(val name: String, var age: Int)

Using Records with JPA

Entities are classes that are mapped to a database table. In popular JPA providers like Hibernate, entities are created and managed using proxies. Proxies are classes that extend the entity class, relying on the entity to have a no-args constructor and setters. Since records do not have setters and are final, they can't be used as entities.

However, starting with version 6.2, Hibernate supports record classes as embeddables.

@Embeddable
public record Person(String name, int age) { }

This annotation tells the persistence provider that this class can be embedded into entity objects.

@Entity 
public class User {

    @Id
    @GeneratedValue
    private Long id;

    @Embedded
    private Person person;

    private String email;
    ................
}

Take into account that the information represented by the record is immutable.

EntityManager entityManager = emFactory.createEntityManager();

User user = entityManager.find(User.class, userId);
// user.person.name and user.person.age are immutable

Conclusion

• Java records make data class construction much easier than traditional POJOs, resulting in a much more readable code.

• The syntax for records contructors is different from regular classes.

• All the record member fields are immutable, but be careful when dealing with non-primitive data types whose elements might be modified.

• Records could not be used as entities, but this has changed in recent JPA versions.

Bibliography

• https://reflectoring.io/beginner-friendly-guide-to-java-records/

• https://www.baeldung.com/java-record-keyword

• https://thorben-janssen.com/java-records-embeddables-hibernate/

In Java, a Supplier is a functional interface introduced in Java 8 as part of the functional programming API, as explained in my previous article.

It is an interface that takes no arguments and produces a result of a specific type. Its abstract method is called get().

@FunctionalInterface 
public interface Supplier<T> { 
    T get();
}

Usage:

Supplier<Double> randomSupplier = () -> Math.random();
Double randomValue = randomSupplier.get();

But when is providing a value without taking any input useful?

Factory methods

public interface Shape {
   void draw();
}

public class Circle implements Shape {
    @Override
    public void draw() {
        System.out.println("Drawing a circle");
    }
}

public class Rectangle implements Shape {
    @Override
    public void draw() {
        System.out.println("Drawing a rectangle");
    }
}

Factory pattern using Supplier:

final static Map<String, Supplier<Shape>> map = new HashMap<>();
static {
    map.put("circle", () -> new Circle());  
    map.put("rectangle", () -> new Rectangle());
}

The whole factory class is:

public class ShapeFactory {
    final static Map<String, Supplier<Shape>> map = new HashMap<>();
    static {
        map.put("circle", Circle::new);
        map.put("rectangle", Rectangle::new);
    }

    public Shape getShape(String shapeType) {
        Supplier<Shape> shape = map.get(shapeType.toLowerCase());
        if (shape != null) {
            return shape.get();
        }
        throw new IllegalArgumentException("Invalid shape type: " + shapeType.toLowerCase());
    }
}

The drawback of this technique is that it does not scale well if the factory method getShape needs to take multiple arguments to pass on to the Shape constructors.

Stream API

The generate and iterate methods in the Stream API receive a Supplier as parameter:

Supplier<Double> randomSupplier = () -> Math.random();
Stream.generate(randomSupplier)
    .limit(10)
    .forEach(System.out::println);

It can be simplified using method references:

Stream.generate(Math::random)
    .limit(10)
    .forEach(System.out::println);

Lazy initialization

It is a design pattern where the creation of an object or computation of a value is deferred until it is needed. This technique improves performance and reduces memory usage, because it avoids unnecessary computations.

// Eager initialization
String eagerValue = "Eager Initialization";

// Lazy initialization using Supplier
Supplier<String> lazyValueSupplier = () -> "Lazy Initialization";

// Value is not created until get() is called
System.out.println("Before accessing lazy value");
System.out.println(lazyValueSupplier.get()); // Output: Lazy Initialization

The example is useless, but let's imagine a heavy computation task instead of a single String. For this case, it is useful to ensure the object is created only once (memoization).

Let's create a custom wrapper class for this:

public class Lazy<T> {
    private final Supplier<T> supplier;
    private T value;

    public Lazy(Supplier<T> supplier) {
        this.supplier = supplier;
    }

    public T get() {
        if (value == null) {
            value = supplier.get();
        }
        return value;
    }
}

It is called like that:

Lazy<String> lazyValue = new Lazy<>(() -> "Computed Value");

System.out.println("Before accessing lazy value");
System.out.println(lazyValue.get()); // Output: Computed Value

The syntax for creating a Lazy object in Java is verbose, since it's not a built-in class. In other JVM languages a variable can be declared lazy. For example, in Scala:

lazy val lazyValue = "Computed Value"

Generating an infinite list

This is an application of lazy evaluation. It's a quite common case.

 // Generate an infinite stream of random numbers
Stream<Double> infiniteStream = Stream.generate(Math::random);
// Take the first 5 elements and print them
infiniteStream.limit(5).forEach(System.out::println);

// Generate an infinite stream of integers starting from 1
Stream<Integer> infiniteStream = Stream.iterate(1, n -> n + 1);
// Take the first 5 elements and print them
infiniteStream.limit(5).forEach(System.out::println);

Scala's native support for laziness makes it more idiomatic for such tasks:

val infiniteList = LazyList.continually(scala.util.Random.nextDouble())
// Take the first 5 elements and print them
println(infiniteList.take(5).toList)

Lazy Evaluation in Kotlin

// Generate an infinite sequence of integers starting from 1
val infiniteSequence = generateSequence(1) { it + 1 }
// Take the first 5 elements and print them
println(infiniteSequence.take(5).toList())

In general, the sequence function is a builder needed for creating sequences lazily.

val randomNumbers = sequence {
    while (true) {
        yield(Random.nextDouble())
    }
}

// Take the first 5 random numbers and print them
println(randomNumbers.take(5).toList())

Custom extension functions can be defined to create infinite sequences for specific use cases. This allows Kotlin to mimic the functional Scala syntax:

fun Int.toInfiniteSequence(): Sequence<Int> = generateSequence(this) { it + 1 }

fun main() {
    // Create an infinite sequence starting from 10
    val infiniteSequence = 10.toInfiniteSequence()

    // Take the first 5 elements and print them
    println(infiniteSequence.take(5).toList()) 
}

Summary

Suppliers are an important part of functional programming in Java.

They have two main use cases:

• To encapsulate the logic of value generation.

• To allow separating the definition of how a value is generated from when that value is needed. This technique is called lazy evaluation and it's more easily implemented in Scala and Kotlin.

A lambda expression or anonymous method is a shortcut to define an implementation of a functional interface.

It has the following syntax:

(parameters) -> {statements/s}

(Integer number) -> {
    return number * 2;
}

The parameter type can be inferred:

(number) -> {
    return number * 2;
}

Since the method body is a single expression, the curly braces and the return keyword are not necessary.

(number) -> number * 2;

If there is only one parameter, the parentheses can be omitted:

number -> number * 2;

Now we have a very -maybe too much- compact lambda expression. But how do we use it ?

function duplicate(int number) -> number * 2;  // Invalid code

and then we might want to invocate the function:

duplicate(3); // Invalid code

But this does not work, function is not a Java keyword. There are only classes and interfaces in Java. In order to maintain its famous backward compatibility, the language designers decided to relate lambdas with ordinary interfaces:

@FunctionalInterface
public interface MyFunction {
    int duplicate(int number);
}

We can finally write a valid lambda expression:

public class MyClass implements MyFunction { 
    MyFunction myFunction = (number) -> number * 2;
    ...........................................
}

and call it:

System.out.println(myFunction.duplicate(3)); // 6

We can now understand the definition given in the beginning of this article:

A lambda expression or anonymous method is an implementation of a functional interface. It was introduced in Java 8.

A functional interface is an interface that contains only one abstract method. Also called SAM ("single abstract method") interface.

The @FunctionalInterface annotation is used to mark interfaces that only have one abstract method. It is not required, since there might be SAM interfaces declared in earlier Java versions.

@FunctionalInterface   // This annotation is optional, but recommended
public interface MyFunction {
    int duplicate(int number);
}

In other words, the implementation of the abstract method of a functional interface is the equivalent to a function in other languages. In a modern JVM language like Kotlin, this is the equivalent code:

fun duplicate(number: Int): Int {
    return number * 2
}

Function Types

Do we have to write a functional interface every time we want to use a lambda expression ? No, because Java provides a series of pre-defined functional interfaces called function types.

Function<T, R> and friends

These functional interfaces represent functions that take a parameter of type T and return a result of type R.

Function<Integer, Integer> duplicate = x -> x * 2;
System.out.println(duplicate.apply(3));     // 6

Notice the parameters are not primitive types, but objects.

Equivalent code in Kotlin:

fun duplicate(x: Int): Int {
    return x * 2
}

It is probably more clear in Kotlin or Scala, but you can get used to it. In my opinion, Java language designers did a good work to maintain the backwards compatibility. However, using these pre-defined function types makes you to have to learn a number of other functional interfaces and their corresponding default methods.

Default methods are provided for the Function interface: andThen() and compose()

Function<Integer, Integer> duplicate = x -> x * 2;
Function<Integer, Integer> addOne = x -> x + 1;
Function<Integer, Integer> duplicatePlusOne = duplicate.andThen(addOne);
System.out.println(duplicatePlusOne.apply(3));     // 7

That code is equivalent to this one:

Function<Integer, Integer> duplicate = x -> x * 2;
Function<Integer, Integer> addOne = x -> x + 1;
Function<Integer, Integer> duplicatePlusOne = addOne.compose(duplicate);
System.out.println(duplicatePlusOne.apply(3));     // 7

BiFunction<T, U, R> and friends

These functional interfaces represent functions that take two parameters of type T and U and return a result of type R.

BiFunction<Integer, Integer, Integer> add = (x, y) -> x + y;
System.out.println(add.apply(3, 4));     // 7

Other pre-defined function types

UnaryOperator<Integer> square = (x) -> x * x;
System.out.println(square.apply(3));     // 9

BinaryOperator<Integer> add = (x, y) -> x + y;
System.out.println(add.apply(3, 4));     // 7

and when a primitive data type is returned:

• ToIntFunction - takes a T and returns an int.

• ToLongFunction - takes a T and returns a long.

• ToDoubleFunction - takes a T and returns a double.

The Function interface is for operations that take a single parameter and return a single value, while the BiFunction interface is designed for operations that take two parameters.

Predicate<T>

This functional interface represents functions that take a parameter of type T and return a boolean value. It's mainly used for filtering and evaluating conditions.

Predicate<Integer> isEven = x -> x % 2 == 0;
boolean result = isEven.test(4); // true

The Predicate interface also provides several default methods: and(), or(), negate():

Predicate<Integer> isEven = x -> x % 2 == 0;
Predicate<Integer> isGreaterThan10 = x -> x > 10;
Predicate<Integer> isEvenAndGreaterThan10 = isEven.and(isGreaterThan10);
boolean result = isEvenAndGreaterThan10.test(12); // true

Predicate<String> containsA = str -> str.contains("A");
Predicate<String> containsB = str -> str.contains("B");
Predicate<String> containsEither = containsA.or(containsB);

Predicate<Integer> isEven = x -> x % 2 == 0;
Predicate<Integer> isOdd = isEven.negate();

Consumer<T>

It's a functional interface that takes a parameter of type T and performs an action without returning a value.

Consumer<String> greeting = s -> System.out.println(s);
greeting.accept("Hello, World!");

In my opinion, the above default method could have been called apply() in order to be consistent with the Function function type.

The Consumer interface also provides the default method andThen(), which allows for chaining multiple Consumer operations. This is similar to the and() method of the Function interface seen above.

Supplier<T>

It's a functional interface that returns a value of type T without taking any input arguments. It's the oppossite of the Consumer. It has a single abstract method called T get().

Supplier<String> supplier = () -> "Hello, World!";
System.out.println(supplier.get());

Suppliers are useful to generate values in a lazy way. The exact meaning of this deserves its own article.

Method References

Besides lambdas, Java 8 introduced method references, which are a way to refer to a method without having to specify the full method signature.

Consumer<String> greeting = s -> System.out.println(s);
Consumer<String> greeting = System.out::println;
greeting.accept("Hello, World!");

The general syntax for method references is ClassName::methodName, where ClassName is the name of the class containing the method and methodName is the name of the method to be called.

This is especially useful when using custom classes:

class Employee {
    String getName() {
        return name;
    }
    ......................
}

With method references we can do this:

Consumer<Employee> printName = employee -> employee.getName();
Consumer<Employee> printName = Employee::getName;

Constructor References

Instead of

Supplier<Employee> employee = () -> new Employee();

use

Supplier<Employee> employee = Employee::new;

Lambda expressions and Streams

In conjunction with lambdas, Streams provide a way to process sequences of data elements in a functional style. Streams allow to perform operations like filtering, mapping, and reducing on data, making the code much more concise and readable.

List<Integer> numbers = Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
int sumOfEvenSquares = numbers.stream()
    .filter(number -> number % 2 == 0)
    .map(number -> number * number)
    .reduce(0, Integer::sum);

System.out.println("Sum of squares of even numbers:" + sumOfEvenSquares);

There is much more to explain about the Streams API, but this is enough to show how they use lambda expressions.

Lambda Expressions in other Java packages

In addition to the function types, there are more pre-defined functional interfaces in other Java libraries.

@FunctionalInterface
public interface Comparator<T> {
    int compare(T obj1, T obj2);
}

The abstract method above compares its two arguments for order. Returns a negative integer, zero, or a positive integer if the first argument is less than, equal to, or greater than the second. (Source: Comparator official docs)

When using custom classes, we probably have to create our own Comparator:

public class EmployeeComparator implements Comparator<Employee> {
    @Override
    public int compare(Employee empl1, Employee empl2) {
        return Integer.compare(empl1.getAge(), empl2.getAge()); 
    }
}

The Comparator interface has a number of default and static methods that can be used with lambda expressions.

Functional Interfaces before Java 8

Although the term functional interface was introduced in Java 8, there were a number of interfaces with a single abstract method in earlier Java versions.

For example, the Comparator interface was declared in the same way, but without using the @FunctionalInterface annotation.

The main difference is that the Comparator interface was implemented using anonymous inner classes:

Collections.sort(employeeList, new Comparator<Employee>() {
    @Override
    public int compare(Employee e1, Employee e2) {
        return e1.getName().compareTo(e2.getName());
    }
});

This was more verbose than the lambda expressions.

Conclusion

We have explained lambda expressions and functional interfaces, features introduced in Java 8. Then we explained the different function types, which allow us to create powerful transformations of data. Method references provide a shorthand for lambda expressions, making our code even more readable.

A small comparison with the equivalent code used with anonymous classes allows us to observe how powerful the lambda expressions are when used with pre-defined functional interfaces.

Optional is a class introduced in Java 8 to handle null values in order to avoid the dreadful NullPointerException (NPE). It is a wrapper class that can be used to represent a value that may be null or not.

Before Java 8, developers had to use null checks to handle null values.

Let's say we have a method that returns an employee from a database.

public static void main(String[] args) {
    var employee = getEmployee("John");
}

public Employee getEmployee(String name) {
    Employee employee = getEmployeeByName(name);

    if (employee != null) {
        return employee;
    } else {
        return throw new IllegalArgumentException("Employee not found");
    }
}

This is the equivalent code with Optional.

public static void main(String[] args) {
    var employee = getEmployee("John");
}

public Optional<Employee> getEmployee(String name) {
    Optional<Employee> employee = getEmployeeByName(name);

    if (employee.isPresent()) {
        return employee.get();
    } else {
        return employee.orElseThrow(() -> new IllegalArgumentException("Employee not found"));
        // return Optional.of(new Employee());    // or return a default employee
        // return Optional.empty();               // or return an empty optional
    }
}

But, wait! what is the point of the Optional class if we can achieve the same result using a null check?

There is a subtle difference: when a method returns an Optional, that method is indicating that it may or may not return a value. So you have to be prepared to handle both cases. But that is not a big improvement over the null check.

Real improvements with Optional

The Optional API provides additional methods.

public static void main(String[] args) {
    var employee = getEmployeee("John");
}

The orElse() method returns the wrapped value or the provided value as if the optional is empty. It's preferred over the get() and isPresent() methods.

public Optional<Employee> getEmployeee(String name) {
    return getEmployeeByName(name)
               .orElse(new Employee());
}

Chaining stream operations

Let's try to retrieve an employee age from the database using null checks.

public int getEmployeeAge(String name) {
    Employee employee = getEmployeeByName(name);

    if (employee != null) {
        if (employee.getAge() != null) {
            return employee.getAge();
        } else {
            return throw new IllegalArgumentException("Employee age is null");
        }
    }
}

It's a bit ugly and cumbersome. More important, forgetting one null check can cause a NPE. The code above can be simplified by chaining stream operations.

The Optional API provides a much more robust code.

public Optional<Integer> getEmployeeAge(String name) {
    Optional<Employee> optionalEmployee = getEmployeeByName(name);
    return getEmployeeByName(name)
               .map(Employee::getAge)
               .orElse(0);
}

We might want to throw an exception if the age is null.

public Optional<Integer> getEmployeeAge(String name) {
    return getEmployeeByName(name)
               .map(Employee::getAge)
               .orElseThrow(() -> new IllegalArgumentException("Employee age is null"));
}

Do not overuse Optional

Optional can also be used for method parameters, but it does not make any sense. It shoul be used only for method return values.

// Strange use of Optional
public Optional<Integer> getEmployeeAge(Optional<String> name) {
    ..................
}

Bonus: how other languages handle null values

Scala

Scala, one important JVM language, uses the Option class, which is a wrapper class.

def getEmployeeAge(name: String): Option[Int] = {
  val employee = getEmployeeByName(name)
  employee.map(_.age)
}

Kotlin

Other languages use an operator instead of a wrapper object to handle null values. In Kotlin the ? is called the safe call operator.

// In Kotlin the returned data type is put after the semicolon
fun getEmployeeAge(String name): Int? {
    val employee = getEmployeeByName(name)
    return employee?.age // similar to `orElse(null)` in Java
}

If you want to provide a default value, you can use the ?: operator.

val age = getEmployeeAge("John") ?: 0  // similar to `orElse(0)` in Java

Outside the JVM world, C# also uses the ? or null-conditional operator to indicate that a variable may be null.

C#

public int? GetEmployeeAge(string name) {
    var employee = GetEmployeeByName(name);
    return employee?.Age;
}

Conclusion

As we saw, Optional is not just a replacement for null checks. It is a wrapper class that can be used to represent a value that may be null or not. We can appreciate its real power when we chain stream operations. The Optional methods get() and isPresent() are discouraged to use. So much that the language designers regret having creating them.

Other languages like Kotlin and C# use the ? operator to handle null values. Scala provides a similar solution.

In npm's Node JS, the same dependency or library may have different versions depending on the various parts of an application.

But Java and its build tools are not designed to support using two different versions of the same library at runtime. If you want multiple versions at the same time, at runtime, then you need to do classloader tricks.

What are dependency conflicts

Also called dependency hell, these terms refer to the conflict caused by using different versions of the same library, as shown above.

<!-- Project dependencies -->
    <dependencies>
        <dependency>
            <groupId>org.example</groupId>
            <artifactId>study-maven-2</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>org.example</groupId>
            <artifactId>study-maven-3</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>

<groupId>org.example</groupId>
    <artifactId>study-maven-2</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>30.1.1-jre</version>
        </dependency>
    </dependencies>

<groupId>org.example</groupId>
    <artifactId>study-maven-3</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>29.0-jre</version>
        </dependency>
    </dependencies>

In this example, only one version of Guava will be imported, but which one ?

Before answering this question, we need to explain briefly another concept.

The dependency graph

A dependency graph is a graph that represents dependencies and the relations among them.

The two most used build tools -Maven and Gradle- have a very helpful tool to present all dependencies and their versions:

mvn dependency:tree -Dverbose

gradle dependencies

Resolution strategy

The strategy used to select which library version is chosen in runtime is different in Apache Maven and in Gradle.

Apache Maven

Maven uses a nearest first strategy.

It will take the shortest path to a dependency and use that version. In case there are multiple paths of the same length, the first one wins.

The main drawback of this method is that it is ordering dependent. Keeping order in a very large graph can be a challenge. For example, what if the new version of a dependency ends up having its own dependency declarations in a different order than the previous version? This could have unwanted impact on resolved versions.

Gradle

By default, Gradle will select the highest version for a dependency when there's a conflict.

You can force a particular version to be used with a custom resolutionStrategy. More info in the Gradle docs

configurations.all {
 resolutionStrategy { force 'com.google.guava:guava:15.0' } 
}

This does not add a dependency on guava 15.0, but forces the use of 15.0 if there is a dependency (even transitively).

Conclusion

This was a very short article that introduced some basic concepts in Java dependency management.

We will explain some solutions in the next part of these series.

References and Further Reading

• https://www.baeldung.com/maven-dependency-graph

• https://liam8.github.io/2021/09/24/How-to-solve-dependency-conflicts-with-Maven/

• https://docs.gradle.org/current/userguide/dependency_resolution.html

• https://www.baeldung.com/maven-version-collision