Modules

The new system defines modules, which have a name (except for the so-called unnamed module) and express their dependencies and export packages via a file called module-info.java. A module includes a compiled module-info.class inside its deliverable JAR. The module-info.java file is known as a module descriptor.

The contents of module-info.java start with the word module and then use a combination of requires and exports keywords to describe what the module does. To demonstrate this, following is a trivial “Hello, World!” example that will use two modules and the JVM.

The example modules are com.oreilly.suppliers and com.kousenit.clients.

The former supplies a Stream of strings representing names. The latter prints each name to the console with a welcome message.

For the Supplier module, the source code for the NamesSupplier class is shown in Example 10-1.

package com.oreilly.suppliers;

// imports ...

public class NamesSupplier implements Supplier<Stream<String>> {
    private Path namesPath = Paths.get("server/src/main/resources/names.txt");

    @Override
    public Stream<String> get() {
        try {
            return Files.lines(namesPath);
        } catch (IOException e) {
            e.printStackTrace();
            return null;
        }
    }
}

(The module is stored in an IntelliJ module—unfortunately IntelliJ IDEA also uses the word “module” for a different concept—called “server,” which is why that name is in the path for the text file.)

The contents of names.txt are:⁴

Londo
Vir
G'Kar
Na'Toth
Delenn
Lennier
Kosh

In the client module, the source code for the Main class is in Example 10-2.

package com.kousenit.clients;

// imports ...

public class Main {
    public static void main(String[] args) throws IOException {
        NamesSupplier supplier = new NamesSupplier();

        try (Stream<String> lines = supplier.get()) {  
            lines.forEach(line -> System.out.printf("Hello, %s!%n", line));
        }
    }
}

The module-info.java file for the Supplier code is shown in Example 10-3.

module com.oreilly.suppliers {      
    exports com.oreilly.suppliers;  
}

The module-info.java file for the client module is shown in Example 10-4.

module com.kousenit.clients {       
    requires com.oreilly.suppliers; 
}

When this program is executed, the output is:

Hello, Vir!
Hello, G'Kar!
Hello, Na'Toth!
Hello, Delenn!
Hello, Lennier!
Hello, Kosh!

The exports clause is necessary in the Supplier module for the NamesSupplier class to be visible to the client. The requires clause in the client module tells the system that this module needs classes from the Supplier module.

If you would like to log accesses to the server in that module, you can add a Logger from the java.util.logging package in the JVM, as in Example 10-5.

public class NamesSupplier implements Supplier<Stream<String>> {
    private Path namesPath = Paths.get("server/src/main/resources/names.txt");
    private Logger logger = Logger.getLogger(this.getClass().getName()); 

    @Override
    public Stream<String> get() {
        logger.info("Request for names on " + Instant.now());            
        try {
            return Files.lines(namesPath);
        } catch (IOException e) {
            e.printStackTrace();
            return null;
        }
    }
}

This code will not compile. The JVM has been modularized as part of Java 9, and the java.util.logging package is not part of java.base, which is the only module provided by the JVM by default. In order to use the Logger class, you need to update the module-info.java file to match that in Example 10-6.

module com.oreilly.suppliers {
    requires java.logging;          
    exports com.oreilly.suppliers;
}

The JVM modules are each documented with their own module-info.java files. For instance, Example 10-7 shows the module-info.java file from the java.logging module.

module java.logging {
    exports java.util.logging;
    provides jdk.internal.logger.DefaultLoggerFinder with
        sun.util.logging.internal.LoggingProviderImpl;
}

This file does not only exports the module. It also provides an internal implementation of a Service Provider Interface (SPI) DefaultLoggerFinder in the form of the Logging​ProviderImpl class when a logger is requested by a client.

Hopefully this gives you a sense of how modules are defined and how they work together. Expect to hear much more about this in the coming months.

There are many more issues related to modules that will be resolved before the specification is approved. Many of them involve porting legacy code. Terms like the unnamed module and automatic modules involve code that is not in any module but on the “module path,” and modules formed by existing legacy JAR files. Much of the debate about JPMS is about how to handle those cases.

The ofNullable method

