Java 8 Constructor Refs (In All Their Glory)

[Note: my last post announced my new book, Modern Java Recipes, is now available from O’Reilly publishers in Early Release form. As a sample, I included a discussion of the Predicate interface, one of the new functional interfaces in the the java.util.function package. In this post, I highlight constructor references, which are discussed in another recipe in the book.]

Problem

You want to instantiate an object using a method reference as part of a stream pipeline.

Solution

Use the new keyword as part of a method reference.

Discussion

When people talk about the new syntax added to Java 8, they mention lambda expressions, method references, and streams. For example, say you had a list of people and you wanted to convert it to a list of names. One way to do so would be:

List<String> names = people.stream()
    .map(person -> person.getName()) // lambda expression
    .collect(Collectors.toList());

In other words, take a list of Person instances, turn it into a stream, map each one to a String by invoking the getName() method on it, and collect them back into a List.

That works, but most developers would use a method reference instead:

List<String> names = people.stream()
    .map(Person::getName)           // method reference
    .collect(Collectors.toList());

The method reference is slightly shorter, and makes clear that the only thing being done to each person is transforming it using the getName method. Lambda expressions can be far more complicated and versatile. Method references are simple.

What if you want to go the other way? What if you have a list of strings and you want to create a list of Person references from it? In that case you can use a method reference again, but this time using the keyword new. That’s a constructor reference, which I would like to illustrate here.

First, here is the Person class, which is just about the simplest Plain Old Java Object (POJO) imaginable. All it does is wrap a simple string attribute called name.

public class Person {
    private String name;

    public Person() {}   // default constructor

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

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

