Interface Message

All Superinterfaces:
AsString, Transmittable, Triaged
All Known Implementing Classes:
Activity, Alert, Announcement, CriticalAlert, EnsureFailure, FatalProblem, Glitch, Information, Narration, OperationFailed, OperationHalted, OperationLifecycleMessage, OperationMessage, OperationStarted, OperationStatusMessage, OperationSucceeded, Problem, Quibble, StepFailure, StepIncomplete, StepSuccess, Trace, Unsupported, Warning

public interface Message extends Transmittable, Triaged, AsString
An interface to retrieve the basic attributes of a message, find out what it means and format it as text. A message's text is unformatted when it is created. The message text and any arguments must be passed to MessageFormatter to produce a final formatted message, which can be retrieved with formatted(MessageFormatter.Format). This is a useful design because it is cheaper to construct messages if the formatting is delayed until the formatted string is need, for example, when a log message is added to a formatted text log.

Message Attributes

  • text() - The unformatted text of the message
  • arguments() - Arguments that can be applied to the message text when formatting it
  • cause() - Any exception associated with the message
  • created() - The time that the message was created
  • severity() - The severity of the message
  • operationStatus() - The operation that the message relates to, if any
  • status() - The status of a step in an ongoing operation that the message relates to, if any

Types of Messages

Different types of messages relate to different aspects of a running program. Messages relating to a larger goal of the program, such as converting a file or computing a route are operation lifecycle messages and extend OperationLifecycleMessage. Messages that relate to the smaller steps required to achieve an operation are status messages and extend OperationStatusMessage. If the operationStatus() method returns a non-null value, the message relates to the operation lifecycle. If the status() method returns a non-null value the message relates to the most recent step in the current operation.

Each class implementing Message will define one or the other of these two return values. For example, OperationHalted is a lifecycle message which means that the current operation has transitioned to the Message.OperationStatus.HALTED state. Warning relates to a step in an operation which Message.Status.SUCCEEDED, even if it did so imperfectly. Inspection of message classes will reveal what their meaning is with respect to operations and the steps used to complete them.

Operation Lifecycle Messages

An Message.OperationStatus lifecycle message relates to a state change in the status of an operation. Operations start, run and then complete with some kind of result:

Operation Status Messages

A Message.Status message relates to the result of executing a step in a larger operation:

Author:
jonathanl (shibo)
  • Field Details

    • FORMATTER

      static final MessageFormatter FORMATTER
      Static instance of a (stateless) message formatter
  • Method Details

    • escape

      static String escape(String text)
      Returns:
      The given string with single quotes escaped
    • format

      static String format(String message, Object... arguments)
      Returns:
      The message text formatted with the given arguments
    • println

      static void println(String message, Object... arguments)
    • arguments

      Object[] arguments()
      Returns:
      Message arguments used to produce formatted message
    • asException

      RuntimeException asException()
      Returns:
      This message as an exception
    • cause

      Throwable cause()
      Returns:
      Any cause or null if none
    • context

      CodeContext context()
      Returns:
      The context where this message was created
    • created

      Time created()
      Returns:
      The time at which this message was created
    • description

      String description()
      Returns:
      The formatted message without stack trace information
    • formatted

      String formatted(MessageFormatter.Format format)
      Returns:
      Formatted message, including any stack trace information
    • importance

      Importance importance()
      Returns:
      The importance of this message, without respect to severity
    • isMoreImportantThan

      default boolean isMoreImportantThan(Class<? extends Message> type)
    • isMoreImportantThanOrEqualTo

      default boolean isMoreImportantThanOrEqualTo(Class<? extends Message> type)
    • isWorseThan

      default boolean isWorseThan(Message.Status status)
      Returns:
      True if the status of this message is worse than the given value
    • isWorseThanOrEqualTo

      default boolean isWorseThanOrEqualTo(Message.Status status)
      Returns:
      True if the status of this message is worse than the given value
    • maximumFrequency

      Frequency maximumFrequency()
      Returns:
      The frequency with which this message should be logged or null if the message should always be logged.

      NOTE: Message identity is determined by looking at the unformatted message returned by message(). If message() does not return a constant string, a bounded map error may occur as the system attempts to track too many message frequencies.

    • operationStatus

      Message.OperationStatus operationStatus()
      Returns:
      The operational status represented by this message, if any
    • severity

      Severity severity()
      Specified by:
      severity in interface Triaged
      Returns:
      The severity of this message
    • stackTrace

      StackTrace stackTrace()
      Returns:
      Any stack trace associated with this message (or null if none applies)
    • status

      Message.Status status()
      Returns:
      The status of a step in an ongoing operation, if the message is relevant to this
    • text

      String text()
      Returns:
      The un-formatted message text. See and MessageFormatter for details on how this text is formatted using the arguments() to the message.
    • throwAsIllegalArgumentException

      default void throwAsIllegalArgumentException()
    • throwAsIllegalStateException

      default void throwAsIllegalStateException()
    • toString

      String toString()
      The formatted message, including any exception
      Overrides:
      toString in class Object