Read the entire book below

Practical Vavr is a clearly structured overview of basic functional programming concepts with Vavr. There are many examples in this book to help you understand most of the existing Vavr APIs.

I like the pointers Alexandre gives about my design decisions and how he puts topics in a larger context.

This is a book I am recommending to all Vavr users. It is a great introduction to Vavr for beginners and an everyday reference for experts.

Daniel Dietrich, Creator of Vavr

Vavr

Vavr (formerly called Javaslang) is a functional library for Java.

As stated from the official repository of Vavr:

Vavr is an object-functional language extension to Java 8, which aims to reduce the lines of code and increase code quality. It provides persistent collections, functional abstractions for error handling, concurrent programming, pattern matching, and much more.

Vavr fuses the power of object-oriented programming with the elegance and robustness of functional programming. The most interesting part is a feature-rich, persistent collection library that smoothly integrates with Java's standard collections.

Because Vavr does not depend on any libraries (other than the JVM) you can easily add it as standalone .jar to your classpath.

To sum up, it's a Java library that helps to reduce the amount of code and to increase the robustness, using concepts from functional programming, immutable values, and control structures to operate on these values.

Vavr has been originally developed by Daniel Dietrich and was released in March 2014.

Why

Have you heard about Functional Programming, or have you been attracted by it but still need to use Java? Do you want to write more robust code, but in a different way, a more elegant way? Do you want a library that gives you all these well-thought building blocks in a well-organized API?

Well, Vavr is the library you need. It can improve your code, give you confidence in writing it, make you design your business code better, and can prevent you from falling into programming traps and all kinds of exceptions.

How

Using Vavr

The latest released version as the date I'm writing these lines is 0.10.5.

If you are using Maven just add the following dependency to your pom.xml file

<dependencies>
    <dependency>
        <groupId>io.vavr</groupId>
        <artifactId>vavr</artifactId>
        <version>0.10.5</version>
    </dependency>
</dependencies>

If you are using Gradle, just add the following dependency to your build.gradle file

dependencies {
    compile "io.vavr:vavr:0.10.5"
}

And finally, if you're not using any build system, you can just download the latest version and drop the JAR in your classpath.

That's it, you're ready to rock some code in your favorite code editor or IDE and benefit instantly from the features of Vavr.

This book

Why

I have been using Vavr before it was called Vavr, I discovered it beginning of 2015, and have been using it pretty extensively since then.

As a Tech Lead and Software Craftsman in my day to day job, I like to promote this library to help developers write less and safer code with better quality, understand functional programming idioms and how to apply them in their work.

I've been teaching this library for multiple years, and developers always tend to have the same set of questions on how to get going with it, when to use it, also how and why to use it.

This book will cover what I think are the best parts of Vavr, how the API works, and what it has to offer in your real world day-to-day programming.

Code samples

Code example will be using Java 15 with preview enabled so that we can benefit from features like the new instanceof syntactic sugar, and from records to avoid Lombok when not necessary.

The code is available on my github/agrison.

About me

My name is Alexandre, I am a Software Engineer from Metz in France and working as a Tech Lead and Software Craftsman in Luxembourg.

In my spare time, I like to code in various languages including Java (with Vavr), Clojure/ClojureScript, Kotlin, JavaScript, Go, Python, OCaml, and a few others. I'm interested in both backend and frontend having practiced them extensively.

From APIs to mobile, through the cloud and databases, preferably using a functional programming language.

Besides coding, I am passionate about my wife Jessica, my daughter Eva and my son William, I also love to travel and practice photography.

You can find me at grison.me and on Twitter at @algrison.

The cover

The book's cover is a picture of Metz at sunrise as seen from the Plan d'eau.

It features the Cathedrale Saint Etienne de Metz on the left, which is the Cathedral having one of the highest naves in the world and the largest expanse of stained glass in the world.

Besides, on the right you'll see a Torii - a traditional Japanese gate - which was installed around 1985 (the year I was born) during a Japanese exposition in Metz.

If you happen to be visiting Metz, don't hesitate to drop me a message :)

Thank you

Thank you to all the readers, especially to Mikalai Zaikin for the great feedback and help he provided regarding typos and sentences improvements.

Table of Content

• Tuple
• Option
• Either
• Try
• Lazy
• Future
• Match
  • Patterns
  • Predicates
• Validation
• Functions
• Collections
• Sequences
• Sets
• Maps
• Folding and reducing Maps
• Streams
• Vavr in action
  • Try: a real world example
  • The Gilded Rose Kata
  • From HTTP to the Database, and back
  • Analysing football data
  • Advent Of Code
• Vavr Matchers
• Vavr and Kotlin
• Vavr and Property Testing

Tuple

Let's say you want to create a collection of heterogeneous elements. A small collection going from 0 to 8 elements.

Of course, you can create a custom class or record for it, however, sometimes you don't need or want to.

Here comes the Tuple type. Vavr's Tuples are immutable and are of type Tuple0, Tuple1, Tuple2, …, Tuple8.

Creating Tuples

In order to create a Tuple, just use the factory method Tuple.of().

var t = Tuple.of("Alex", 36); // Tuple2

Notice that this Tuple contains two different types, one String and one Integer.

record Customer(String name, int age) {}

var t = Tuple.of(42, "Hello", new Customer("Alex", 36)); // Tuple3
t._1; // 42
t._2; // "Hello"
t._3; // Customer(name = "Alex", age = 36) 

// you can also use _N as a method
t._1(); // 42
t._2(); // "Hello"
t._3(); // Customer(name = "Alex", age = 36) 

In this example, the Tuple contains three elements, one Integer, one String, and one Customer.

Finally, you can also create a Tuple2 from a Map.Entry.

var t = Tuple.of(new SimpleEntry(42, "foo"));

Creating Tuples from Iterables

You can create an instance of Tuple with an Iterable of tuples using the sequenceN method, where N refers to the size of the Tuple.

List<Tuple2<Integer, String>> list = Arrays.asList(
    Tuple.of(1, "foo"), Tuple.of(2, "bar"));

var t = Tuple.sequence2(list); // Tuple2(Seq(1, 2), Seq("foo", "bar"))

Note that it returns a TupleN<Seq<T1>, ...> but implementation related the Seq are of type Stream.

Accessing elements

Each TupleN implementation will provide a _N accessors to let you get the element. You can also use the _N() method to access it.

Mapping a tuple

There are two ways to map a function, providing N functions:

var t = Tuple.of("Alex", 36);
var newTuple = t.map(String::toUpperCase, age -> ++age);
newTuple._1(); // "ALEX"
newTuple._2(); // 37

// t stays unchanged
t._1(); // "Alex"
t._2(); // 36

or one with N-arities.

var t = Tuple.of("Alex", 36);
var newTuple = t.map((name, age) -> Tuple.of(name.toUpperCase(), ++age));

newTuple._1(); // "ALEX"
newTuple._2(); // 37

// t stays unchanged
t._1(); // "Alex"
t._2(); // 36

If you only need to map a specific Tuple element you can use mapN() where N is the element position.

var t = Tuple.of("Alex", 36);
var newTuple = t.map2(age -> ++age); 
newTuple._1(); // "Alex"
newTuple._2(); // 37

// t stays unchanged
t._1(); // "Alex"
t._2(); // 36

Updating a Tuple

Vavr offers an updateN() method, where N is the element position to update.

var t = Tuple.of("Alex", 36);
var newTuple = t.update2(50);

newTuple._1(); // "John"
newTuple._2(); // 50

It is similar to mapN except that mapN takes a Function whereas updateN takes directly the value to update the tuple element with.

Transforming Tuples

If you want to transform a Tuple to a new type, there's the apply method for that.

var t = Tuple.of("Alex", 36)

var hello = t.apply((name, age) -> "My name is " + name + " and I'm " + age + 
    " years old");

System.out.println(hello); 
// "My name is Alex and I'm 36 years old"

Getting the size

If you want to retrieve the size of a Tuple instance, just ust the arity method.

var t = Tuple.of("Alex", 36);
t.arity(); // 2

Growing Tuples

Let's say you want to grow your Tuple from 2 to 3 elements, then use the append method.

record Address(String street, String city) {}

var t = Tuple.of("Alex", 36);
var newTuple = t.append(new Address("rue Serpenoise", "Metz"));
newTuple.arity(); // 3
newTuple._3(); // Address(street = "rue Serpenoise", city = "Metz")

Vavr also offers the possibility to concat tuples, it's like append but with other tuples.

record Address(String street, String city) {}
record Nationality(String nationality, String birthPlace) {}

var t = Tuple.of("Alex", 36);
var p = Tuple.of(new Address("rue Serpenoise", "Metz"),
                 new Nationality("French", "Paris"));
var newTuple = t.concat(p);
newTuple.arity(); // 4
newTuple._3(); // Address(street = "rue Serpenoise", city = "Metz")
newTuple._4(); // Nationality(street="French", birthPlace="Paris")

Converting to a sequence

Instances of Tuple can be converted to a Seq using toSeq() (with a List implementation).

var t = Tuple.of("foo", "bar", "bazz");
t.toSeq(); // Seq(foo, bar, bazz)

Hashing objects

This comes as a practical utility, the Tuple type has a method hash which will compute a hash of all the given objects.

int h = Tuple.hash("foo", "bar"); // ...

Which is equivalent to:

(31 * (31 + Objects.hashCode("foo")) + Objects.hashCode("bar"))

Tuples and Maps

Tuples are used by Vavr to represent and work with entries in a Map collection, thus you can create a Map from a Tuple, iterate on Tuples representing each entry of the Map, get the first and last elements as a Tuple, and much more, but we'll see about this in the Collections chapter.

In its io.vavr.control package, Vavr provide useful values like Option, Either and Try. These values share similar APIs and as such, some operations are valid on these 3 types.

You will then find similarities in the following sections.

Option

The Option type from Vavr is a replacement for Java's Optional. It is referred to as a monadic container type which represents an optional value.

Instances of Option are either an instance of Some or None.

The API is similar to the one of Optional and what can be found in languages like Scala or Haskell.

Creating an Option

While Java offers both of and ofNullable to create an Optional, Vavr offers only of. An Option created with of cannot hold a null, consider Option.of similar to Optional.ofNullable.

If you

var o1 = Option.of("foo"); // Option<String>
var o2 = Option.some("foo"); // Option<String>
o1.equals(o2); // true

You may also want to create an Option from a Java's Optional:

var o = Option.ofOptional(Optional.ofNullable(42));

Conditionally creating an Option

Vavr offers the when method to conditionally create an Option:

var i = 42
var o1 = Option.when(i % 2 == 0, "foo");
o1.isDefined(); // true
var o2 = Option.when(i > 0, () -> "foo");
o2.isDefined(); // true
var o3 = Option.when(i < 0, "bar");
o3.isEmpty(); // true

Creating an Option from a sequence

You can use the sequence method to create an Option from an Iterable of Options.

The resulting Option will hold the given values if all Options were defined, None otherwise.

var o1 = Option.sequence(List.of(Option.of(1), Option.of(2)));
o1.isDefined(); // true
o1.get(); // Seq(1, 2)

var o2 = Option.sequence(List.of(Option.of(1), Option.none(), Option.of(2)));
o2.isDefined(); // false

This is not to be confused with filtering a list for non defined Options.

Vavr also offers the traverse method which does exactly like the sequence method but provides a mapping on the sequence before rejecting them if they contain any empty Option.

// ensure we continue only if all the ints are positive
var o1 = Option.traverse(List.of(1, 2, 3), e -> Option.of(e > 0 ? e : null));
o1.isDefined(); // true
o1.get(); // Seq(1, 2, 3)

var o2 = Option.traverse(List.of(1, 2, -1, 3, -4), e -> Option.of(e > 0 ? e : null));
o2.isDefined(); // false

Checking the status of an Option

There are multiple ways to know if an Option is defined or not.

var o = Option.of("foo");
o.isDefined(); // true
o.isEmpty(); // false

Creating an Option holding null

Well, if you need such a thing (business-related), then you can do it like this:

var o = Option.some(null)
o.isDefined(); // true
o.get(); // null

But be aware of all the NullPointerException that might occurs later on.

Running side effects

You can run side effects when the Option is empty using onEmpty.

var r = new Random();
var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
o.onEmpty(() -> System.out.println("Bad Luck")); // maybe printing "Bad Luck"

The onEmpty method won't run any side effect if the Option is defined.

You may look at the Option API and see that there is no onDefined method, and you're totally right, this method is named peek, the API is different in that onEmpty takes a Runnable whereas peek takes a Consumer<T>, because the Option is defined and so you have to deal with the value it is holding.

var r = new Random();
var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
o.peek(i -> System.out.println("Feeling lucky: " + i)); // may print "Feeling lucky: 42"

Getting the value out of an Option

