Package org.apache.juneau.terminal.report

Class TerminalEvent

java.lang.Object
org.apache.juneau.terminal.report.TerminalEvent
public final class TerminalEvent extends Object
One event of a terminal-view stream.

An immutable value with static factories, one per event kind. Every factory and with* method validates its argument against the event contract and throws IllegalArgumentException naming the member, so a producer finds its bug where it is written. toContractMap() produces the wire form, and fromMap(Map) is its strict inverse.

A seq() of 0 means the event has not been numbered yet; sources assign it.

  • Field Details

  • Method Details

    • step

      public static TerminalEvent step(String id, String title)
      Creates a step event.
      Parameters:
      id - The step id. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
      title - The step title, 1-200 chars.
      Returns:
      A new event.

    • end

      public static TerminalEvent end(String id, TerminalEvent.EndStatus status)
      Creates an end event.
      Parameters:
      id - The id of a known step.
      status - The final status.
      Returns:
      A new event.

    • suite

      public static TerminalEvent suite(String step, String fw, String suite, int pass, int fail, int skip)
      Creates a suite placeholder event.
      Parameters:
      step - The id of a known step.
      fw - The test framework key.
      suite - The suite name, 1-512 chars.
      pass - The pass count, 0-1,000,000,000.
      fail - The fail count, 0-1,000,000,000.
      skip - The skip count, 0-1,000,000,000.
      Returns:
      A new event.

    • test

      public static TerminalEvent test(String step, String fw, String suite, String name, TerminalEvent.TestStatus status)
      Creates a test event.
      Parameters:
      step - The id of a known step.
      fw - The test framework key.
      suite - The suite name, 1-512 chars.
      name - The test name, 1-512 chars.
      status - The test status.
      Returns:
      A new event.

    • replace

      public static TerminalEvent replace(String step)
      Creates a replace event.
      Parameters:
      step - The id of a known step.
      Returns:
      A new event.

    • note

      public static TerminalEvent note(TerminalEvent.Level level, String text)
      Creates a note event.
      Parameters:
      level - The level.
      text - The plain text, 1-1,000 chars.
      Returns:
      A new event.

    • done

      public static TerminalEvent done(TerminalEvent.DoneStatus status)
      Creates a done event.
      Parameters:
      status - The final run status.
      Returns:
      A new event.

    • withN

      public TerminalEvent withN(int n)
      Sets the display ordinal of a step event.
      Parameters:
      n - The ordinal, 1-9999.
      Returns:
      A copy with the member set.

    • withState

      public TerminalEvent withState(TerminalEvent.StepState state)
      Sets the state of a step event.
      Parameters:
      state - The state.
      Returns:
      A copy with the member set.

    • withRawOffset

      public TerminalEvent withRawOffset(long offset)
      Sets the raw byte offset of a step, suite or test event.

      The 0-based offset into the raw output log of the start of the line that produced the event; a terminal view scrolls to it.

      Parameters:
      offset - The offset, 0 to 9007199254740991.
      Returns:
      A copy with the member set.

    • withMs

      public TerminalEvent withMs(long ms)
      Sets the duration of an end or test event.
      Parameters:
      ms - The duration in milliseconds, 0 to 9007199254740991.
      Returns:
      A copy with the member set.

    • withExit

      public TerminalEvent withExit(int exit)
      Sets the process exit code of an end event.
      Parameters:
      exit - The exit code.
      Returns:
      A copy with the member set.

    • withMsg

      public TerminalEvent withMsg(String msg)
      Sets the failure message of a test event.
      Parameters:
      msg - The message, at most 2,000 chars.
      Returns:
      A copy with the member set.

    • withTrace

      public TerminalEvent withTrace(String trace)
      Sets the stack trace of a test event.
      Parameters:
      trace - The trace, at most 8,000 chars.
      Returns:
      A copy with the member set.

    • withHref

      public TerminalEvent withHref(String href)
      Sets the link of a note event.
      Parameters:
      href - An absolute http(s) URL or a same-origin path.
      Returns:
      A copy with the member set.

    • withStep

      public TerminalEvent withStep(String step)
      Sets the step a note belongs under.
      Parameters:
      step - A step id.
      Returns:
      A copy with the member set.

    • withSeq

      public TerminalEvent withSeq(long seq)
      Returns a copy with the sequence number set.
      Parameters:
      seq - The sequence number, 1 to 9007199254740991, or 0 for unassigned.
      Returns:
      A copy.

    • kind

      public TerminalEvent.Kind kind()
      Returns the event kind.
      Returns:
      The kind.

    • seq

      public long seq()
      Returns the sequence number.
      Returns:
      The sequence number, or 0 when unassigned.

    • toContractMap

      public Map<String,Object> toContractMap()
      Returns the event in its wire form.

      The map is ordered (ev, seq when assigned, then the members in contract order) and omits unset optional members. A fresh map is returned on every call.

      Returns:
      The wire map.

    • validate

      public TerminalEvent validate()
      Checks that the serialized event fits in MAX_EVENT_CHARS.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If it does not.

    • fromMap

      public static TerminalEvent fromMap(Map<?,?> map)
      Builds an event from its wire form.

      The strict inverse of toContractMap(). Unknown members are ignored; an unknown ev or a malformed known member throws.

      Parameters:
      map - The wire map.
      Returns:
      A new event.
      Throws:
      IllegalArgumentException - If the map is not a valid event.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object