Module io.helidon.inject.api
Package io.helidon.inject.api

Interface Services

public interface Services
The service registry. The service registry generally has knowledge about all the services that are available within your application, along with the contracts (i.e., interfaces) they advertise, the qualifiers that optionally describe them, and oll of each services' dependencies on other service contracts, etc.

Collectively these service instances are considered "the managed service instances" under Injection. A ServiceProvider wrapper provides lifecycle management on the underlying service instances that each provider "manages" in terms of activation, scoping, etc. The service providers are typically created during compile-time processing when the Injection APT processor is applied to your module (i.e., any service annotated using Singleton, Contract, Inject, etc.) during compile time. Additionally, they can be built using the Injection maven-plugin. Note also that the maven-plugin can be used to "compute" your applications entire DI model at compile time, generating an Application class that will be used at startup when found by the Injection framework.

This Services interface exposes a read-only set of methods providing access to these "managed service" providers, and available via one of the lookup methods provided. Once you resolve the service provider(s), the service provider can be activated by calling one of its get() methods. This is equivalent to the declarative form just using Inject instead. Note that activation of a service might result in activation chaining. For example, service A injects service B, etc. When service A is activated then service A's dependencies (i.e., injection points) need to be activated as well. To avoid long activation chaining, it is recommended to that users strive to use Provider injection whenever possible. Provider injection (a) breaks long activation chains from occurring by deferring activation until when those services are really needed, and (b) breaks circular references that lead to ServiceProviderInjectionException during activation (i.e., service A injects B, and service B injects A).