Try not using get without knowing if the Option is defined, otherwise it will crash on you. Use getOrElse or orElse to do so.

var age = Option.of(42).getOrElse(0); // 42
var age = Option.of(null).getOrElse(0); // 0

var alex = Option.of(null);
var eva = Option.of("Eva");
var cute = alex.orElse(eva); // Option(Eva)

The orElse method also supports a Supplier.

In case an Option being empty is critical and you need to crash, Vavr has got you covered with getOrElseThrow.

var r = new Random();
var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
var luckyNumber = o.getOrElseThrow(() -> 
    new RuntimeException("No losers in this Casino"));

Last option you have to get a value out of an Option is by using fold.

var r = new Random();
var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
var str = o.fold(() -> "Bad Luck", i -> "Feeling lucky: " + i);

The fold methods takes a Supplier and a Function. The Supplier is used to provide a value if the Option is empty, and the Function is used to compute a value from the Option, thus the three following forms are essentially the same:

var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
var s1 = o.getOrElse("Bad Luck");                      // both are
var s2 = o.fold(() -> "Bad Luck", Function::identity); // essentially the same

Use fold if you need to get the value out of a map by transforming it also, it's like doing a map just before a getOrElse.

var o = Option.of(r.nextBoolean() ? r.nextInt() : null);
var s1 = o.map(i -> "Feeling lucky: " + i).getOrElse("Bad Luck"); // both are
var s2 = o.fold(() -> "Bad Luck", i -> "Feeling lucky: " + i));   // the same

Filtering an Option

You may wish to set an Option to None if the value that it holds doesn't satisfy a given Predicate. In such a case, use the filter method.

var o = Option.of(41);
var even = o.filter(i -> i % 2 == 0);
even.isEmpty(); // true

var odd = o.filter(i -> i % 2 == 1);
odd.isDefined(); // true

Mapping an Option

Option is a powerful type to work with, and you may want to keep working with it until it makes sense to get the value out of this magical box. As said in the introduction of the chapter, Option is a monadic container, and as such it provides an API to transform what's inside the container, but it does so safely for you.

Indeed, if an Option is empty, mapping its content will have no effect at all.

var str = Option.of("alex")
              .map(String::toUpperCase)
              .getOrElse("Could not proceed");

In the following example I am using StringUtils from the commons-lang3 library:

<dependency>
           <groupId>org.apache.commons</groupId>
           <artifactId>commons-lang3</artifactId>
           <version>3.11</version>
</dependency>

You can use as many map as you want, and remember, mapping on an empty Option has no effect:

import org.apache.commons.lang3.StringUtils;

var str = Option.of(null)
              .map(StringUtils::reverse)
              .map(StringUtils::lowerCase)
              .map(StringUtils::capitalize)
              .map(s -> s.concat(" is enjoying Vavr"))
              .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

Now imagine that the Option was defined:

var str = Option.of("XELA")
              .map(StringUtils::reverse)
              .map(StringUtils::lowerCase)
              .map(StringUtils::capitalize)
              .map(s -> s.concat(" is enjoying Vavr"))
              .getOrElse("Could not proceed");
System.out.println(str); // "Alex is enjoying Vavr"

Monadic containers help you think in terms of pipeline of transformation, and keeping in mind the happy path, letting you handle the failure case when you need the value.

The code above is equivalent to:

var o = Option.of("XELA");
String s = "Could not proceed";
if (o.isDefined()) { // without Option you would check == null instead
   s = StringUtils.capitalize(
          StringUtils.lowerCase(StringUtils.reverse(o.get())))
       + " is enjoying Vavr";
}
System.out.println(s);

When accustomed to monadic containers, the first example looks better (I think) and conveys much more the business intent of the code which is:

1. try to reverse the string
2. then lowercase it
3. then capitalize it
4. then concatenate some other string with it
5. then get the final result
   1. but if any of this fails I want the Could not proceed string instead.

Mapping and nulls or other Option

As said earlier in this chapter, an Option can be either Some or None, but it can be a Some(null), and this can be problematic.

Let's see an example:

var str = Option.of("ALEX")
                .map(String::toLowerCase)
                .map(s -> s.length() < 10 ? null : s)
                .map(s -> s + " size is: " + s.length()) // BOOM: NullPointerException
                .getOrElse("Could not proceed");

Now this is where flatMap comes into action:

var str = Option.of("ALEX")
                .map(String::toLowerCase)
                .flatMap(s -> Option.of(s.length() < 10 ? null : s))
                .map(s -> s + " size is: " + s.length()) // no BOOM :-)
                .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

In the last example we encapsulated the possible null in an Option but to avoid dealing with an Option<Option<T>>, we used flatMap which gives an Option<T> if the inner Option was defined, None otherwise.

Transforming an Option

You can transform an Option to another type using transform.

var length = Option.of("foo").transform(o -> o.getOrElse("").length()); // int = 3

// wich is essentially the same as
var length = Option.of("foo").map(String::length).getOrElse(0);

Using with collectors

Interrop with the Java Collectors is provided via collect()

Option.of("foo").collect(Collectors.toList()); // List(foo)
// IntSummaryStatistics{count=1, sum=3, min=3, average=3, max=3}
Option.of("foo").collect(Collectors.summarizingInt(String::length));

Generally the collect method is available on most of Vavr's types.

Either

The Either object represents a value of two possible types. It's either a Left or a Right.

By convention a Left represents an error, and a Right a computed value.

Like Option, Either is a monadic container, and thus provide ways to transfrom the two branches that it holds, these transformations are safe in that trying to map on Left when the Either is Right will have no effect, same in the other way.

Creating an Either

Use left or right to create an Either instance.

var e1 = Either.left("foo"); // Left<String>
var e2 = Either.some("bar"); // Right<String>

Creating an Either from a sequence

You can use the sequence method to create an Either from an Iterable of Eithers.

If the Iterable contains any Left then sequence will return a Left with all the Lefts provided in the Iterable, otherwise it will return a Right with all the provided Rights.

var e1 = Either.sequence(List.of(
             Either.left("foo"), Either.right(1), Either.left("bar")));
e1.isLeft(); // true
e1.getLeft(); // Vector("foo", "bar")

var e2 = Either.sequence(List.of(
             Either.right(1), Either.right(2)));
e2.isRight(); // true
e2.getRight(); // Vector(1, 2)

Vavr provides also sequenceRight which is similar to sequence except that in case of any Left in the Iterable, it will return a Left containing the first Left value (in iteration order).

var e1 = Either.sequenceRight(List.of(
             Either.left("foo"), Either.right(1), Either.left("bar")));