In Java 8, the Stream interface has an overloaded static factory method called of, which takes either a single value or a variable argument list. Either way, you can’t use a null argument.

In Java 9, the ofNullable method lets you create a single-element stream that wraps a value if not null, or is an empty stream otherwise. See the test case in Example 10-16 for details.

@Test
public void ofNullable() throws Exception {
    Stream<String> stream = Stream.ofNullable("abc");  
    assertEquals(1, stream.count());

    stream = Stream.ofNullable(null);                  
    assertEquals(0, stream.count());
}

The count method returns the number of nonempty elements in a stream. You can now use the ofNullable method on any argument without checking whether or not it’s null first.

Using iterate with a Predicate

The next interesting method is a new overload for iterate. The iterate method in Java 8 has the signature:

static<T> Stream<T> iterate(final T seed, final UnaryOperator<T> f)

So creating a stream starts with a single element (the seed), and subsequent elements are produced by successively applying the unary operator. The result is an infinite stream, so using it normally requires a limit or some other short-circuiting function, like findFirst or findAny.

The new overloaded version of iterate takes a Predicate as the second argument:

static<T> Stream<T> iterate(T seed, Predicate<? super T> hasNext,
    UnaryOperator<T> next)

The values are produced by starting with the seed and then applying the unary operator as long as the values satisfy the hasNext predicate.

For instance, see Example 10-17.

@Test
public void iterate() throws Exception {
    List<BigDecimal> bigDecimals =                
            Stream.iterate(BigDecimal.ZERO, bd -> bd.add(BigDecimal.ONE))
            .limit(10)
            .collect(Collectors.toList());

    assertEquals(10, bigDecimals.size());

    bigDecimals = Stream.iterate(BigDecimal.ZERO,  
            bd -> bd.longValue() < 10L,
            bd -> bd.add(BigDecimal.ONE))
            .collect(Collectors.toList());

    assertEquals(10, bigDecimals.size());
}

The first stream is the Java 8 way of using iterate with a limit. The second one uses a Predicate as the second argument. The result looks more like a traditional for loop.

takeWhile and dropWhile

The new methods takeWhile and dropWhile allow you to get portions of a stream based on a predicate. According to the Javadocs, on an ordered stream, takeWhile returns “the longest prefix of elements taken from this stream that match the given predicate,” starting at the beginning of the stream.

The dropWhile method does the opposite—it returns the remaining elements of the stream after dropping the longest prefix of elements that satisfy the predicate.

The code in Example 10-18 shows how they work on an ordered stream.

@Test
public void takeWhile() throws Exception {
    List<String> strings = Stream.of("this is a list of strings".split(" "))
            .takeWhile(s -> !s.equals("of"))  
            .collect(Collectors.toList());
    List<String> correct = Arrays.asList("this", "is", "a", "list");
    assertEquals(correct, strings);
}

@Test
public void dropWhile() throws Exception {
    List<String> strings = Stream.of("this is a list of strings".split(" "))
            .dropWhile(s -> !s.equals("of"))  
            .collect(Collectors.toList());
    List<String> correct = Arrays.asList("of", "strings");
    assertEquals(correct, strings);
}

Each method splits the stream at the same place, but takeWhile returns the elements before the split and dropWhile returns the elements after it.

The real advantage to takeWhile is that it is a short-circuiting operation. If you have a huge collection of sorted elements, you can stop evaluating once you hit the condition you care about.

For example, say you had a collection of orders from a client, sorted by value in descending order. Using takeWhile, you can get just the orders above a certain threshold, without having to apply a filter on every element.

The code in Example 10-19 simulates this situation by generating 50 random integers between 0 and 100, sorting them in descending order, and returning only those whose value is greater than 90.

Random random = new Random();
List<Integer> nums = random.ints(50, 0, 100) 
        .boxed()                             
        .sorted(Comparator.reverseOrder())
        .takeWhile(n -> n > 90)              
        .collect(Collectors.toList());

This particular example is perhaps more intuitive (though not necessarily more efficient) using dropWhile instead, as in Example 10-20.

Random random = new Random();
List<Integer> nums = random.ints(50, 0, 100)
        .sorted()                
        .dropWhile(n -> n < 90)  
        .boxed()
        .collect(Collectors.toList());

