Package org.apache.juneau.terminal.bus

Class TerminalNudges

java.lang.Object
org.apache.juneau.terminal.bus.TerminalNudges
All Implemented Interfaces:
AutoCloseable, TerminalNudgePublisher
public final class TerminalNudges extends Object implements TerminalNudgePublisher, AutoCloseable
Tells browser terminal cards that a terminal has new bytes, so they fetch immediately instead of waiting for the next poll.

This is a TerminalNudgePublisher: hand it to MemoryTerminalSource.nudges(String, TerminalNudgePublisher) or TerminalProcess.nudges(String, TerminalNudgePublisher), or call nudge(String, long, boolean) after a write of your own. Each call is coalesced to at most one frame per terminal per 250 ms, carrying the latest offset, and is published on term.nudge:<id> as {"end": <offset>}, plus "done": true once no more bytes will arrive. A nudge is only a hint: the card still reads the bytes through the terminal's bytes endpoint, and keeps polling as a fallback.

Wiring. The bus is built from the policy, so it is bound afterwards, once:

TerminalNudges nudges = TerminalNudges.create(access); ServerBus bus = ServerBus.create(BusPolicy.create() .downstream("term.nudge:*", false) .build()); nudges.bind(bus);

Access. TerminalAccess.canWatch(TerminalCaller, String) is called for every delivery, which is up to four times per second per terminal, for each connected session that holds the grant (up to 256 by default). It must be cheap. Only sessions holding the exact term.nudge:<id> grant receive a nudge; a session granted only term.nudge:* receives none. A revocation that races a delivery can let that one frame through; the next is denied.

Delivery runs on one daemon thread named juneau-terminal-nudges. nudge(String, long, boolean) only records state and schedules, so it never blocks the writer.

  • Field Details

  • Method Details

    • create

      public static TerminalNudges create(TerminalAccess access)
      Creates a publisher.
      Parameters:
      access - Who may watch. Must not be null.
      Returns:
      A new, unbound publisher.
      Throws:
      IllegalArgumentException - If access is null.

    • topic

      public static String topic(String terminalId)
      The nudge topic of a terminal.
      Parameters:
      terminalId - The terminal id.
      Returns:
      term.nudge:<id>.
      Throws:
      IllegalArgumentException - If the id is not a valid run id.

    • bind

      public TerminalNudges bind(ServerBus bus)
      Binds the bus the nudges are published on, and starts the scheduler. May be called once.
      Parameters:
      bus - The bus. Its policy must allow term.nudge:* downstream without retention.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If bus is null.
      IllegalStateException - If a bus is already bound, or the policy does not allow term.nudge:* downstream unretained.

    • nudge

      public void nudge(String terminalId, long end, boolean done)
      Records that a terminal's bytes now end at an offset; delivery is coalesced and happens on the scheduler thread.

      Dropped silently before bind(ServerBus) and after close().

      Specified by:
      nudge in interface TerminalNudgePublisher
      Parameters:
      terminalId - The terminal id.
      end - The offset one past the last byte.
      done - true if no more bytes will be appended.
      Throws:
      IllegalArgumentException - If the id is not a valid run id.

    • close

      public void close()
      Stops the scheduler. Flushes already queued, and later nudges, deliver nothing. Idempotent.
      Specified by:
      close in interface AutoCloseable