Java java.lang.Module API

1. Introduction

Following A Guide to Java 9 Modularity, in this article, we’re going to explore the java.lang.Module API that was introduced alongside the Java Platform Module System.

This API provides a way to access a module programmatically, to retrieve specific information from a module, and generally to work with it and its ModuleDescriptor.

2. Reading Module Information

The Module class represents both named and unnamed modules. Named modules have a name and are constructed by the Java Virtual Machine when it creates a module layer, using a graph of modules as a definition.

An unnamed module doesn’t have a name, and there is one for each ClassLoader. All types that aren’t in a named module are members of the unnamed module related to their class loader.

The interesting part of the Module class is that it exposes methods that allow us to retrieve information from the module, like the module name, the module classloader and the packages within the module.

Let’s see how it’s possible to find out if a module is named or unnamed.

2.1. Named or Unnamed

Using the isNamed() method we can identify whether a module is named or not.

Let’s see how we can see if a given class, like HashMap, is part of a named module and how we can retrieve its name:

Module javaBaseModule = HashMap.class.getModule();

assertThat(javaBaseModule.isNamed(), is(true));
assertThat(javaBaseModule.getName(), is("java.base"));

Let’s now define a Person class:

public class Person {
    private String name;

    // constructor, getters and setters
}

In the same way, as we did for the HashMap class, we can check if the Person class is part of a named module:

Module module = Person.class.getModule();

assertThat(module.isNamed(), is(false));
assertThat(module.getName(), is(nullValue()));

2.2. Packages

When working with a module, it might be important to know which packages are available within the module.

Let’s see how we can check if a given package, for example, java.lang.annotation, is contained in a given module:

assertTrue(javaBaseModule.getPackages().contains("java.lang.annotation"));
assertFalse(javaBaseModule.getPackages().contains("java.sql"));

2.3. Annotations

In the same way, as for the packages, it’s possible to retrieve the annotations that are present in the module using the getAnnotations() method.

If there are no annotations present in a named module, the method will return an empty array.

Let’s see how many annotations are present in the java.base module:

assertThat(javaBaseModule.getAnnotations().length, is(0));

When invoked on an unnamed module, the getAnnotations() method will return an empty array.

2.4. ClassLoader

Thanks to the getClassLoader() method available within the Module class, we can retrieve the ClassLoader for a given module:

assertThat(
  module.getClassLoader().getClass().getName(), 
  is("jdk.internal.loader.ClassLoaders$AppClassLoader")
);

2.5. Layer

Another valuable information that could be extracted from a module is the ModuleLayer, which represents a layer of modules in the Java virtual machine.

A module layer informs the JVM about the classes that may be loaded from the modules. In this way, the JVM knows exactly which module each class is a member of.

A ModuleLayer contains information related to its configuration, the parent layer and the set of modules available within the layer.

Let’s see how to retrieve the ModuleLayer of a given a module:

ModuleLayer javaBaseModuleLayer = javaBaseModule.getLayer();

Once we have retrieved the ModuleLayer, we can access its information:

assertTrue(javaBaseModuleLayer.configuration().findModule("java.base").isPresent());

A special case is the boot layer, created when Java Virtual Machine is started. The boot layer is the only layer that contains the java.base module.

3. Dealing With ModuleDescriptor

A ModuleDescriptor describes a named module and defines methods to obtain each of its components.

ModuleDescriptor objects are immutable and safe for use by multiple concurrent threads.

Let’s start by looking at how we can retrieve a ModuleDescriptor.

3.1. Retrieving a ModuleDescriptor

Since the ModuleDescriptor is tightly connected to a Module, it’s possible to retrieve it directly from a Module:

ModuleDescriptor moduleDescriptor = javaBaseModule.getDescriptor();

3.2. Creating a ModuleDescriptor

It’s also possible to create a module descriptor using the ModuleDescriptor.Builder class or by reading the binary form of a module declaration, the module-info.class.

Let’s see how we create a module descriptor using the ModuleDescriptor.Builder API:

ModuleDescriptor.Builder moduleBuilder = ModuleDescriptor
  .newModule("baeldung.base");

ModuleDescriptor moduleDescriptor = moduleBuilder.build();

assertThat(moduleDescriptor.name(), is("baeldung.base"));

With this, we created a normal module but in case we want to create an open module or an automatic one, we can respectively use the newOpenModule() or the newAutomaticModule() method.

3.3. Classifying a Module

A module descriptor describes a normal, open, or automatic module.

