Interface ServiceRegistry

public interface ServiceRegistry
The service registry manages and provides access to service providers. Services are interfaces which define a set of methods a provider of a service must implement. Modules and/or plugins can query implementations from the registry (if one is available for the given service). If multiple service providers are present for a service the caller must explicitly select one by their name or use the provider which was marked as the default for the service.
Since:
4.0

  • Method Details

    • registry

      @NonNull static @NonNull ServiceRegistry registry()
      Get the jvm-static singleton instance of the service registry. The returned instance is the same as retrievable from injection. If available callers should opt for using dependency injection instead.
      Returns:
      the jvm-static singleton instance of the service registry.

    • discoverServices

      void discoverServices(@NonNull @NonNull Class<?> owner)
      Discovers and registers all auto service definitions which were generated by the annotation processor and that are available from the code source of the given owner class. The method does the following steps to resolve the service definitions:
      1. Resolve the code source of the given owner class (e.g. the containing jar file)
      2. Resolve the autoservices directory in the resolved code source.
      3. Visit all files in that directory and register the deserialized bindings from the file.

      The class loader of the given owner class is used to resolve class references, for example the implementation types. When a non-singleton service instance needs to be constructed, the injection layer of the given owner class will be used to construct the instance. If a different behaviour is needed the caller should not use auto service registration and register the services manually instead.

      Parameters:
      owner - a class from the owning class source of the auto service bindings to register.
      Throws:
      NullPointerException - if the given owner class is null.
      IllegalStateException - if the auto service mappings cannot be deserialized.

    • registerProvider

      @NonNull <S> @NonNull ServiceRegistryRegistration<S> registerProvider(@NonNull @NonNull Class<S> serviceType, @NonNull @NonNull String serviceName, @NonNull S serviceImplementation)
      Registers a singleton service into this service registry. Each retrieval of the service will return an accessor to the given singleton instance to call methods on. If another service implementation with the same name is already registered, this method invocation will be ignored and the registration of the already registered provider is returned instead.
      Type Parameters:
      S - the service type model.
      Parameters:
      serviceType - the type of the service with which the implementation should be associated.
      serviceName - the name of the implementation for later retrievals.
      serviceImplementation - the implementation instance of the service to bind to.
      Returns:
      a registration to the newly or already registered service registration.
      Throws:
      NullPointerException - if the service type, name or implementation is null.
      IllegalArgumentException - if the service type is not an interface, the impl is not extending the service type or the service name is empty.

    • registerConstructingProvider

      @NonNull <S> @NonNull ServiceRegistryRegistration<S> registerConstructingProvider(@NonNull @NonNull Class<S> serviceType, @NonNull @NonNull String serviceName, @NonNull @NonNull Class<? extends S> implementationType)
      Registers a service into this service registry which will return a new instance on each invocation, using the public no-arg constructor in the given implementation type. If another service implementation with the same name is already registered, this method invocation will be ignored and the registration of the already registered provider is returned instead.
      Type Parameters:
      S - the service type model.
      Parameters:
      serviceType - the type of the service with which the implementation should be associated.
      serviceName - the name of the implementation for later retrievals.
      implementationType - the implementation type to constructor for service instances.
      Returns:
      a registration to the newly or already registered service registration.
      Throws:
      NullPointerException - if the service type, name or implementation type is null.
      IllegalArgumentException - if the service type is not an interface, the impl type is not extending the service type, the service name is empty or the impl type does not contain a public, accessible no-arg constructor.

    • unregisterAll

      void unregisterAll(@NonNull @NonNull ClassLoader classLoader)
      Unregisters all service registrations from this registry whose
      1. service type uses the given class loader.
      2. implementation type uses the given class loader.
      Parameters:
      classLoader - the class loader of which all associated registrations should be removed.
      Throws:
      NullPointerException - if the given class loader is null.

    • registeredServiceTypes

      @NonNull @NonNull @UnmodifiableView Collection<Class<?>> registeredServiceTypes()
      Get all service types for which an implementation was registered. Updates to the underlying collection are reflected into the returned collection, but no changes can be made to the returned collection.
      Returns:
      all service types for which an implementation was registered.

    • registration

      <S> @UnknownNullability ServiceRegistryRegistration<S> registration(@NonNull @NonNull Class<S> service, @NonNull @NonNull String name)
      Get the registration of a service implementation based on the given service type and name.
      Type Parameters:
      S - the service type model.
      Parameters:
      service - the service type to retrieve an implementation of.
      name - the name of the implementation to get.
      Returns:
      the registration of the implementation for the service type and name, null if no such registration exists.
      Throws:
      NullPointerException - if the given service type or name is null.

    • defaultRegistration

      <S> @UnknownNullability ServiceRegistryRegistration<S> defaultRegistration(@NonNull @NonNull Class<S> service)
      Get the default registration for the given service in this service registry. The implementation might return a proxy which always returns information about the current default implementation instead of the actual default implementation registration.
      Type Parameters:
      S - the service type model.
      Parameters:
      service - the service to the default implementation registration of.
      Returns:
      the registration of the default impl for the given service or null if no impl for the service is present.
      Throws:
      NullPointerException - if the given service type is null.

    • registrations

      @NonNull <S> @NonNull @UnmodifiableView Collection<ServiceRegistryRegistration<S>> registrations(@NonNull @NonNull Class<S> service)
      Get a view of all registrations which are present for the given service type. Updates to the underlying collection are reflected into the returned collection, but no changes can be made to the returned collection. This rule does not apply if no implementations for the service type is present in which case the implementation might return an empty collection that will not see any updates on registrations.
      Type Parameters:
      S - the service type model.
      Parameters:
      service - the service to get the available registrations of.
      Returns:
      a collection of all registrations for the given service type.
      Throws:
      NullPointerException - if the given service type is null.

    • instance

      default <S> @UnknownNullability S instance(@NonNull @NonNull Class<S> service, @NonNull @NonNull String name)
      Get the instance of a service implementation based on the given service type and name.
      Type Parameters:
      S - the service type model.
      Parameters:
      service - the service type to retrieve the implementation of.
      name - the name of the implementation to get.
      Returns:
      the instance of the implementation for the service type and name, null if no such registration exists.
      Throws:
      NullPointerException - if the given service type or name is null.

    • defaultInstance

      default <S> @UnknownNullability S defaultInstance(@NonNull @NonNull Class<S> service)
      Get the instance of the default service implementation for the given service type. The implementation might decide to return a proxy so that each invocation on the returned instance will always happen on the current default implementation, even if the default changes during the lifetime of the returned instance.
      Type Parameters:
      S - the service type model.
      Parameters:
      service - the service type to retrieve the default implementation of.
      Returns:
      the instance of the default implementation for the service type, null if no such registration exists.
      Throws:
      NullPointerException - if the given service type is null.