Module io.helidon.pico.api
Package io.helidon.pico.api

Interface PicoServices

public interface PicoServices
Abstract factory for all services provided by a single Helidon Pico provider implementation. An implementation of this interface must minimally supply a "services registry" - see services().

The global singleton instance is accessed via picoServices(). Note that optionally one can provide a primordial bootstrap configuration to the Pico services provider. One must establish any bootstrap instance prior to the first call to picoServices() as it will use a default configuration if not explicitly set. Once the bootstrap has been set it cannot be changed for the lifespan of the JVM.

  • Field Details

    • EMPTY_CRITERIA

      static final ServiceInfoCriteria EMPTY_CRITERIA
      Empty criteria will match anything and everything.

    • SERVICE_QUERY_REQUIRED

      static final ContextualServiceQuery SERVICE_QUERY_REQUIRED
      Denotes a match to any (default) service, but required to be matched to at least one.

  • Method Details

    • bootstrap

      Bootstrap bootstrap()
      Returns the Bootstrap configuration instance that was used to initialize this instance.
      Returns:
      the bootstrap configuration instance

    • isDebugEnabled

      static boolean isDebugEnabled()
      Returns true if debugging is enabled.
      Returns:
      true if debugging is enabled
      See Also:

    • globalBootstrap

      static Optional<Bootstrap> globalBootstrap()
      Retrieves any primordial bootstrap configuration that previously set.
      Returns:
      the bootstrap primordial configuration already assigned
      See Also:

    • realizedGlobalBootStrap

      static Bootstrap realizedGlobalBootStrap()
      First attempts to locate and return the globalBootstrap() and if not found will create a new bootstrap instance.
      Returns:
      a bootstrap

    • globalBootstrap

      static void globalBootstrap(Bootstrap bootstrap)
      Sets the primordial bootstrap configuration that will supply picoServices() during global singleton initialization.
      Parameters:
      bootstrap - the primordial global bootstrap configuration
      See Also:

    • picoServices

      static Optional<PicoServices> picoServices()
      Get PicoServices instance if available. The highest Weighted service will be loaded and returned. Remember to optionally configure any primordial Bootstrap configuration prior to the first call to get PicoServices.
      Returns:
      the Pico services instance

    • realizedServices

      static Services realizedServices()
      Short-cut for the following code block. During the first invocation the Services registry will be initialized. 
       
   return picoServices().orElseThrow().services();
      Returns:
      the services instance

    • unrealizedServices

      static Optional<Services> unrealizedServices()
      Similar to services(), but here if Pico is not available or the services registry has not yet been initialized then this method will return Optional.empty(). This is convenience for users who conditionally want to use Pico's service registry if it is currently available and in active use, but if not do alternative processing or allocations directly, etc.
      Returns:
      the services instance if it has already been activated and initialized, empty otherwise

    • services

      default Services services()
      The service registry. The first call typically loads and initializes the service registry. To avoid automatic loading and initialization on any first request then consider using unrealizedServices() or services(boolean).
      Returns:
      the services registry

    • services

      Optional<? extends Services> services(boolean initialize)
      The service registry. The first call typically loads and initializes the service registry.
      Parameters:
      initialize - true to allow initialization applicable for the 1st request, false to prevent 1st call initialization
      Returns:
      the services registry if it is available and already has been initialized, empty if not yet initialized

    • config

      PicoServicesConfig config()
      The governing configuration.
      Returns:
      the config

    • injector

      Optional<Injector> injector()
      Optionally, the injector.
      Returns:
      the injector, or empty if not available

    • shutdown

      Optional<Map<String,ActivationResult>> shutdown()
      Attempts to perform a graceful Injector.deactivate(Object, InjectorOptions) on all managed service instances in the Services registry. Deactivation is handled within the current thread.

      If the service provider does not support shutdown an empty is returned.

      The default reference implementation for Pico will return a map of all service types that were deactivated to any throwable that was observed during that services shutdown sequence.

      The order in which services are deactivated is dependent upon whether the activationLog() is available. If the activation log is available, then services will be shutdown in reverse chronological order as how they were started. If the activation log is not enabled or found to be empty then the deactivation will be in reverse order of RunLevel from the highest value down to the lowest value. If two services share the same RunLevel value then the ordering will be based upon the implementation's comparator.

      When shutdown returns, it is guaranteed that all services were shutdown, or failed to achieve shutdown.

      Returns:
      a map of all managed service types deactivated to results of deactivation, or empty if shutdown is not supported

    • activationLog

      Optional<ActivationLog> activationLog()
      Optionally, the service provider activation log.
      Returns:
      the injector, or empty if not available

    • metrics

      Optional<Metrics> metrics()
      Optionally, the metrics that are exposed by the provider implementation.
      Returns:
      the metrics, or empty if not available

    • lookups

      Optional<Set<ServiceInfoCriteria>> lookups()
      Optionally, the set of Services lookup criteria that were recorded. This is only available if PicoServicesConfig.serviceLookupCaching() is enabled.
      Returns:
      the lookup criteria recorded, or empty if not available

    • createDefaultActivationRequest

      static ActivationRequest createDefaultActivationRequest()
      Will create an activation request either to Phase.ACTIVE or limited to any Bootstrap.limitRuntimePhase() specified.
      Returns:
      the activation request

    • terminalActivationPhase

      static Phase terminalActivationPhase()
      The terminal phase for activation that we should not cross.
      Returns:
      the terminal phase for activation