Java service utilities

This library provides some utilities for Java SPI (Service Provider Interface).

The Java SPI is a mechanism that decouples a service from its implementation(s). It allows the creation of extensible or replaceable modules/plugins. It consists of four main components: a service, a service provider interface, some service providers and a service loader. If the service is a single interface then it is the same as a service provider interface.

Key points:

lightweight library with no dependency
no dependency at runtime, all the work is done at compile-time
Java 8 minimum requirement
has an automatic module name that makes it compatible with JPMS

Components

Annotation	Purpose
@ServiceProvider	registers a service provider
@ServiceDefinition	defines a service usage and generates a specialized loader
@ServiceId	specifies the method used to identify a service provider
@ServiceFilter	specifies the method used to filter a service provider
@ServiceSorter	specifies the method used to sort a service provider

@ServiceProvider

The @ServiceProvider annotation registers a service provider on classpath and modulepath.

Features:

generates classpath files in META-INF/services folder
supports multiple registration of one class
can infer the service if the provider implements/extends exactly one interface/class
checks coherence between classpath and modulepath if module-info.java is available

Limitations:

detects modulepath public static provider() method but doesn't generate a workaround for classpath

public interface FooSPI {}

public interface BarSPI {}

// 💡 One provider, one service
@ServiceProvider
public class FooProvider implements FooSPI {}

// 💡 One provider, multiple services
@ServiceProvider ( FooSPI.class )
@ServiceProvider ( BarSPI.class )
public class FooBarProvider implements FooSPI, BarSPI {}

@ServiceDefinition

The @ServiceDefinition annotation defines a service usage and generates a specialized loader that enforces that specific usage.

Features:

generates boilerplate code, thus reducing bugs and improving code coherence
improves documentation by declaring services explicitly and generating javadoc
checks coherence of service use in modules if module-info.java is available
allows identification
allows filtering and sorting
allows batch loading
allows custom backend

Limitations:

does not support type inspection before instantiation

Main properties:

#quantifier: number of services expected at runtime
#loaderName: custom qualified name of the loader
#fallback: fallback type for SINGLE quantifier
#batchType: bridge different services and generate providers on the fly

Advanced properties:

#mutability: on-demand set and reload
#singleton: loader scope
#wrapper: wrapper type on backend
#preprocessing: custom operations on backend
#backend #cleaner: custom service loader

Quantifier property

The #quantifier property specifies the number of services expected at runtime.

Values:

OPTIONAL: when a service is not guaranteed to be available such as OS-specific API

@ServiceDefinition(quantifier = Quantifier.OPTIONAL)
public interface WinRegistry {

  String readString(int hkey, String key, String valueName);

  int HKEY_LOCAL_MACHINE = 0;

  static void main(String[] args) {
    // 💡 Service availability not guaranteed
    Optional<WinRegistry> optional = WinRegistryLoader.load();
    optional.map(reg -> reg.readString(
            HKEY_LOCAL_MACHINE,
            "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion",
            "ProductName"))
        .ifPresent(System.out::println);
  }
}

Source: nbbrd/service/examples/WinRegistry.java

SINGLE: when exactly one service is guaranteed to be available

@ServiceDefinition(quantifier = Quantifier.SINGLE, fallback = LoggerFinder.FallbackLogger.class)
public interface LoggerFinder {

  Consumer<String> getLogger(String name);

  class FallbackLogger implements LoggerFinder {

    @Override
    public Consumer<String> getLogger(String name) {
      return msg -> System.out.printf(Locale.ROOT, "[%s] %s%n", name, msg);
    }
  }

  static void main(String[] args) {
    // 💡 Service availability guaranteed
    LoggerFinder single = LoggerFinderLoader.load();
    single.getLogger("MyClass").accept("some message");
  }
}

Source: nbbrd/service/examples/LoggerFinder.java

MULTIPLE: when several instances of a service could be used at the same time

@ServiceDefinition(quantifier = Quantifier.MULTIPLE)
public interface Translator {

  String translate(String text);

  static void main(String[] args) {
      // 💡 Multiple services expected
    List<Translator> multiple = TranslatorLoader.load();
    multiple.stream()
        .map(translator -> translator.translate("hello"))
        .forEach(System.out::println);
  }
}

Source: nbbrd/service/examples/Translator.java

Loader name property

The #loaderName property specifies the custom qualified name of the loader.

// 💡 Name without interpretation
@ServiceDefinition(loaderName = "internal.FooSPILoader")
public interface FooSPI { }

An empty value generates an automatic name.
A non-empty value is interpreted as a Mustache template with the following tags:

Tag	Description
`packageName`	The package name of the service class
`simpleName`	The service class name
`canonicalName`	The full service class name

// 💡 Name with interpretation
@ServiceDefinition(loaderName = "internal.{{simpleName}}Loader")
public interface FooSPI { }

Fallback property

The #fallback property specifies the fallback class to use if no service is available.
This property is only used in conjunction with Quantifier#SINGLE.

@ServiceDefinition(quantifier = Quantifier.SINGLE, fallback = NoOpFooProvider.class)
public interface FooSPI { }

// 💡 Provider that does nothing except preventing NPE
public class NoOpFooProvider implements FooSPI { }

Note that a warning is raised at compile time if the fallback is missing but this warning can be disabled with the @SupressWarning("SingleFallbackNotExpected") annotation.

Batch type property

The #batchType property allows to bridge different services and to generate providers on the fly.
Batch providers are used alongside regular providers.

@ServiceDefinition(quantifier = Quantifier.MULTIPLE, batchType = SwingColorScheme.Batch.class)
public interface SwingColorScheme {

  List<Color> getColors();

  static void main(String[] args) {
    // 💡 Invisible use of RgbColorScheme
    SwingColorSchemeLoader.load()
        .stream()
        .map(SwingColorScheme::getColors)
        .forEach(System.out::println);
  }

  interface Batch {
    Stream<SwingColorScheme> getProviders();
  }
  
  // 💡 Bridge between SwingColorScheme and RgbColorScheme
  @ServiceProvider(Batch.class)
  final class RgbBridge implements Batch {

    @Override
    public Stream<SwingColorScheme> getProviders() {
      return RgbColorSchemeLoader.load()
          .stream()
          .map(RgbAdapter::new);
    }
  }

  // 💡 Regular provider
  @ServiceProvider(SwingColorScheme.class)
  final class Cyan implements SwingColorScheme {

    @Override
    public List<Color> getColors() {
      return Collections.singletonList(Color.CYAN);
    }
  }
}

Source: nbbrd/service/examples/SwingColorScheme.java

Constraints:

Batch type must be an interface or an abstract class.
Batch method must be unique.