Methods like takeWhile and dropWhile have existed in other languages for years. In Java 9 they’re available to Java as well.

The filtering method

Say you have a class called Task that has attributes for a budget and a list of developers working on it, which are represented by instances of a Developer class. Both classes are shown in Example 10-21.

public class Task {
    private String name;
    private long budget;
    private List<Developer> developers = new ArrayList<>();

    // ... constructors, getters and setters, etc. ...
}

public class Developer {
    private String name;

    // ... constructors, getters and setters, etc. ...
}

First, say you want to group the tasks by budget. A simple Collectors.groupingBy operation is shown in Example 10-22.

Developer venkat = new Developer("Venkat");
Developer daniel = new Developer("Daniel");
Developer brian = new Developer("Brian");
Developer matt = new Developer("Matt");
Developer nate = new Developer("Nate");
Developer craig = new Developer("Craig");
Developer ken = new Developer("Ken");

Task java = new Task("Java stuff", 100);
Task altJvm = new Task("Groovy/Kotlin/Scala/Clojure", 50);
Task javaScript = new Task("JavaScript (sorry)", 100);
Task spring = new Task("Spring", 50);
Task jpa = new Task("JPA/Hibernate", 20);

java.addDevelopers(venkat, daniel, brian, ken);
javaScript.addDevelopers(venkat, nate);
spring.addDevelopers(craig, matt, nate, ken);
altJvm.addDevelopers(venkat, daniel, ken);

List<Task> tasks = Arrays.asList(java, altJvm, javaScript, spring, jpa);

Map<Long, List<Task>> taskMap = tasks.stream()
        .collect(groupingBy(Task::getBudget));

This results in a Map of budget amounts to lists of tasks with that budget:

 50: [Groovy/Kotlin/Scala/Clojure, Spring]
 20: [JPA/Hibernate]
100: [Java stuff, JavaScript (sorry)]

Now, if you only want tasks that have a budget that exceeds some threshold, you can add a filter operation, as in Example 10-23.

taskMap = tasks.stream()
        .filter(task -> task.getBudget() >= THRESHOLD)
        .collect(groupingBy(Task::getBudget));

The output for a threshold of 50 is:

 50: [Groovy/Kotlin/Scala/Clojure, Spring]
100: [Java stuff, JavaScript (sorry)]

Tasks with budgets below the threshold will not appear in the output map at all. If you want to see them anyway, you now have an alternative. In Java 9, the Collectors class now has an additional static method called filtering, similar to filter, but applied to the downstream list of tasks. The code in Example 10-24 shows how to use it.

taskMap = tasks.stream()
    .collect(groupingBy(Task::getBudget,
          filtering(task -> task.getBudget() >= 50, toList())));

Now all the budget values will appear as keys, but the tasks whose budgets fall below the threshold will not appear in the list values:

 50: [Groovy/Kotlin/Scala/Clojure, Spring]
 20: []
100: [Java stuff, JavaScript (sorry)]

The filtering operation is thus a downstream collector, operating on the list generated by the grouping operation.

The flatMapping method

This time, say you want to get a list of developers on each task. The basic grouping operation produces a group of task names to lists of tasks, as in Example 10-25.

Map<String, List<Task>> tasksByName = tasks.stream()
        .collect(groupingBy(Task::getName));

The (formatted) output is:

                 Java stuff: [Java stuff]
Groovy/Kotlin/Scala/Clojure: [Groovy/Kotlin/Scala/Clojure]
         JavaScript (sorry): [JavaScript (sorry)]
                     Spring: [Spring]
               JPA/Hibenate: [JPA/Hibernate]

To get the associated lists of developers, you can use the mappingBy downstream collector, as in Example 10-26.

Map<String, Set<List<Developer>>> map = tasks.stream()
        .collect(groupingBy(Task::getName,
              Collectors.mapping(Task::getDevelopers, toSet())));

As the return type shows, the problem is that it returns a Set<List<Developer>>. What’s needed here is a downstream flatMap operation to flatten the collection of collections. That’s now possible using the flatMapping method on Collectors, as in Example 10-27.