e1.isLeft(); // true
e1.getLeft(); // "foo"

This is not to be confused with filtering a list of Either.

Vavr also offer the traverse and traverseRight method which does exactly like the sequence method but provides a mapping on the sequence before rejecting them if they contain any Left value.

// ensure we continue only if all the ints are positive
var e1 = Either.traverse(List.of(1, 2, 3),
              e -> e > 0 ? Either.right(e) : Either.left("bad: " + e));
e1.isRight(); // true
e1.getRight(); // Vector(1, 2, 3)

var e2 = Either.traverse(List.of(1, 2, -1, 3, -4),
              e -> e > 0 ? Either.right(e) : Either.left("bad: " + e));
e2.isLeft(); // true
e2.getLeft(); // Vector("bad: -1", "bad: -4")

var e3 = Either.traverseRight(List.of(1, 2, -1, 3, -4),
              e -> e > 0 ? Either.right(e) : Either.left("bad: " + e));
e3.isLeft(); // true
e3.getLeft(); // Vector("bad: -1")

Checking the status of an Either

There are multiple ways to know if an Either is Left or Right, using isLeft or isRight.

var e1 = Either.left("foo");
e1.isLeft(); // true
e1.isRight(); // false

Running side effects

You can run side effects when the Either is either Left or Right using peek and peekLeft.

var r = new Random();
var o = 10 > 0 ? Either.right(r.nextInt()) : Either.left("foo");
o.peek(i -> System.out.println("Feeling lucky:" + i)); // print "Feeling lucky: 42"
o.peekLeft(l -> System.out.println("Bad Luck: " + l)); // print nothing

• The peek method won't run any side effect if the Either is Left.
• The peekLeft method won't run any side effect if the Either is Right.

Additionally, Vavr provides the orElseRun method which let you run a side effect if the Either is a Left:

var r = new Random();
var o = 10 < 0 ? Either.right(r.nextInt()) : Either.left("foo");
o.orElseRun(l -> System.out.println("Bad luck:" + l)); // print "Bad luck: foo"

Getting the value out of an Either

Try not using get without knowing if the Either is a Right, otherwise it will crash on you. Use getOrElse, getOrElseGet or orElse to do so.

var handle = Either.right("Alex").getOrElse("Unknown"); // "Alex"
var handle = Either.left("Alex").getOrElse("Unknown"); // "Unknown"

Additionnally you can use fold :

var handle = Either.right("Alex")
                   .fold(l -> "Unknown", 
                         r -> "@" + r.toLowerCase()); // "@alex"

The orElse method supports also giving both an Either or a Supplier.

Either<String, String> isCool(String name) {
    return name.startsWith("E") ?
            Either.right(name) : Either.left("not cool: " + name);
}

var s = isCool("Alex")
           .orElse(isCool("Eva"))
           .fold(l -> "No one is cool",
                 r -> r + " is so cool")); // "Eva is so cool"

In case an Either being a Left is critical and you need to crash, Vavr has got you covered with getOrElseThrow.

isCool("Alex")
    .getOrElseThrow(() -> new RuntimeException("No losers in this Casino"));

Filtering an Either

You may wish to set an Either to Left if the value that an Either holds doesn't satisfy a given Predicate. In such a case, use the filterOrElse method.

var e = Either.right(41);
var even = e.filterOrElse(i -> i % 2 == 0, v -> "nope: " + v);
even.isLeft(); // true

var odd = e.filterOrElse(i -> i % 2 == 1, v -> "nope: " + v);
odd.isRight(); // true

Swaping an Either

You may wish to swap an Either, by making the Left its Right, and the other way:

var e = Either.right(41).swap();
e.isLeft(); // true