    // ... equals, hashCode, toString methods ...

Given a list of string names, I can map them to Person instances using the one-argument constructor.

List<String> names =  
    Arrays.asList("Grace Hopper", "Barbara Liskov", "Ada Lovelace",
        "Karen Spärck Jones");

List<Person> people =
    names.stream()
         .map(name -> new Person(name))  // lambda expression
         .collect(Collectors.toList());

Now instead of using the lambda expression that invokes the one-argument constructor directly, I can use a constructor reference instead.

names.stream()
     .map(Person::new)     // Constructor reference
     .collect(Collectors.toList());

Like all lambda expression or method references, context is everything. The map method is invoked on a stream of strings, so the Person::new reference is invoked on each string in the stream. The compiler recognizes that the Person class has a constructor that takes a single string, so it calls it. The default constructor is ignored.

Copy Constructors

To make things more interesting, I’ll add two additional constructors: a “copy constructor” that takes a Person argument, and one that takes a variable argument list of strings.

public Person(Person p) {   // copy constructor
    this.name = p.name;
}

public Person(String... names) {  // varargs constructor
    this.name = Arrays.stream(names)
                      .collect(Collectors.joining(" "));
}

The copy constructor makes a new Person from an existing Person instance. Say I defined a person, then used that person in a stream without mapping it, and then converted back into a collection. Would I still have the same person?

Person before = new Person("Grace Hopper");

List<Person> people = Stream.of(before)
        .collect(Collectors.toList());
Person after = people.get(0);

assertTrue(before == after);  // exact same object

before.setName("Grace Murray Hopper");  // Change name using 'before'
assertEquals("Grace Murray Hopper", after.getName()); // Same in 'after'

The point is, if I have a reference to Admiral Hopper before the stream operations and I didn’t map her to another object, I still have the same reference afterwards.

Using a copy constructor I can break that connection.

people = Stream.of(before)
        .map(Person::new)          // use copy constructor
        .collect(Collectors.toList());
after = people.get(0);
assertFalse(before == after);      // different objects
assertEquals(before, after);       // but equivalent

before.setName("Rear Admiral Dr. Grace Murray Hopper"); // Change using 'before'
assertFalse(before.equals(after)); // No longer the same in 'after'

This time, when invoking the map method, the context is a stream of Person instances. Therefore the Person::new syntax invokes the constructor that takes a Person and returns a new, but equivalent, instance. I’ve broken the connection between the before reference and the after reference.

(Btw, I mean no disrespect by treating Admiral Hopper as an object. I have no doubt she could still kick my a**, and she passed away in 1992.)

Varargs Constructors

The varargs constructor is invoked by the client by passing zero or more string arguments separated by commas. Inside the constructor, the names variable is treated like String[], a string array. The static stream method on the Arrays class is used to convert that into a stream, which is then turned into a single string by calling the collect method, whose argument comes from the convenient joining(String delimiter) method in the Collectors class.

How does that get invoked? Java includes a split method on String that takes a delimiter and returns a String array:

String[] split(String delimiter)

Since the variable argument list is equivalent to an array, I can use that method to invoke the varargs constructor.

names.stream()                     // Stream<String>
    .map(name -> name.split(" "))  // Stream<String[]>
    .map(Person::new)              // Stream<Person> using String... ctor
    .collect(Collectors.toList());

This time I map the strings to string arrays before invoking the constructor. Note that this is one of those times where I can’t use a method reference, because there’s no way using a method reference to supply the delimiter argument. I have to use the lambda expression instead.

Since the context after the first map is now a stream of string arrays, the Person::new constructor reference now uses the varargs constructor. If I add a print statement to that constructor:

System.out.println("Varargs ctor, names=" + Arrays.asList(names));

I can then see it in action:

Varargs ctor, names=[Grace, Hopper]
Varargs ctor, names=[Barbara, Liskov]
Varargs ctor, names=[Ada, Lovelace]
Varargs ctor, names=[Karen, Spärck, Jones]

Arrays

With constructor references, not only can you create instances, you can even create arrays. Say instead of returning a List, I wanted to return an array of person, Person[]. The Stream class has a method called, naturally enough, toArray.

<A> A[] toArray(IntFunction<A[]> generator)

This method uses A to represent the generic type of the array returned containing the elements of the stream, which is created using the provided generator function. The cool part is that a constructor reference can be used for that, too.

names.stream()
     .map(Person::new)         // Person constructor ref
     .toArray(Person[]::new);  // Person[] constructor ref

The returned value is a Person[] with all the stream elements now included as Person references.

Constructor references are just method references by another name, using the word new to invoke a constructor. Which constructor is determined by the context, as usual. This technique gives a lot of flexibility when processing streams.

Modern Java Recipes now in Early Release

My latest book, Modern Java Recipes, is now available in Early Release form! If you have a Safari account (the online book repository from O’Reilly), you can add it to your bookshelf at any time. Otherwise, you can get it directly from http://shop.oreilly.com or even at Amazon.com.

modern_java_recipes_early

There are only three chapters in the Early Release,  covering 17 recipes, but that’s a bit misleading. The book itself is probably about 85% finished, covering about 50 recipes of an anticipated 60 or so. The released chapters are the sections in the best shape at the moment, but expect several more to be added rapidly in the coming weeks. Frankly, I hope to finish the entire book within the next month, though that may be asking a lot.

(Nothing like committing to an ambitious deadline in public. Sigh. I’ve noticed that when I’m being productive (and today has been a pretty decent day), my estimates tend to assume that I’ll be able to continue at the same level of productivity indefinitely. Yeah, good luck with that.)

Let me give the book the best praise I can, which is to say it’s not bad, and parts of it are actually pretty decent. Most of it is being reviewed by tech experts at the moment (you know who you are), so the quality will undoubtedly improve as I incorporate their suggestions.

The goal of the book is very practical. I want Java developers to understand the new additions to Java that came in version 8 (and are coming in version 9) and how to apply them to their code. With that in mind, recipe titles include topics like, “Default Method Conflict” for when a class implements two interfaces that each have the same default method implementation, “Logging with a Supplier” that shows how the updated Logger class overloads the logging methods to use a Supplier in order to defer execution, and “Using a Generic Exception Wrapper”, which shows how to wrap lambda expressions that throw checked exceptions into a method that will catch them and rethrow them as unchecked.

Some of the examples are very basic, but many are more advanced and come from several sources, including authors I respect. I tried to give credit wherever that happened, but if you see something that isn’t sourced and you think it should be, please let me know. Now is when I’ll have an opportunity to make those sorts of updates.

Some recipes are the result of questions I’ve asked on Stack Overflow (mandatory joke seen on Twitter: the maintainers of Stack Overflow have the hardest job in I.T., because when it goes down, they have to fix it without accessing Stack Overflow). I have to mention that my good friend Tim Yates was so helpful there that I finally contacted him directly so I could ask questions on a regular basis. He kindly agreed to be one of the tech reviewers, and has improved every section he touched.

(At least so far. Who knows what his review will reveal? But no pressure…)

I’ll have a lot more to say about the book in the coming weeks. I hope to post about it here on a regular basis, discussing various recipes and other lessons I’ve learned while writing the book, as well as sharing any jokes that my editor makes me remove (yes, that’s a teaser for later).

In the meantime, here’s a quick sample, which (1) shows the style I’m trying to follow, and (2) gives me an excuse (and any excuse is a good one) to use sample names from Firefly:

Filter Data With Predicates

Problem

You want to implement the java.util.function.Predicate interface.

Solution

Implement the boolean test(T t) method in the Predicate interface using a lambda expression or a method reference.

Discussion

Predicates are used primarily to filter streams. Given a stream of items, the filter method in java.util.stream.Stream takes a Predicate and returns a new stream that includes only the items that match the given predicate.

The single abstract method in Predicate is boolean test(T t), which takes a single generic argument and returns true or false. The complete set of methods in Predicate, including state and defaults, is given by:

default Predicate<T> and(Predicate<? super T> other)
static <T> Predicate<T> isEquals(Object targetRef)
default Predicate<T> negate()
default Predicate<T> or(Predicate<? super T> other)
boolean test(T t)

Say you have a collection of names and you want to find all the instances that have a particular length. The next example shows how to use stream processing to do so.

public String getNamesOfLength5(String... names) {
    return Arrays.stream(names)
                 .filter(s -> s.length() == 5)
                 .collect(Collectors.joining(", "));

Alternatively, perhaps you want only the names that start with a particular letter:

public String getNamesStartingWithS(String... names) {
    return Arrays.stream(names)
        .filter(s -> s.startsWith("S"))
        .collect(Collectors.joining(", "));
}

Both of these examples have hard-wired values for the filter. It’s more likely that the condition will be specified by the client:

public String getNamesSatisfyingCondition(Predicate<String> condition, String... names) {
    return Arrays.stream(names)
        .filter(condition)
        .collect(Collectors.joining(", "));
}

This is quite flexible, but it may be a bit much to expect the client to write every predicate themselves. One option is to add constants to the class representing the most common cases.

public class ImplementPredicate {
    public static final Predicate<String> LENGTH_FIVE = s -> s.length() == 5;
    public static final Predicate<String> STARTS_WITH_S = s -> s.startsWith("S");

    // ... rest as before ...
}

The other advantage to supplying a predicate as an argument is that you can also use the default methods and, or, and negate to create a composite predicate from a series of individual elements.

This test case demonstrates all of these techniques.

import org.junit.Before;
import org.junit.Test;

import java.util.stream.Stream;

import static functionpackage.ImplementPredicate.*;
import static org.junit.Assert.assertEquals;

public class ImplementPredicateTest {
    private ImplementPredicate demo = new ImplementPredicate();
    private String[] names;

    @Before
    public void setUp() {
        names = Stream.of("Mal", "Wash", "Kaylee", "Inara", "Zoë",
                          "Jayne", "Simon", "River", "Shepherd Book")
                      .sorted()
                      .toArray(String[]::new);
}

    @Test
    public void getNamesOfLength5() throws Exception {
        assertEquals("Inara, Jayne, River, Simon",
            demo.getNamesOfLength5(names));
    }

    @Test
    public void getNamesStartingWithS() throws Exception {
        assertEquals("Shepherd Book, Simon", demo.getNamesStartingWithS(names));
    }

    @Test
    public void getNamesSatisfyingCondition() throws Exception {
        assertEquals("Inara, Jayne, River, Simon",
            demo.getNamesSatisfyingCondition(s -> s.length() == 5, names));
        assertEquals("Shepherd Book, Simon",
            demo.getNamesSatisfyingCondition(s -> s.startsWith("S"), names));
        assertEquals("Inara, Jayne, River, Simon",
            demo.getNamesSatisfyingCondition(LENGTH_FIVE, names));
        assertEquals("Shepherd Book, Simon",
            demo.getNamesSatisfyingCondition(STARTS_WITH_S, names));
    }

    @Test
    public void composedPredicate() throws Exception {
        assertEquals("Simon",
            demo.getNamesSatisfyingCondition(LENGTH_FIVE.and(STARTS_WITH_S), names));
        assertEquals("Inara, Jayne, River, Shepherd Book, Simon",
            demo.getNamesSatisfyingCondition(LENGTH_FIVE.or(STARTS_WITH_S), names));
        assertEquals("Kaylee, Mal, Shepherd Book, Wash, Zoë",
            demo.getNamesSatisfyingCondition(LENGTH_FIVE.negate(), names));
    }
}

Other methods in the standard library that use predicates include:

  • Optional.filter(Predicate predicate) — if a value is present, and the value matches the given predicate, return an optional describing the value, otherwise return an empty Optional
  • Collection.removeIf(Predicate filter) — removes all elements of this collection that satisfy the predicate
  • Stream.allMatch(Predicate predicate) — return true if all elements of the stream satisfy the given predicate. The methods anyMatch and noneMatch work similarly
  • Collectors.partitioningBy(Predicate predicate) — returns a Collector which splits a stream into two categories: those that satisfy the predicate and those that do not

Predicates are useful whenever a stream should only return certain elements. This recipe hopefully gives you an idea where and when that might be useful.

See Also

Closure composition is also discussed in [the section on closure composition].

 

 

%d bloggers like this: