Interface Transport

All Known Implementing Classes:
MemoryTransport, QuicheTransport, Transport.IP, Transport.Socket, Transport.TCPIP, Transport.TCPUnix, Transport.UDPIP, Transport.UDPUnix, Transport.Unix, Transport.Wrapper
public interface Transport

The low-level transport used by clients.

A high-level protocol such as HTTP/1.1 can be transported over a low-level protocol such as TCP/IP, Unix-Domain sockets, QUIC, shared memory, etc.

This class defines the programming interface to implement low-level protocols, and useful implementations for commonly used low-level protocols such as TCP/IP or Unix-Domain sockets.

Low-level transports may be layered; some of them maybe considered lower-level than others, but from the point of view of the high-level protocols they are all considered low-level.

For example, QUIC is typically layered on top of the UDP/IP low-level Transport, but it may be layered on top Unix-Domain sockets, or on top of shared memory. As QUIC provides a reliable, ordered, stream-based transport, it may be seen as a replacement for TCP, and high-level protocols that need a reliable, ordered, stream-based transport may use either the non-layered TCP/IP or the layered QUIC over UDP/IP without noticing the difference. This makes possible to transport HTTP/1.1 over QUIC over Unix-Domain sockets, or HTTP/2 over QUIC over shared memory, etc.

  • Field Details

    • CONTEXT_KEY

      static final String CONTEXT_KEY

    • TCP_IP

      static final Transport TCP_IP

      The TCP/IP Transport.

    • UDP_IP

      static final Transport UDP_IP

      The UDP/IP Transport.

  • Method Details

    • isIntrinsicallySecure

      default boolean isIntrinsicallySecure()
      Returns:
      whether this Transport is intrinsically secure.

    • requiresDomainNameResolution

      default boolean requiresDomainNameResolution()

      Returns whether this Transport requires resolution of domain names.

      When domain name resolution is required, it must be performed by an external service, and the value returned by getSocketAddress() is ignored, while the resolved socket address is eventually passed to connect(SocketAddress, Map). Otherwise, domain name resolution is not required, and the value returned by getSocketAddress() is eventually passed to connect(SocketAddress, Map).

      Returns:
      whether this Transport requires domain names resolution

    • connect

      default void connect(SocketAddress socketAddress, Map<String,Object> context)

      Establishes a connection to the given socket address.

      For Transports that require domain name resolution, this is the IP address resolved from the domain name. For Transports that do not require domain name resolution (for example Unix-Domain sockets, or memory) this is the socket address to connect to.

      Parameters:
      socketAddress - the socket address to connect to
      context - the context information to establish the connection

    • getSocketAddress

      default SocketAddress getSocketAddress()
      Returns:
      the socket address to connect to in case domain name resolution is not required

    • newSelectableChannel

      default SelectableChannel newSelectableChannel() throws IOException

      For Transports that are based on sockets, or for Transports that are layered on top of another Transport that is based on sockets, this method is invoked to create a new SelectableChannel used for the socket communication.

      Returns:
      a new SelectableChannel used for the socket communication, or null if the communication does not use sockets.
      Throws:
      IOException - if the SelectableChannel cannot be created

    • newEndPoint

      default EndPoint newEndPoint(Scheduler scheduler, ManagedSelector selector, SelectableChannel selectable, SelectionKey selectionKey)

      For Transports that are based on sockets, or for Transports that are layered on top of another Transport that is based on sockets, this method is invoked to create a new EndPoint that wraps the SelectableChannel created by newSelectableChannel().

      Parameters:
      scheduler - the Scheduler
      selector - the ManagedSelector
      selectable - the SelectableChannel
      selectionKey - the SelectionKey
      Returns:
      a new EndPoint

    • newClientConnectionFactory

      default ClientConnectionFactory newClientConnectionFactory(ClientConnector connector, ClientConnectionFactory factory)

    • newConnection

      default Connection newConnection(EndPoint endPoint, Map<String,Object> context) throws IOException

      Creates a new Connection to be associated with the given low-level EndPoint.

      For non-layered Transports such as TCP/IP, the Connection is typically that of the high-level protocol. For layered Transports such as QUIC, the Connection is typically that of the layered Transport.

      Parameters:
      endPoint - the EndPoint to associate the Connection to
      context - the context information to create the connection
      Returns:
      a new Connection
      Throws:
      IOException - if the Connection cannot be created

    • hashCode

      int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      boolean equals(Object obj)
      Overrides:
      equals in class Object