Mapping an Either (transforming what's inside)

Like Option, Either is a monadic container, and provides an API to transform what's inside the container, but it does so safely for you. Indeed, if an Either is Left, mapping its content will have no effect at all.

var str = Either.right("alex")
              .map(String::toUpperCase)
              .getOrElse("Could not proceed");

You can use as many map as you want, and remember, mapping on a Left has no effect:

var str = Either.left(null)
              .map(StringUtils::reverse)
              .map(StringUtils::lowerCase)
              .map(StringUtils::capitalize)
              .map(s -> s.concat(" is enjoying Vavr"))
              .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

Now imagine that the Either was Right:

var str = Either.right("XELA")
              .map(StringUtils::reverse)
              .map(StringUtils::lowerCase)
              .map(StringUtils::capitalize)
              .map(s -> s.concat(" is enjoying Vavr"))
              .getOrElse("Could not proceed");
System.out.println(str); // "Alex is enjoying Vavr"

Monadic containers help you think in terms of pipeline of transformation, and keeping in mind the happy path, letting you handle the failure case when you need the value.

The code above is equivalent to:

var e = Either.right("XELA");
String str = "Could not proceed";
if (e.isRight()) { // without Option you would check == null instead
   str = StringUtils.capitalize(
          StringUtils.lowerCase(StringUtils.reverse(o.get())))
       + " is enjoying Vavr";
}
System.out.println(str);

When accustomed to monadic containers, the first example looks better (I think) and conveys much more the business intent of the code which is:

1. try to reverse the string
2. then lowercase it
3. then capitalize it
4. then concatenate some other string with it
5. then get the final result
   1. but if any of this fails I want the Could not proceed string instead.

Since Either is like a two sided Option you can also map but on the Left with mapLeft.

Lastly, you can use bimap to map both sides dependently of which side the Either is representing.

Either<Exception, String> e = Either.right("Updated user.");
var status = e.bimap(Throwable::getCause, String::toUpperCase); // UPDATED USER.

Either<Exception, String> e = Either.left(new Exception("Database Error."));
var status = e.bimap(Throwable::getCause, String::toUpperCase); // Database Error.

Like Option, an Either supports flatMap.

Using with collectors

Interrop with the Java Collectors is provided via collect()

Either.left("foo").collect(Collectors.toList()); // List()
Either.right("foo").collect(Collectors.toList()); // List(foo)

Generally the collect method is available on most of Vavr's types.

Try

The Try control gives the developer the ability to write safe code without focusing on try-catch blocks in the presence of exceptions.

You can think of it as an Either where the Left is an Exception, but also using try-catch blocks behind the scene, so that you don't have to.

Try is a really powerful tool that you can use to write better code, right now.

Creating a Try

Use of to create a Try instance.

String crashes() {
    throw new RuntimeException("I like to crash");
}

var t1 = Try.of(() -> "foo"); // Success<String>
var t2 = Try.of(this::crashes); // Failure<RuntimeException>

The of method has different overloads so that you can give it a CheckedFunction0, a Supplier or a Callable.

The difference between a CheckedFunction0 and a Supplier is that the CheckedFunction0 declares that it can throw a Throwable.

Finally, you can create your own instances of Try using the success and failure methods.

var t1 = Try.success("foo"); // Success<String>
var t2 = Try.failure(new RuntimeException("bar")); // Failure<RuntimeException> 

Note that there is also ofCallable and ofSupplier to respectively create a Try from a Callable or a Supplier.

Using a Try to run a procedure

A procedure is a function returning nothing (void, think just printing to the console for example).

You can use Vavr's Try to run these safely also.

void crashes() {
    throw new RuntimeException("I like to crash");
}

var t1 = Try.run(() -> System.out.println("foo")); // Success<Void>
var t2 = Try.run(this::crashes); // Failure<RuntimeException>

Note that you can also use runRunnable to run a Runnable.

Checking the status of a Try

Use isSuccess or isFailure.

var t1 = Try.of(() -> "foo");
t1.isSuccess(); // true
t1.isFailure(); // false

Running side effects

You can run side effects when the Try is either a Success or a Failure using onSuccess, onFailure and peek.

var r = new Random();
var t = Try.of(() -> {
            if (10 > 0) return r.nextInt();
            else throw new RuntimeException("foo");
        });
t.onSuccess(i -> out.println("Feeling lucky:" + i)) // print "Feeling lucky: 42"
 .onFailure(l -> out.println("Bad Luck: " + l)); // print nothing

Notice that onSuccess and onFailure both return the Try instance so that you can continue to chain calls, and use these methods to do useful side effects (like logging for example).

• The onSuccess method won't run any side effect if the Try is Failure.
• The onFailure method won't run any side effect if the Try is Success.

Additionally, Vavr provides the orElseRun method which let you run a side effect in case the Try is a Failure:

var r = new Random();
var t = Try.of(() -> {
            if (10 > 0) return r.nextInt();
            else throw new RuntimeException("foo");
        });
t.orElseRun(l -> System.out.println("Bad luck:" + l)); // print "Bad luck: foo"

Chaining side effects

You can chain side effects using andThen and andThenTry.

var t = Try.of(() -> "foo")
           .andThen(Sytem.out::println); // Try<String>
// prints "foo"

Note that the difference between andThen and andThenTry is that andThenTry accepts CheckedConsumer and CheckedRunnable whereas andThen accepts Consumer and Runnable.

The difference between a CheckedConsumer and a Consumer is that the CheckedConsumer declares that the consumer can throws a Throwable whereas the Consumer interface does not.

If the CheckedConsumer was not offered in the API, then you would have to a wrap your method in a try-catch yourself.

private void log(String str) throws Throwable{
    if (new Random().nextBoolean()) {
        throw new IllegalStateException("Bad luck");
    }
    System.out.println("Logging: " + str);
}

// does not compile
Try.of(() -> "foo").andThen(s -> log(s));

// this compile, but it looks ugly
Try.of(() -> "foo")
        .andThen(s -> {
            try {
                log(s);
            } catch (Throwable e) {
                // do something  
            }
        });

// using andThenTry, it works fine
Try.of(() -> "foo").andThenTry(s -> log(s));

The same rules applies for CheckedRunnable versus Runnable.

Finally

Vavr provides a try-finally behavior no matter what the result of the operation is by using andFinally and andFinallyTry.

var t = Try.of(() -> "foo")
           .andFinally(() -> System.out.println("I'm done")); // Success(foo)
// prints "I'm done"

var t = Try.failure(new Exception("boom"))
           .andFinally(() -> System.out.println("I'm done")); // Failure(boom)
// prints "I'm done"

Note that the difference between andFinally and andFinallyTry is that andFinallyTry accepts a CheckedRunnable whereas andFinally accepts a Runnable.

Getting the value out of a Try

Try not using get without knowing if the Try is a Success, otherwise it will crash on you. Use getOrElse, getOrElseGet or orElse to do so.

var handle = Try.of(() -> "Alex").getOrElse("Unknown"); // "Alex"

// ...

var handle = Try.of(() ->  {
    throw new RuntimeException("foo");
}).getOrElse("Unknown"); // "Unknown"

Additionnally you can use fold :

var handle = Try.of(() -> "Alex")
                   .fold(l -> "Unknown", 
                         r -> "@" + r.toLowerCase()); // "@alex"

The orElse method also support both a Try or a Supplier. While orElseTry will take a Supplier and run it safely for us.

String isCool(String name) {
    if (name.startsWith("E"))
        return name;
    throw new RuntimeException("not cool: " + name);
}

var s = Try.of(() -> isCool("Alex"))
        .orElse(Try.of(() -> isCool("Eva")))
        .fold(l -> "No one is cool", r -> r + " is so cool");

// or with orElseTry
var s = Try.of(() -> isCool("Alex"))
        .orElseTry(() -> isCool("Eva"))
        .fold(l -> "No one is cool", r -> r + " is so cool");

In case a Try being a Failure is critical and you need to crash, Vavr has got you covered with getOrElseThrow.

Try.of(() -> isCool("Alex"))
    .getOrElseThrow(() -> new RuntimeException("No losers in this Casino"));

Filtering a Try

You may wish to set a Try to Failure if the value that it holds doesn't satisfy a given Predicate. In such a case, use the filter method.

var t = Try.of(() -> 41);
var even = t.filter(i -> i % 2 == 0,
        v -> new RuntimeException("nope: " + v));
even.isFailure(); // true

var odd = t.filter(i -> i % 2 == 1,
        v -> new RuntimeException("nope: " + v));
odd.isSuccess(); // true

Note that the API provides also a filterTry if you need to use a CheckedPredicate instead of a Predicate. The filter method delegates to filterTry.

Making an Either

You may wish to make an Either out of a Try:

var e = Try.of(() -> 41).toEither();
e.isRight(); // true

Making a Validation

You may wish to make a Validation out of a Try:

var v = Try.of(() -> 41).toValidation(); // Valid(41)
var i = Try.failure(new Exception("foo")).toValidation(); // Invalid(Exception: foo)
var i = Try.failure(new Exception("foo"))
    .toValidation(Throwable::getMessage); // Invalid(foo)

Mapping a Try

Like Option or Either, a Try is a monadic container, and provides an API to transform what's inside the container, but it does so safely for you. Indeed, if a Try is a Failure, mapping its content will have no effect at all.

var str = Try.of(() -> "alex")
           .map(String::toUpperCase)
           .getOrElse("Could not proceed");

You can use as many map as you want to, and remember, mapping on a Failure has no effect:

var str = Try.failure(null)
           .map(StringUtils::reverse)
           .map(StringUtils::lowerCase)
           .map(StringUtils::capitalize)
           .map(s -> s.concat(" is enjoying Vavr"))
           .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

Now imagine that the Try was a Success:

var str = Try.success("XELA")
           .map(StringUtils::reverse)
           .map(StringUtils::lowerCase)
           .map(StringUtils::capitalize)
           .map(s -> s.concat(" is enjoying Vavr"))
           .getOrElse("Could not proceed");
System.out.println(str); // "Alex is enjoying Vavr"

Monadic containers help you think in terms of pipeline of transformation, and keeping in mind the happy path, letting you handle the failure case when you need the value.

The code above is equivalent to:

var t = Try.success("XELA");
String str = "Could not proceed";
if (t.isSuccess()) { // without Try you would use a catch expression
   s = StringUtils.capitalize(
          StringUtils.lowerCase(StringUtils.reverse(s.get())))
       + " is enjoying Vavr";
}
System.out.println(s);

When accustomed to monadic containers, the first example looks better (I think) and conveys much more the business intent of the code which is:

1. try to reverse the string
2. then lowercase it
3. then capitalize it
4. then concatenate some other string with it
5. then get the final result
   1. but if any of this fails I want the Could not proceed string instead.

Since Try is like an Either you can also map on the Failure side with mapFailure and the pattern matching API.

var t = Try.failure(new IOException("boom"));
t.mapFailure(
    Case($(instanceOf(IOException.class)), e -> 
        new RuntimeException("Now a runtime error", e))
).getCause(); // RuntimeException(Now a runtime error, IOException(boom))

Note that Vavr provides both map and mapTry, the difference being that mapTry accepts a CheckedFunction1 whereas map accepts a Function.

The difference between a Function and a CheckedFunction is that the CheckedFunction signature declares that it throws a Throwable.

Mapping and null

As said earlier in this chapter, a Try can be a Failure or, and thus it can be problematic, but Try's version of map is safer than the others and will use a try-catch behind the scene so that it doesn't crash.

Let's see an example:

var str = Try.of(() -> "ALEX")
             .map(String::toLowerCase)
             .map(s -> s.length() < 10 ? null : s)
             .map(s -> s + " size is: " + s.length()) // No Boom
             .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

Still, you can use flatMap if you want to:

var str = Try.of(() -> "ALEX")
             .map(String::toLowerCase)
             .flatMap(s -> Option.of(s.length() < 10 ? null : s))
             .map(s -> s + " size is: " + s.length()) // still no BOOM 
             .getOrElse("Could not proceed");
System.out.println(str); // "Could not proceed"

Making a Success from a Failure

When you need to turn a Failure into a Success whose content is the cause of the Failure you can user failed().

var t = Try.failure(new Exception("foo"));
t.getCause(); // java.lang.Exception: foo
t.failed(); // Success(java.lang.Exception: foo)

Recovering from errors

When a Try fails, you have many ways to handle the error. Vavr provides recover and recoverWith to help you dealing with failures.

var t = Try.of(() -> 10/0)     // will boom, but handled by Try
            .recover(ex -> 42); // Success(42)
t.isSuccess(); // true
t.get(); // 42

The recoverWith let you try to recover a failure by trying to evaluate another Try.

var t = Try.of(() -> 10/0)
           .recoverWith(ex -> Try.of(() -> 42)); // Success(42)
t.isSuccess(); // true
t.get(); // 42

Of course if the second Try called by recoverWith fails, the resulting Try will be a failure.

var t = Try.of(() -> 10/0)
           .recoverWith(ex -> Future.of(() -> 42/0)); 
t.isSuccess(); // false
t.get(); // BOOM

Working with resources

If you need to run functions depending on Closeable resources within a Try, you can use Try.withResources(...).of(...).

Try.withResources(() -> new FileInputStream("foo.txt"))
   .of(fooInputStream -> doSomething(fooInputStream))
   .getOrElse("Could not read");

In the example above the FileInputStream will be automatically closed.

You can use as many as 8 resources with the withResources factory method.

Using with collectors

Interrop with the Java Collectors is provided via collect()

Try.failure(new Exception("foo")).collect(Collectors.toList()); // List()
Try.of(() -> "foo").collect(Collectors.toList()); // List(foo)

Generally the collect method is available on most of Vavr's types.

Lazy

Lazy is a functor which represents a lazy evaluation. Unlike a Supplier it is to be noted that a Lazy uses memoization and as such will only evaluate once.

Creating a Lazy

In order to create a Lazy you can use the of factory method.

var lazy = Lazy.of(() -> "foo"); // Lazy<String>

You can also make a value by using the val(Supplier, Class) method, which creates a lazy value of a specific type, backed by a Proxy which delegates to a Lazy instance. Note that the Class parameter must point to an interface.

var str = Lazy.val(() -> { 
    System.out.println("realizing foo...");
    return "foo";
}, CharSequence.class); // CharSequence

System.out.println("Hello");
System.out.println(s + " is bar");
System.out.println(s + " is totally bar");

In the example above the value of str will be realized only when needed, let's see the generated output.

Hello
realizing foo...
foo is bar
foo is totally bar

Notice that the string realizing foo... is only printed one time, and after the first string Hello so just when we needed the value to print foo is bar.

Getting the value

Getting the value out of a Lazy is as easy as calling the get() method on it.

var lazy = Lazy.of(() -> "foo"); // Lazy<String>
var str = lazy.get(); // String

A Lazy can generate a null value, it's not like an Option, and as such, even if the API gives you access to getOrElse and getOrElseThrow via the Value superclass, it is not defined and will not do what you think it does, so avoid using these constructs on lazy.

This is because Lazy's implementation of isEmpty() returns false.

var lazy = Lazy.of(() -> (String) null); // Lazy<String>
var str = lazy.getOrElse("bar"); // null

// or using getOrElse with a provider
var str = lazy.getOrElse(() -> "bar")); // null

