Module kivakit.core
Package com.telenav.kivakit.core.messaging

Interface Message

All Superinterfaces:
Named, Stringable, StringSource, Transmittable, Triaged
All Known Implementing Classes:
Activity, Alert, Announcement, CriticalAlert, EnsureProblem, FatalProblem, Glitch, Information, Narration, OperationFailed, OperationHalted, OperationLifecycleMessage, OperationMessage, OperationStarted, OperationStatusMessage, OperationSucceeded, Problem, Quibble, ReflectionProblem, StepFailure, StepIncomplete, StepSuccess, Trace, Unsupported, Warning
public interface Message extends Transmittable, Triaged, Stringable, Named
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 un-formatted when it is created. The message text and any arguments must be passed to Formatter to produce a final formatted message, which can be retrieved with formatted(Formatter.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 un-formatted 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)

  • Method Details

    • escape

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

    • parseMessageName

      static Message parseMessageName(Listener listener, String name)
      Returns:
      The message with the given simple name (Problem, Warning, etc.)

    • 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

    • cause

      Message cause(Throwable cause)
      Not public API

      Sets the cause for this message

    • 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(Formatter.Format format)
      Returns:
      Formatted message, including any stack trace information

    • formatted

      default String formatted()

    • importance

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

    • isFailure

      default boolean isFailure()

    • 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

    • isWorseThan

      default <T extends Message> boolean isWorseThan(Class<T> message)
      Returns:
      True if the status of this message is worse than the given message

    • isWorseThanOrEqualTo

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

    • isWorseThanOrEqualTo

      default <T extends Message> boolean isWorseThanOrEqualTo(Class<T> message)
      Returns:
      True if the status of this message is worse than the given message

    • 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 un-formatted 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.

    • name

      default String name()
      Specified by:
      name in interface Named
      Returns:
      The name of this object

    • 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 Formatter.format(String, Object...) 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