Interface Transport

All Known Implementing Classes:
EPollTransport, IOUringTransport

public interface Transport
A very abstract notion of a transport for a particular implementation of the WebServer interface.

A Transport encompasses certain parts of the inner workings of a given WebServer implementation that simultaneously should not be exposed but need to be configurable.

A WebServer implementation may call createTransportArtifact(Class, String, ServerConfiguration) during startup, and then never again, passing non-null arguments. Only one call per combination of artifactType and artifactName is permitted.

It is not expected or required that implementations of this interface be safe for concurrent use by multiple threads.

See Also:
  • Method Details

    • isAvailableFor

      boolean isAvailableFor(WebServer webserver)
      Returns true if this Transport implementation is available for use by the given WebServer implementation; false otherwise.

      Implementations of this method must be idempotent and deterministic.

      WebServer implementations normally call this method, supplying themselves, and interpret its return value before performing any invocation of createTransportArtifact(Class, String, ServerConfiguration).

      If a given Transport implementation returns false from its implementation of this method, then a given WebServer implementation is permitted to discard it and use another Transport implementation instead.

      The WebServer passed to this method is in a deliberately undefined state. Most notably, it has not yet been configured, and it is in the process of being constructed. Most Transport implementations should either not use this parameter at all or, for example, should only test it to see if it is an implementation of WebServer that they support.

      webserver - the WebServer implementation in a deliberately undefined state and currently being constructed
      true if this Transport implementation is available for use; false otherwise
    • createTransportArtifact

      <T> Optional<T> createTransportArtifact(Class<T> type, String name, ServerConfiguration config)
      Creates and returns a suitable transport artifact, if one can be created or is available, and an empty Optional otherwise.

      A transport artifact is a deliberately opaque item that is defined by a particular WebServer implementation that is needed at startup time. A transport artifact has a String-typed name and a Class-typed type. A WebServer implementation may call this method only after having received true from an invocation of isAvailableFor(WebServer).

      A WebServer implementation must not call this method more than once per combination of type and name or undefined behavior will result.

      No further specifications of any kind are made regarding the behavior of any implementation of this method. Specifically, an implementation may create a new artifact, or return a cached one.

      Implementations of this method are called while a WebServer implementation is in the process of being constructed and while it is in a deliberately undefined state.

      Type Parameters:
      T - the type of the transport artifact
      type - a Class that can help to identify the kind of artifact to be returned
      name - the WebServer-implementation-specific name of a specific transport artifact of the given type that should be returned
      config - the finalized ServerConfiguration in effect during construction of the WebServer implementation
      an Optional, possibly empty, representing the desired transport artifact