// or using getOrElseThrow
var str = lazy.getOrElseThrow(() -> new RuntimeException()); // null (does not throw)

Knowing if a Lazy has been evaluated

Since Lazy is a container, you can declare it and then use it later. Sometimes you need to know if the value a Lazy is supposed to compute has been already computed.

To do this use the isEvaluated() method.

var lazy = Lazy.of(() -> "foo"); // Lazy<String>
lazy.isEvaluated(); // false
var str = lazy.get(); // "foo"
lazy.isEvaluated(); // true

Filtering a Lazy

Vavr lets you filter a Lazy by creating an Option holding or not the evaluated value if it satisfies a predicate. Of course, calling filter on a Lazy which has not been evaluated will force its evaluation.

var lazy = Lazy.of(() -> {
    System.out.println("realizing...");
    return "foo"; 
}); // Lazy<String>
var opt1 = lazy.filter(s -> s.length() > 3); // None
var opt2 = lazy.filter(s -> s.length() == 3); // Some("foo")

In the example above the string realizing... will be printed only one time.

Mapping on a Lazy

Since Lazy is a monadic container, you can transform the value it holds. Of course calling map on a Lazy which has not been evaluated will force its evaluation.

However the returned Lazy will not be evaluated yet!

var lazy = Lazy.of(() -> {
    System.out.println("realizing...");
    return "foo";
}).map(s -> {
    System.out.println("uppercasing...");
    return s.toUpperCase();
});
System.out.println(lazy.get() + " is BAR");
System.out.println(lazy.get() + " is totally BAR");