The services are ranked according to the provider's comparator. The Injection framework will rank according to a strategy that first looks for Weighted, then Priority, and finally by the alphabetic ordering according to the type name (package and class canonical name).

  • Method Summary

    Modifier and Type
    Method
    Description
    default Services
    contextualServices(io.helidon.inject.api.InjectionPointInfo ctx)
    Implementors can provide a means to use a "special" services registry that better applies to the target injection point context to apply for sub-lookup* operations.
    default ServiceProvider<?>
    lookup(io.helidon.inject.api.ServiceInfoCriteria criteria)
    Retrieves the first match based upon the passed service info criteria.
    default <T> ServiceProvider<T>
    lookup(Class<T> type)
    Retrieve the "first" service that implements a given contract type with the expectation that there is a match available.
    default <T> ServiceProvider<T>
    lookup(Class<T> type, String name)
    Retrieve the "first" named service that implements a given contract type with the expectation that there is a match available.
    default List<ServiceProvider<?>>
    lookupAll(io.helidon.inject.api.ServiceInfoCriteria criteria)
    Retrieve all services that match the criteria.
    List<ServiceProvider<?>>
    lookupAll(io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
    Retrieve all services that match the criteria.
    <T> List<ServiceProvider<T>>
    lookupAll(Class<T> type)
    Retrieve all services that implement a given contract type.
    default <T> List<ServiceProvider<T>>
    lookupAll(Class<T> type, io.helidon.inject.api.ServiceInfoCriteria criteria)
    Lookup all services that match the criteria and share a given contract type.
    default ServiceProvider<?>
    lookupFirst(io.helidon.inject.api.ServiceInfoCriteria criteria)
    Retrieves the first match based upon the passed service info criteria.
    Optional<ServiceProvider<?>>
    lookupFirst(io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
    Retrieves the first match based upon the passed service info criteria.
    default <T> ServiceProvider<T>
    lookupFirst(Class<T> type)
    Retrieves the first match based upon the passed service info criteria.
    <T> Optional<ServiceProvider<T>>
    lookupFirst(Class<T> type, boolean expected)
    Retrieve the "first" service that implements a given contract type with no expectation that there is a match available unless expected = true.
    default <T> Optional<ServiceProvider<T>>
    lookupFirst(Class<T> contract, io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
    Retrieves the first match based upon the passed service info criteria.
    <T> Optional<ServiceProvider<T>>
    lookupFirst(Class<T> type, String name, boolean expected)
    Retrieve the "first" service that implements a given contract type with no expectation that there is a match available unless expected = true.

  • Method Details

    • lookup

      default <T> ServiceProvider<T> lookup(Class<T> type)
      Retrieve the "first" service that implements a given contract type with the expectation that there is a match available.
      Type Parameters:
      T - the type of the service
      Parameters:
      type - the type to find
      Returns:
      the best service provider matching the criteria
      Throws:
      InjectionException - if resolution fails to resolve a match

    • lookup

      default <T> ServiceProvider<T> lookup(Class<T> type, String name)
      Retrieve the "first" named service that implements a given contract type with the expectation that there is a match available.
      Type Parameters:
      T - the type of the service
      Parameters:
      type - the type criteria to find
      name - the name for the service
      Returns:
      the best service provider matching the criteria
      Throws:
      InjectionException - if resolution fails to resolve a match

    • lookupFirst

      <T> Optional<ServiceProvider<T>> lookupFirst(Class<T> type, boolean expected)
      Retrieve the "first" service that implements a given contract type with no expectation that there is a match available unless expected = true.
      Type Parameters:
      T - the type of the service
      Parameters:
      type - the type criteria to find
      expected - indicates whether the provider should throw if a match is not found
      Returns:
      the best service provider matching the criteria, or empty if (@code expected = false) and no match found
      Throws:
      InjectionException - if expected=true and resolution fails to resolve a match

    • lookupFirst

      <T> Optional<ServiceProvider<T>> lookupFirst(Class<T> type, String name, boolean expected)
      Retrieve the "first" service that implements a given contract type with no expectation that there is a match available unless expected = true.
      Type Parameters:
      T - the type of the service
      Parameters:
      type - the type criteria to find
      name - the name for the service
      expected - indicates whether the provider should throw if a match is not found
      Returns:
      the best service provider matching the criteria, or empty if (@code expected = false) and no match found
      Throws:
      InjectionException - if expected=true and resolution fails to resolve a match

    • lookup

      default ServiceProvider<?> lookup(io.helidon.inject.api.ServiceInfoCriteria criteria)
      Retrieves the first match based upon the passed service info criteria.
      Parameters:
      criteria - the criteria to find
      Returns:
      the best service provider
      Throws:
      InjectionException - if resolution fails to resolve a match

    • lookupFirst

      Optional<ServiceProvider<?>> lookupFirst(io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
      Retrieves the first match based upon the passed service info criteria.
      Parameters:
      criteria - the criteria to find
      expected - indicates whether the provider should throw if a match is not found
      Returns:
      the best service provider matching the criteria, or empty if (@code expected = false) and no match found
      Throws:
      InjectionException - if expected=true and resolution fails to resolve a match

    • lookupFirst

      default <T> Optional<ServiceProvider<T>> lookupFirst(Class<T> contract, io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
      Retrieves the first match based upon the passed service info criteria.
      Type Parameters:
      T - type of the service
      Parameters:
      contract - contract that must be implemented
      criteria - the criteria to find
      expected - indicates whether the provider should throw if a match is not found
      Returns:
      the best service provider matching the criteria, or empty if (@code expected = false) and no match found
      Throws:
      InjectionException - if expected=true and resolution fails to resolve a match

    • lookupFirst

      default ServiceProvider<?> lookupFirst(io.helidon.inject.api.ServiceInfoCriteria criteria)
      Retrieves the first match based upon the passed service info criteria.

      This is the same as calling the following: 

           lookupFirst(criteria, true).orElseThrow();
      Parameters:
      criteria - the criteria to find
      Returns:
      the best service provider matching the criteria
      Throws:
      InjectionException - if resolution fails to resolve a match

    • lookupFirst

      default <T> ServiceProvider<T> lookupFirst(Class<T> type)
      Retrieves the first match based upon the passed service info criteria.

      This is the same as calling the following: 

           lookupFirst(criteria, true).orElseThrow();
      Type Parameters:
      T - the type of the service
      Parameters:
      type - the type criteria to find
      Returns:
      the best service provider matching the criteria
      Throws:
      InjectionException - if resolution fails to resolve a match

    • lookupAll

      <T> List<ServiceProvider<T>> lookupAll(Class<T> type)
      Retrieve all services that implement a given contract type.
      Type Parameters:
      T - the type of the service being managed
      Parameters:
      type - the type criteria to find
      Returns:
      the list of service providers matching criteria

    • lookupAll

      default List<ServiceProvider<?>> lookupAll(io.helidon.inject.api.ServiceInfoCriteria criteria)
      Retrieve all services that match the criteria.
      Parameters:
      criteria - the criteria to find
      Returns:
      the list of service providers matching criteria

    • lookupAll

      default <T> List<ServiceProvider<T>> lookupAll(Class<T> type, io.helidon.inject.api.ServiceInfoCriteria criteria)
      Lookup all services that match the criteria and share a given contract type.
      Type Parameters:
      T - type of the service being managed
      Parameters:
      type - the type criteria to find
      criteria - additional criteria
      Returns:
      list of service providers matching criteria

    • lookupAll

      List<ServiceProvider<?>> lookupAll(io.helidon.inject.api.ServiceInfoCriteria criteria, boolean expected)
      Retrieve all services that match the criteria.
      Parameters:
      criteria - the criteria to find
      expected - indicates whether the provider should throw if a match is not found
      Returns:
      the list of service providers matching criteria

    • contextualServices

      default Services contextualServices(io.helidon.inject.api.InjectionPointInfo ctx)
      Implementors can provide a means to use a "special" services registry that better applies to the target injection point context to apply for sub-lookup* operations. If the provider does not support contextual lookup then the same services instance as this will be returned.
      Parameters:
      ctx - the injection point context to use to filter the services to what qualifies for this injection point
      Returns:
      the qualifying services relative to the given context
      See Also:
      • InjectionServicesConfigBlueprint.supportsContextualLookup()