Interface MessageConnector.IMessageConnection

Enclosing class:
MessageConnector

public static interface MessageConnector.IMessageConnection
A reliable, ordered, bidirectional message connection for complete Net4j frames. Providers assemble transport fragments before delivering a message. Each message includes the four-byte Net4j header.

Receive demand counts complete messages. Each received callback consumes one credit, and callbacks for a connection must be delivered in message order. The provider leases the supplied storage until its release action is invoked, and must not mutate or reuse the storage before then. After a complete message has been accepted by the listener, the connector may grant more demand independently of when that message's Net4j buffer is released. Providers must retain each leased frame's storage until its matching release action.

A rejected send must not retain or access its buffer after returning and must not invoke its callback. An exception thrown before acceptance has the same ownership result: the provider has not borrowed the buffer, must cease accessing it, and must not invoke its callback. Acceptance is reported by returning true. Once the provider borrows the buffer, it must return true and deliver exactly one terminal callback; the callback may happen before send(IBuffer, SendCallback) returns. A terminal callback guarantees that provider access to the buffer has ended. Throwing after borrowing the buffer violates this contract; an accepted send must return true and arrange its terminal callback. The provider must deliver terminal callbacks for every accepted send, including sends outstanding during shutdown.

If a provider permanently omits a terminal callback, safe reuse and eventual reclamation of that buffer cannot both be guaranteed. The connector bounds this risk to at most one buffer for each connection generation. Repeated activations can therefore leave one retained buffer in each generation whose provider omitted completion; this is not a global one-buffer limit. The connector must not use timeouts or premature release to conceal the missing ownership transfer.

Since:
4.23
Author:
Eike Stepper
  • Method Details

    • start

      Installs a listener and begins or attaches the connection. Implementations may call MessageConnector.IMessageConnection.Listener.ready() synchronously. A listener belongs to this connection generation and must not be used to signal readiness or input for another generation.
      Parameters:
      listener - the callbacks for this connection generation
    • send

      Attempts to send one complete framed buffer. At most one accepted send is submitted by a MessageConnector at a time. Returning false rejects the send: the provider must not borrow, retain, modify, release, or later access the buffer, and must not invoke the callback. Throwing before acceptance has the same ownership result and the provider must no longer access the buffer. Acceptance is reported by returning true; once the provider borrows the buffer, it must return true and deliver exactly one terminal callback, including after transport failure. Throwing after borrowing violates this contract; the provider must return true and arrange that accepted-send completion. All provider access to borrowed storage must have ended before the terminal callback.
      Parameters:
      buffer - the Net4j buffer borrowed for the send
      callback - completion of an accepted send
      Returns:
      true when accepted with exactly one terminal callback, or false when rejected without borrowing the buffer
    • request

      void request(long messages)
      Grants demand for complete incoming messages. Each delivered message consumes one credit. The provider must not deliver more messages than requested and must retain each supplied storage lease until the listener invokes its matching release action. The connector may grant further demand while earlier messages remain leased.
      Parameters:
      messages - positive number of additional messages requested
    • closeGracefully

      void closeGracefully()
      Starts graceful local closure after all sends already accepted by the provider have completed. Once closure begins, the provider rejects new sends and later reports closure through its listener.
    • abort

      void abort()
      Initiates immediate termination, prevents further sends from being accepted, and causes outstanding accepted sends to complete unsuccessfully unless already successfully completed. This method is safe concurrently with send(IBuffer, SendCallback) and must not wait indefinitely for callbacks. Borrowed buffers remain owned by the provider until their terminal callbacks, which may occur after this method returns.