Will output the following text:

realizing...
uppercasing...
FOO is BAR
FOO is totally BAR

Running a side effect

Like Option, you can run side effects using peek, except that there is no concept of present or absent value. There's always a value, which can be null.

var lazy = Lazy.of(() -> {
    System.out.println("realizing...");
    return "foo";
}).peek(s -> System.out.println("Current state is: " + s))
  .map(s -> {
        System.out.println("uppercasing...");
        return s.toUpperCase();
  }).peek(s -> System.out.println("Current state is: " + s));
System.out.println(lazy.get() + " is BAR");
System.out.println(lazy.get() + " is totally BAR");

Will output the following text:

realizing...
Current state is: foo
uppercasing...
Current state is: FOO
FOO is BAR
FOO is totally BAR

Transforming to another domain

If you need to get the value out of a Lazy and transform it at the same type, you can use the transform method.

var str = Lazy.of(() -> "foo")
        .transform(s -> s.get().toUpperCase() + " is " + s.get().length());
System.out.println(str); // "FOO is 3"

Deprecation

The Lazy API has been marked deprecated since Java is not a lazily evaluated language. Library authors think that the implementation is ineffective because it acts as a simple wrapper and thus doesn't scale well.

Future

The Future is a computation result that becomes eventually available, providing non-blocking operations on it.

A Future has two states:

1. Pending, which means that the computation is still ongoing and can be cancelled or completed
2. Completed, which means that the computation has either finished successfully with a result, failed with an exception or was cancelled.

Creating a Future

To create a Future you can use the of factory method.

var future = Future.of(() -> "foo"); // Future<String>

You can also create Future in a defined state using failed or successful.

var future = Future.failed(); 
future.isFailure(); // true
future = Future.failed(new RuntimeException("boom"));
future.isFailure(); // true
future = Future.failed(newSingleThreadExecutor(), () -> "foo");
future.isFailure(); // true

future = Future.successful();
future.isSuccess(); // true
future = Future.successful("foo");
future.isSuccess(); // true

Finally, you can also use ofCallable and ofSupplier to create a Future from either a Callable or a Supplier.

Retrieve a Future state

To know in what state a Future is, the API provides:

• isCompleted: true if the Future has completed, false otherwise
• isSuccess: true if the Future has completed successfully, false otherwise
• isFailure: true if the Future has completed with an error, false otherwise
• isCancelled: true if the Future has been cancelled.

Retrieving a Future's value

In order to get the value out of a Future you can use either get, getOrElse, getOrElseThrow. Note that getOrElse returns the absent value only for failures, or cancellation, not for missing values like null.

var future = Future.of(() -> "foo");
var str = future.get(); // "foo"

future = Future.of(() -> null);
str = future.getOrElse("bar"); // null, because a Future can return a null

future = Future.of(() -> { throw new RuntimeException("boom");} );
str = future.getOrElse("bar"); // "bar"

str = future.getOrElseThrow(new RuntimeException("blurp")); // Exception: blurp

Since a Future may have not finished to compute the final value when you call get or getOrElse these two methods will block the current thread until the Future has completed.

If you wish not to block the current thread, then use the getValue method which returns an Option<Try<?>>. This Option will be None until the Future's computation has completed.

var future = Future.of(() -> {
    Thread.sleep(50);
    return "foo";
});
for (int i = 0; i < 1_000_000_000; ++i) {
    var opt = future.getValue();
    if (opt.isDefined()) {
        API.println(i + ": future has completed");
        opt.peek(t -> {
            API.println("\tSuccess: " + t.isSuccess());
            API.println("\t  Value: " + t.getOrElse("fallback"));
        });
        break;
    } else if (i % 10_000_000 == 0) {
        API.println(i + ": Waiting...");
    }
}

In the example above we simulate some computation which takes 50ms before returning, and then we loop maximum a billion times, each time getting the Future value into an Option trying to check if it is defined or not, in such a case we print the current iteration and the state and value of the Future, otherwise each ten million times we print Waiting....

On my machine it prints:

0: Waiting...
10000000: Waiting...
20000000: Waiting...
30000000: Waiting...
40000000: Waiting...
40674362: future has completed
	Success: true
	  Value: foo

Eventually the future has returned and a defined Option has been produced by getValue. This Option contains a Try which represents the status of the completion, either a Success or a Failure.

Running side effects

To run side effects on Success or Failure you can do exactly like with the Try monad by using onSuccess and onFailure.

Future.of(() -> "foo")
      .onSuccess(value -> System.out.println("Success: " + value))
      .onFailure(ex -> System.err.println("Error: " + ex))
      .getOrElse("bar"); // "foo"

Sometimes, it may be important to run a side effect as soon as the Future has completed, in such a case you can use onComplete.

Future.of(() -> "foo")
      .onComplete(v -> System.out.println("Just finished: " + v))
      .onSuccess(v -> System.out.println("Success: " + v))
      .onFailure(ex -> System.err.println("Error: " + ex))
      .getOrElse("bar"); // "foo"

Which outputs:

Just finished: Success(foo)
Success: foo

Finally, note that you can chain as many onComplete and onSuccess as you wish, but if you want to run them in a specific order you may want to use andThen instead.

