Interface HttpServiceLocator

All Superinterfaces:
ServerLifecycle
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface HttpServiceLocator extends ServerLifecycle
Locates an HttpService for a matched request.

Service locators are registered with HttpRules.registerLocator(HttpServiceLocator) or HttpRules.registerLocator(String, HttpServiceLocator). The locator is invoked at request time after the locator's path pattern matches. Path parameters from the locator path pattern are available from ServerRequest.path().

Returning Optional.empty() means this locator has no service for the request and routing should continue with the next available route.

The locator participates in the server lifecycle through ServerLifecycle. WebServer configures each distinct located service lazily and caches its routes by service instance identity until the server stops. Before cached routes are used, the located service receives any lifecycle callbacks needed to bring it to the current server lifecycle phase. Each cached service receives ServerLifecycle.afterStop() when the server stops.

Locators must return a stable, bounded set of service instances. When a locator returns an additional service instance after its cache reaches maxServiceCacheSize(), WebServer rejects the request with Status.SERVICE_UNAVAILABLE_503. Override maxServiceCacheSize() when a locator intentionally exposes more stable identities than the default.

  • Field Details

    • DEFAULT_MAX_SERVICE_CACHE_SIZE

      static final int DEFAULT_MAX_SERVICE_CACHE_SIZE
      Default maximum number of service instances cached by one locator.
      See Also:

  • Method Details

    • create

      static HttpServiceLocator create(Function<ServerRequest, Optional<HttpService>> locator)
      Create a service locator from a locating function.
      Parameters:
      locator - function to locate a service
      Returns:
      service locator

    • locate

      Optional<HttpService> locate(ServerRequest request)
      Locate an HTTP service for the current request.
      Parameters:
      request - server request, never null
      Returns:
      located service, or empty if this locator has no service for this request

    • maxServiceCacheSize

      default int maxServiceCacheSize()
      Maximum number of distinct service instances this locator may cache.

      The value must be greater than zero.

      Returns:
      maximum number of cached service instances, defaults to 1024