Providing a Service

he Java Platform Module System introduced a new construct called provides in the module descriptor in order for a module to be able to declare that it provides and exposes a service implementation for a specific service. Figure 6-1 illustrates its syntax.

Figure 6-1. The provides with clause

The provides with clause takes two parameters :

• <interface_name> represents the name of the service interface. It specifies the name of the service for which the current module provides an implementation. The service could be either a class or an interface.

• <class_name> represents the name of the class. It specifies the name of the class that implements the service interface. This class must be present in the current module. If it is not present in the current module, we get a compilation error.

A module uses the provides clause to inform the ServiceLoader that it provides an implementation of a service. Without this knowledge, the ServiceLoader wouldn’t have been able to load the service provider because it wouldn’t have been aware of it existence.

Jigsaw also allows for a single module to provide an implementation for a service and to also consume that service. But it does not allow for more than one provides statement to specify the same interface in a module declaration. A module declaration like this will never compile:

module myModule {
        provides myInterface with firstClass;
        provides myInterface with secondClass;
}

We mentioned previously the notion of consuming a service. The next subsection explains what this means and how it can be declared in Jigsaw.

Consuming a Service

In JDK 9, a module can explicitly declare that it consumes a service. For this, the service has to be discovered. Therefore, the uses clause was introduced in JDK 9 in the module declaration. It takes an interface as a parameter.

Figure 6-2 shows the syntax of the uses clause.

Figure 6-2. The uses clause

When should we use this clause? This clause should be used in modules that define a ServiceLoader<interface_name>, which loads service providers for the service with the name <interface_name>. If our module uses the ServiceLoader class to load services, then it’s mandatory to declare this in the module’s declaration using the uses clause, followed by the name of the service interface used.

This means that inside the module that declares the uses clause, a ServiceLoader is used, as in the following example:

Iterable<interface_name> ourInterfaces = ServiceLoader.load(interface_name.class);

Here, a ServiceLoader for services of type interface_name has been used.

Retrieving a ServiceLoader

We’ve already seen how to obtain a service loader. It can be done using the load() method , which comes in four flavours, according to the JDK 9 API specification:

• public static <S> ServiceLoader<S> load(Class<S> service)

  This method creates a new service loader for the given service type. It uses the context class loader of the current thread.

• public static <S> ServiceLoader<S> load(Class<S> service, ClassLoader loader)

  This method creates a new service loader and uses the given class loader to locate service providers for the service. Providers are located first in named modules and then in unnamed modules. Providers are located in all named modules of the class loader or to any class loader reachable via parent delegation.

• public static <S> ServiceLoader<S> load(ModuleLayer layer, Class<S> service)

  This method creates a new service loader for the given service type to load service providers from modules in the given module layer and its ancestors. It doesn’t locate providers in unnamed modules.

• public static <S> ServiceLoader<S> loadInstalled(Class<S> service)

  This method creates a new service loader for the given service type. It uses the platform class loader.

After we retrieve a ServiceLoader, we can iterate over all the service providers using the iterate() method. Another option would be to call the stream() method, which returns a stream to lazily load available providers. The syntax of the stream() method is as follows:

Stream<ServiceLoader.Provider<S>> stream()

Until now, we’ve seen how to retrieve a ServiceLoader and also how to provide and to consume a service. It’s time to see a practical example. We’ll use an example using one service consumer and one service provider. Then we’ll expand the example and show how to add more service providers.

Using One Consumer and One Provider

This section shows a simple example to illustrate the concepts presented earlier. Suppose we have three modules:

• Module com.apress.moduleA contains a simple interface called ServiceExample.

• Module com.apress.providerA defines a service provider that contains the class ServiceExampleImplementation1, which implements the interface from module com.apress.moduleA, ServiceExample.

• Module com.apress.consumer defines a service consumer that creates a new service loader for the ServiceExample service and uses this service.

Listing 6-1 shows the interface ServiceExample, defined inside the module com.apress.moduleA.

Listing 6-1. The Interface ServiceExample from the Module com.apress.moduleA

package com.apress.moduleA.interfaces;

public interface ServiceExample {

        String printHelloWorld();
}

The module descriptor of the module com.apress.moduleA is depicted in Listing 6-2. The package com.apress.moduleA.interfaces, where the interface is located, is exported.

Listing 6-2. The Module Descriptor of the Module com.apress.moduleA

module com.apress.moduleA {

        exports com.apress.moduleA.interfaces;
}

Until now we’ve only defined an interface inside of a module. Next we’ll define the provider module. Listing 6-3 shows the implementation class of the interface from the module com.apress.providerA.

Listing 6-3. The Implementation Class of Interface ServiceExample from Module com.apress.providerA

package com.apress.providerA;

import com.apress.moduleA.interfaces.ServiceExample;

public class ServiceExampleImplementation1 implements ServiceExample {

    public ServiceExampleImplementation() {
    }

    @Override
    public String printHelloWorld() {

        return "Hello World from ServiceExampleImplementation1";
    }
}

In Listing 6-4 you see the module descriptor of module com.apress.providerA.

Listing 6-4. The Module Descriptor of Module com.apress.providerA

module com.apress.providerA {
         requires com.apress.moduleA;
         provides com.apress.moduleA.interfaces.ServiceExample with com.apress.providerA.ServiceExampleImplementation1;
}

The module descriptor states that it provides an implementation of the ServiceExample interface with the class ServiceExampleImplementation1. This means that inside the module we have a class called ServiceExampleImplementation1 that implements the interface ServiceExample. The module descriptor also requires the com.apress.moduleA module because it has to access the interface in order to be able to implement it.

Listing 6-5 shows the content of module com.apress.consumer.

Listing 6-5. The Main Class of Module com.apress.consumer

package com.apress.consumer;

import com.apress.moduleA.interfaces.ServiceExample;
import java.util.ServiceLoader;

public class Main {

        public static void main(String[] args) {
                Iterable<ServiceExample> services = ServiceLoader.load(ServiceExample.class);
                for(ServiceExample serviceExample : services) {
                                System.out.println(serviceExample.printHelloWorld());
                }
        }
}

The Main class obtains instances of ServiceExample using the ServiceLoader from the java.util package. This is done by creating a new service loader for the ServiceExample type inside the Main class of the com.apress.consumer module. All instances of type ServiceExample are retrieved by calling the load() method with the ServiceExample.class parameter. Finally, we iterate through them and call the printHelloWorld() method on them.

Listing 6-6 shows the module-info.java file of the module com.apress.consumer.

Listing 6-6. The Module Descriptor of Module com.apress.consumer

module com.apress.consumer {
         requires com.apress.moduleA;
         uses com.apress.moduleA.interfaces.ServiceExample;
}

Module com.apress.consumer requires module com.apress.moduleA because it needs access to the interface to call the corresponding method on it. Additionally, it specifies that it uses the interface ServiceExample. This tells the module system that the module com.apress.consumer wants to consume instances of the com.apress.moduleA.interfaces.ServiceExample interface.

Finally, we compile the modules specified using the following command:

javac -d output --module-source-path src $(find . -name "*.java")

Then we run the following command:

java --module-path output -m com.apress.consumer/com.apress.consumer.Main

The output is printed inside the console:

Hello World from ServiceExampleImplementation1

We saw in this example how to define a simple service provider, a service consumer, and an interface in a separate module for the communication between the service provider and the service consumer. Both service provider and service consumer require only the interface. This means there’s a dependency between the service provider and the interface and respectively a dependency between the service consumer and the interface. It’s important to remember that there’s no dependency between the service provider and the service consumer. As a consequence, we don’t have tight coupling between those two modules.

Using One Consumer and Two Providers

Until now we’ve had only one service provider, but we can define many service providers and at the same time keeping the loosely coupled relation between the service providers at the service consumers. We’ll illustrate this concept with an example by defining another provider module.

Listing 6-7 shows the implementation class of the interface ServiceExample in the module com.apress.providerB.

Listing 6-7. The Implementation Class of Interface ServiceExample from Module com.apress.providerB

package com.apress.providerB;

import com.apress.moduleA.interfaces.ServiceExample;

public class ServiceExampleImplementation2 implements ServiceExample {

    public ServiceExampleImplementation2() {
    }

    @Override
    public String printHelloWorld() {
        return "Hello World from ServiceExampleImplementation2";
    }
}

Listing 6-8 shows the module descriptor of module com.apress.providerB .

Listing 6-8. The Module Descriptor of Module com.apress.providerB

module com.apress.providerB {
         requires com.apress.moduleA;
         provides com.apress.moduleA.interfaces.ServiceExample with com.apress.providerB.ServiceExampleImplementation2;
}

The module descriptor of module com.apress.providesB provides an implementation of the ServiceExample interface with the class ServiceExampleImplementation2.

By compiling and running the modules, the following result is printed in the console:

Hello World from ServiceExampleImplementation2
Hello World from ServiceExampleImplementation1

In this example, we defined two provider modules and saw how they interact in the context of the module system. None of the provider modules has a dependency upon the consumer module.

In our example, neither the provider modules nor the consumer module exports their packages. In this way, they’re encapsulated and can’t be accessed from outside. Nonetheless, Jigsaw has the capability to instantiate classes of type ServiceExampleImplementation1 because it implements the interface ServiceExample, which is defined using the provides directive inside the module-info.java of module com.apress.providerB.