Future.of(() -> "foo")
      .andThen(v -> System.out.println("Finished #1: " + v))
      .andThen(v -> System.out.println("Finished #2: " + v))
      .andThen(v -> System.out.println("Finished #3: " + v))
      .onSuccess(v -> System.out.println("Success: " + v))
      .onFailure(ex -> System.err.println("Error: " + ex))
      .getOrElse("bar"); // "foo"

Which outputs:

Finished #1: Success(foo)
Finished #2: Success(foo)
Finished #3: Success(foo)
Success: foo

Canceling a Future

In order to cancel a Future, simply call cancel on it.

var future = Future.of(() -> "foo");
future.cancel();
future.isCancelled(); // true
future.getOrElse("bar"); // "bar"

Awaiting termination

To wait until completion without actually getting the value, just use await on the Future instance.

var future = Future.of(() -> "foo");
future.await(); // blocks the thread until the future has completed
future.isCompleted(); // true
future.getOrElse("bar"); // "foo"

Finding a Future within a sequence

If you have an Iterable of Future which may or may not be already completed and you want to find the first Future whose final value satisfies a predicate, you can use the find factory method.

var futures = Vector.of(
    Future.of(() -> "abcdef"),
    Future.of(() -> "abc"),
    Future.of(() -> "abcd"),
    Future.of(() -> "a"));

var option = Future.find(futures, 
    s -> s.length() >= 3 && s.length() < 5 && s.startsWith("a")); 
// Some(abc)

Finding the first completed Future within a sequence

If you have an Iterable of Future which may or may not be already completed and you want to find the first Future who has completed, you can use the firstCompletedOf method.

Imagine a function named firstHitWins(String) which calls an API with a Twitter handle as parameter, and the first hit to complete wins.

Random r = new Random();

// imagine some networking here
@SneakyThrows
String firstHitWins(String name) { 
    Thread.sleep(r.nextInt(2_000));
    return name; 
} 

var futures = Vector.of(
    Future.of(() -> firstHitWins("Alex")),
    Future.of(() -> firstHitWins("Jessica")),
    Future.of(() -> firstHitWins("Eva")));

var winner = Future.firstCompletedOf(futures);
winner.get(); // may be "Alex", "Jessica", or "Eva" 
              // depending on which Future completes first

The @SneakyThrows annotation from lombok here just saves us to write the function firstHitWins like this:

String firstHitWins(String name) throws InterruptedException {
    Thread.sleep(r.nextInt(2_000));
    return name;
} 

Running tasks

If you want to run some background computations of which you don't need any results, you can use run.

Future.run(() -> System.out.println("hello")).await();

// providing a custom Executor
Future.run(newSingleThreadExecutor(), () -> System.out.println("hello")).await();

Note that runRunnable is deprecated.

Accessing the underlying Executor

Future is based on Java's Executor and if you need to access it for any reason, you can do it by calling executor.

var future = Future.of(() -> "foo");
future.peek(System.out::println)
        .executor().execute(() -> System.out.println("bar"));

Note that there is also an executorService method which has been deprecated since Vavr 0.10.0 and more.

Providing a custom Executor

The of factory method has an overload specifically to let you give a custom Executor that the returned Future instance should use.

var future = Future.of(newSingleThreadExecutor(), () -> "foo");
future.peek(System.out::println)
        .executor().execute(() -> System.out.println("bar"));
    }

Mapping the Future

Like all the other values in Vavr, Future is a monadic container and thus, you can transform the value it is holding via map.

var str = Future.of(() -> "foo")
                .map(String::toUpperCase)
                .map(s -> "Hey " + s + "!")
                .getOrElse("Could not proceed");
System.out.println(str); // "Hey FOO!"

Note that using map won't force the Future to complete, the transformation you want to do on the final value will takes place when you will call get, getOrElse or await on the resulting Future.

var future1 = Future.of(() -> "foo")
                    .map(String::toUpperCase);
future1.isCompleted(); // false

var future2 = future1.map(s -> { throw new RuntimeException("boom"); });
future2.isCompleted(); // false
future2.await(); // Future(Failure(RuntimeException: boom))
future2.isFailure(); // true

future1.await(); // Future(Success(FOO))
future1.isSuccess(); // true

You can also nest calls to functions returning a Future with flatMap like you would do for an Option.

var str = Future.of(() -> "foo")
                .map(String::toUpperCase)
                .flatMap(s -> Future.of(() -> "Hey " + s + "!"))
                .getOrElse("Could not proceed");
System.out.println(str); // "Hey FOO!"

Note that Vavr provides also flatMapTry instead of flatMap when you need to use a CheckedFunction1 instead of a Function.

Folding futures

If you need to return a Future which contains the result of folding the given future values, then you can use fold.

Imagine a function named userScore which returns a user score, and we want to find the total score for all Future.

Random r = new Random();

@SneakyThrows
Integer userScore(String name) {
    Thread.sleep(r.nextInt(1_000));
    return r.nextInt(100);
}

var futures = Vector.of(
        Future.of(() -> userScore("Alex")),
        Future.of(() -> userScore("Jessica")),
        Future.of(() -> userScore("Eva")));

Future.fold(futures, 0, Integer::sum)
        .map(score -> "Total score: " + score)
        .get(); // "Total score 153"

Reducing Futures

If you need to return a Future which contains the reduced result of an Iterable of future values, you can use reduce.

var f1 = Future.of(() -> "My name");
var f2 = Future.of(() -> "is");
var f3 = Future.of(() -> "Alex");

Future.reduce(Vector.of(f1, f2, f3), 
        (a, b) -> a + " " + b).get(); // My name is Alex

Filtering Futures

You can filter a Future with a Predicate using filter, or with a CheckedPredicate using filterTry.

var future = Future.of(() -> "foo");

future.filter(s -> s.length() > 3).get(); 
// -> NoSuchElementException: Predicate does not hold for foo

future.filter(s -> s.length <= 3).get(); // "foo"

Zipping Futures

When using the Future API to consume data, it's really powerful to be able to consume multiple sources asynchronously but still process them at once with zip.

record Person(String firstName, String lastName) {}
record Address(String street, String city, String country) {}

// imagine that instead of creating manually entities we would
// fetch them through the network via a REST API for example
var name = Future.of(() -> new Person("John", "Doe"));
var address = Future.of(() -> new Address("13 rue des Clercs", "Metz", "FR"));

var info = name.zip(address).get(); // Tuple2<Person, Address>
System.out.println(info._1.firstName()); // "John"
System.out.println(info._2.city()); // "Metz"