Map<String, Set<Developer>> task2setdevs = tasks.stream()
        .collect(groupingBy(Task::getName,
                Collectors.flatMapping(task -> task.getDevelopers().stream(),
                toSet())));

Now the result is what you want:

                 Java stuff: [Daniel, Brian, Ken, Venkat]
Groovy/Kotlin/Scala/Clojure: [Daniel, Ken, Venkat]
         JavaScript (sorry): [Nate, Venkat]
                     Spring: [Craig, Ken, Matt, Nate]
              JPA/Hibernate: []

The flatMapping method is just like the flatMap method on Stream. Note that the first argument flatMapping needs to be a stream, which can be empty or not depending on the source.

The stream method

Consider a finder method to look up customers by ID, as in Example 10-28.

public Optional<Customer> findById(int id) {
    return Optional.ofNullable(map.get(id));
}

This method assumes that the customers are contained within a Map in memory. The get method on Map returns a value if the key is present or null if not, so making it the argument to Optional.ofNullable either wraps a nonnull value inside an Optional or returns an empty Optional.

Since findById returns an Optional<Customer>, trying to return a collection of customers is a bit more complicated. In Java 8, you can write the code in Example 10-29.

public Collection<Customer> findAllById(Integer... ids) {
    return Arrays.stream(ids)
            .map(this::findById)           
            .filter(Optional::isPresent)   
            .map(Optional::get)            
            .collect(Collectors.toList());
}

This isn’t too much of a hardship, but Java 9 has made the process simpler by adding the stream method to Optional, whose signature is:

Stream<T> stream​()

If a value is present, this method returns a sequential, single element stream containing only that value. Otherwise it returns an empty stream. This method means that a stream of optional customers can be turned into a stream of customers directly, as in Example 10-30.

public Collection<Customer> findAllById(Integer... ids) {
    return Arrays.stream(ids)
            .map(this::findById)            
            .flatMap(Optional::stream)      
            .collect(Collectors.toList());
}

This is purely a convenience method, but a useful one.

The or method

The orElse method is used to extract a value from an Optional. It takes a default as an argument:

Customer customer = findById(id).orElse(Customer.DEFAULT)

There is also the orElseGet method that uses a Supplier to create the default, in the case where doing so is an expensive operation:

Customer customer = findById(id).orElseGet(() -> createDefaultCustomer())

Both of those return Customer instances. The or method on Optional, added in Java 9, allows you to return an Optional<Customer> instead, given a Supplier of them, so you can chain alternative ways of finding customers together.

The signature of the or method is:

Optional<T> or​(Supplier<? extends Optional<? extends T>> supplier)

If a value is present, this method returns an Optional describing it. Otherwise it invokes the Supplier and returns the Optional it returns.

Therefore, if we have multiple ways to find a customer, you can now write the code in Example 10-31.

public Optional<Customer> findById(int id) {
    return findByIdLocal(id)
            .or(() -> findByIdRemote(id))
            .or(() -> Optional.of(Customer.DEFAULT));

This method searches for the customer in the local cache and then accesses some remote server. If neither of those finds a nonempty Optional, the final clause creates a default, wraps it in an Optional, and returns it instead.

The ifPresentOrElse method

The ifPresent method on Optional executes a Consumer if the Optional is not empty, as in Example 10-32.

public void printCustomer(Integer id) {
    findByIdLocal(id).ifPresent(System.out::println);  
}

public void printCustomers(Integer... ids) {
    Arrays.asList(ids)
            .forEach(this::printCustomer);
}

This works, but you might want to run something else if the returned Optional is empty. The new ifPresentOrElse method takes a second, Runnable, argument that is executed if the Optional is empty. Its signature is:

void ifPresentOrElse​(Consumer<? super T> action, Runnable emptyAction)

To use it, simply provide a lambda that takes no arguments and returns void, as in Example 10-33.

public void printCustomer(Integer id) {
    findByIdLocal(id).ifPresentOrElse(System.out::println,
            () -> System.out.println("Customer with id=" + id + " not found"));
}

This version prints the customer if one is found, and prints a default message otherwise.

None of these additions to Optional change its behavior in any fundamental way, but they do provide conveniences when applicable.