Thanks to the method available within the ModuleDescriptor, it’s possible to identify the type of the module:

ModuleDescriptor moduleDescriptor = javaBaseModule.getDescriptor();

assertFalse(moduleDescriptor.isAutomatic());
assertFalse(moduleDescriptor.isOpen());

3.4. Retrieving Requires

With a module descriptor, it’s possible to retrieve the set of Requires, representing the module dependencies.

This is possible using the requires() method:

Set<Requires> javaBaseRequires = javaBaseModule.getDescriptor().requires();
Set<Requires> javaSqlRequires = javaSqlModule.getDescriptor().requires();

Set<String> javaSqlRequiresNames = javaSqlRequires.stream()
  .map(Requires::name)
  .collect(Collectors.toSet());

assertThat(javaBaseRequires, empty());
assertThat(javaSqlRequiresNames, hasItems("java.base", "java.xml", "java.logging"));

All modules, except java.base, have the java.base module as a dependency.

However, if the module is an automatic module, the set of dependencies will be empty except for the java.base one.

3.5. Retrieving Provides

With the provides() method it’s possible to retrieve the list of services that the module provides:

Set<Provides> javaBaseProvides = javaBaseModule.getDescriptor().provides();
Set<Provides> javaSqlProvides = javaSqlModule.getDescriptor().provides();

Set<String> javaBaseProvidesService = javaBaseProvides.stream()
  .map(Provides::service)
  .collect(Collectors.toSet());

assertThat(javaBaseProvidesService, hasItem("java.nio.file.spi.FileSystemProvider"));
assertThat(javaSqlProvides, empty());

3.6. Retrieving Exports

Using the exports() method, we can find out if the modules exports packages and which in particular:

Set<Exports> javaSqlExports = javaSqlModule.getDescriptor().exports();

Set<String> javaSqlExportsSource = javaSqlExports.stream()
  .map(Exports::source)
  .collect(Collectors.toSet());

assertThat(javaSqlExportsSource, hasItems("java.sql", "javax.sql"));

As a special case, if the module is an automatic one, the set of exported packages will be empty.

3.7. Retrieving Uses

With the uses() method, it’s possible to retrieve the set of service dependencies of the module:

Set<String> javaSqlUses = javaSqlModule.getDescriptor().uses();

assertThat(javaSqlUses, hasItem("java.sql.Driver"));

In case the module is an automatic one, the set of dependencies will be empty.

3.8. Retrieving Opens

Whenever we want to retrieve the list of the open packages of a module, we can use the opens() method:

Set<Opens> javaBaseUses = javaBaseModule.getDescriptor().opens();
Set<Opens> javaSqlUses = javaSqlModule.getDescriptor().opens();

assertThat(javaBaseUses, empty());
assertThat(javaSqlUses, empty());

The set will be empty if the module is an open or an automatic one.

4. Dealing With Modules

Working with the Module API, other than reading information from the module, we can update a module definition.

4.1. Adding Exports

Let’s see how we can update a module, exporting the given package from a given module:

Module updatedModule = module.addExports(
  "com.baeldung.java9.modules", javaSqlModule);

assertTrue(updatedModule.isExported("com.baeldung.java9.modules"));

This can be done only if the caller’s module is the module the code is a member of.

As a side note, there are no effects if the package is already exported by the module or if the module is an open one.

4.2. Adding Reads

When we want to update a module to read a given module, we can use the addReads() method:

Module updatedModule = module.addReads(javaSqlModule);

assertTrue(updatedModule.canRead(javaSqlModule));

This method does nothing if we add the module itself since all modules read themselves.

In the same way, this method does nothing if the module is an unnamed module or this module already reads the other.

4.3. Adding Opens

When we want to update a module that has opened a package to at least the caller module, we can use addOpens() to open the package to another module:

Module updatedModule = module.addOpens(
  "com.baeldung.java9.modules", javaSqlModule);

assertTrue(updatedModule.isOpen("com.baeldung.java9.modules", javaSqlModule));

This method has no effect if the package is already open to the given module.

4.4. Adding Uses

Whenever we want to update a module adding a service dependency, the method addUses() is our choice:

Module updatedModule = module.addUses(Driver.class);

assertTrue(updatedModule.canUse(Driver.class));

This method does nothing when invoked on an unnamed module or an automatic module.

5. Conclusion

In this article, we explored the use of the java.lang.Module API where we learned how to retrieve information of a module, how to use a ModuleDescriptor to access additional information regarding a module and how to manipulate it.