Package eu.bandm.tools.message

Class SimpleMessage<D>

java.lang.Object
eu.bandm.tools.message.Message
eu.bandm.tools.message.SimpleMessage<D>
Type Parameters:
D - the document identifier used by the locations
All Implemented Interfaces:
PreMessage, Serializable
Direct Known Subclasses:
SimpleMessage.Ping
public class SimpleMessage<D> extends Message implements PreMessage
A minimal selection of message data which is useful in practice.

In most cases sufficient information content: The abstract Message class is enhanced by a Location, which points to a document(/some documents), a textual information text, and a list of arguments (=array of objects) which probably will be inserted into the message text by some formatting technique. (In this context, the text can be called template text.)

Additionally this class provides a collection of static factory methods for frequent combinations of explicit vs. default parameters. But in many production cases, the create-and-send"methods of SimpleMessage.Sender are preferrable.

See Also:

  • Field Details

    • location

      @Opt protected final @Opt Location<D> location
      Optional document position the message is related to.

    • text

      @Opt protected final @Opt String text
      Contains the textual information of the message (maybe null). ("text" and "cause" can both be ==null in case of a simple "Ping"-style message.)

    • args

      @Opt protected final @Opt Object[] args
      Optional pieces of information. In most cases, these are intended to be inserted into the text, before this is presented to the user, and possibly after translation. In this case, text and arguments should follow the formatting rules as defined by Formatter.

    • emptyArgs

      public static final Object[] emptyArgs
      Constant used as default value when constructing messages.

  • Constructor Details

    • SimpleMessage

      public SimpleMessage(Message.Kind k, int v, @Opt @Opt Throwable e, @Opt @Opt Locatable<D> l, @Opt @Opt String t, Object... a)
      Main constructor which sets all field values.

      (Even both e and t maybe =null for a "Ping"-style message.)

      Parameters:
      k - (never null) message Kind
      v - the level (0 = always shown, increasing verbosity levels)
      e - (maybe null) the causing Throwable
      l - (maybe null) text location to which the message is related
      t - (maybe null) message text
      a - (maybe null) list of additional pieces of information, meant to be formatted into the message. (The argument value null is replaced by an empty array. For an argument list with one single entry of value null use "(Object)null".)

    • SimpleMessage

      public SimpleMessage(SimpleMessage<D> msg)
      Return a clone.
      Parameters:
      msg - the message to copy

  • Method Details

    • getLocation

      @Opt public final @Opt Location<D> getLocation()
      Delivers the text location related to the message.
      Returns:
      (maybe null) the text location related to the message.

    • getText

      @Opt public final @Opt String getText()
      Description copied from interface: PreMessage
      Returns the template text.
      Specified by:
      getText in interface PreMessage
      Returns:
      (maybe null) the text contents related to the message.

    • getArgs

      public final Object[] getArgs()
      Description copied from interface: PreMessage
      Returns the arguments. Changing the array may or may not change this instance.
      Specified by:
      getArgs in interface PreMessage
      Returns:
      the argument array contained in this message. Is never null, but possibly empty.

    • messageToString

      public static <D> Function<SimpleMessage<D>,String> messageToString(Function<? super Location<D>,? extends String> formatLoc)
      Create a reified function for converting a message to a string, using a given transformation function for the Location part. Result is meant to be plugged into MessagePrinter.setMessageToString(Function).
      Type Parameters:
      D - the type of the document id
      Parameters:
      formatLoc - the function to format the location information
      Returns:
      the formatted message

    • messageToString

      public static <D> Function<SimpleMessage<D>,String> messageToString(Function<? super Location<D>,? extends String> formatLoc, Function<? super Message.Kind,String> formatKind)
      Construct a reified function for converting a message to a string, using the given transformation functions for the Location part and for the Message.Kind. Result is meant to be plugged into MessagePrinter.setMessageToString(Function).
      Type Parameters:
      D - the type of the document id
      Parameters:
      formatLoc - the function to format the location information
      formatKind - the function to format the message kind
      Returns:
      the formatted message

    • toString

      public String toString(Function<? super Location<D>,? extends String> formatLoc, Function<? super Message.Kind,String> formatKind)
      Convert a message to a string, using the function arguments to print the Location and the Message.Kind parts. This is only a rough interpretation for debugging and tracing; an actual user-level MessagePrinter provides more elaborate methods. Esp. no "printf"-style formatting of the argument list is executed.
      Parameters:
      formatLoc - the function to format the location information
      formatKind - the function to format the message kind
      Returns:
      the formatted message

    • toString

      public String toString(Function<? super Location<D>,? extends String> formatLoc, Function<? super Message.Kind,String> formatKind, IntFunction<String> formatLevel)
      Convert a message to a string, using the function arguments to print the Location and the Message.Kind parts. This is only a rough interpretation for debugging and tracing; an actual user-level MessagePrinter provides more elaborate methods. Esp. no "printf"-style formatting of the argument list is executed.
      Parameters:
      formatLoc - the function to format the location information
      formatKind - the function to format the message kind
      formatLevel - the function to format the level
      Returns:
      the formatted message

    • toString

      public String toString(Function<? super Location<D>,? extends String> formatLoc)
      Convert a message to a string, using the function argument to print the Location part and the enumeration names for the Message.Kind.
      Parameters:
      formatLoc - the function to format the location information
      Returns:
      the formatted message

    • toString

      public String toString()
      Convert a message to a string, using the java default "toString(Object)" for the Location part. This is a primitive visualisation, required for tracing and debugging. An actual user-level MessagePrinter or sim., will provide more elaborate rendering.
      Overrides:
      toString in class Message
      Returns:
      the formatted message

    • cast

      public static <E> SimpleMessage<E> cast(SimpleMessage<? extends E> message)
      Convenience method for upcasting any instance with a more specialized (=subclass) document identifier to an instance with the more general document identifier. When used as method argument, return value or in assignments, the target class needs not be given explicitly, as in
      SimpleMessage<Object> var = cast(new SimpleMessage<String>())

      Otherwise it can be called explicitly by SimpleMessage.<Object>cast(new SimpleMessage<String>())

      Type Parameters:
      E - the document type of the message
      Parameters:
      message - to convert
      Returns:
      the converted message

    • narrow

      public static <E> MessageReceiver<SimpleMessage<E>> narrow(MessageReceiver<? super SimpleMessage<? super E>> receiver)
      Convenience method for downcasting a message receiver accepting more general messages or document identifiers to one which accepts more specialized (=subclass) messages. When used as method argument, return value or in assignments, the target class needs not be given explicitly, as in MessageReceiver<SimpleMessage<String>> rec = narrow(new MessageReceiver<Message>())

      Otherwise it can be called explicitly by SimpleMessage.<SimpleMessage<String>>narrow (new MessageReceiver<Message>())

      Type Parameters:
      E - the document type of the message
      Parameters:
      receiver - to convert
      Returns:
      the converted receiver

    • narrowToBottom

      public static <E> MessageReceiver<SimpleMessage<?>> narrowToBottom(MessageReceiver<? super SimpleMessage<E>> receiver)
      Convenience method for casting a message receiver which accepts SimpleMessages with a particular document identifiers to one with an unspecified document identifier.
      Type Parameters:
      E - the document type of the message
      Parameters:
      receiver - to convert
      Returns:
      the converted receiver

    • mapKind

      public SimpleMessage<D> mapKind(UnaryOperator<Message.Kind> f)
      Apply a function which operates on the kind of a message to construct a new message.

      Partiality of the given function means partiality of this method.

      Parameters:
      f - the function operating on message kinds
      Returns:
      the message with the calculated kind

    • mapLevel

      public SimpleMessage<D> mapLevel(IntUnaryOperator f)
      Apply a function which operates on the "level" part to construct a new message.

      Partiality of the given function means partiality of this method.

      Parameters:
      f - the function operating on message level
      Returns:
      the message with the calculated level

    • liftMapKind

      public static <X> Function<SimpleMessage<X>,SimpleMessage<X>> liftMapKind(UnaryOperator<Message.Kind> f)
      Lift a function which operates on the kind part to one which operates on the whole message.

      Partiality of the given function means partiality of the resulting function.

      Type Parameters:
      X - the document id type of the message
      Parameters:
      f - the function operating on message kinds
      Returns:
      the function on simple messages

    • mapLocation

      public <E> SimpleMessage<E> mapLocation(Function<Location<D>,Location<E>> f)
      Apply a function which operates on the location part to construct a new message.

      Partiality of the given function means partiality of this method.

      Type Parameters:
      E - the document id type of the message
      Parameters:
      f - the function operating on locations
      Returns:
      the function on simple messages

    • liftMapLocation

      public static <D, E> Function<@Opt SimpleMessage<D>,@Opt SimpleMessage<E>> liftMapLocation(Function<Location<D>,Location<E>> f)
      Constructs a function which operates on SimpleMessages (never null to never null), from a function which operates on locations (maybe null to maybe null).

      Partiality of the location function means partiality of the resulting function.

      Type Parameters:
      D - the document type of the original location
      E - the document type of the calculated location
      Parameters:
      f - the function on locations (may be partial, may accept and deliver null)
      Returns:
      the function on messages (may be partial. May not accept nor deliver null)

    • mapLocation

      public static <E, F> BiFunction<Function<Location<E>,Location<F>>,SimpleMessage<E>,SimpleMessage<F>> mapLocation()
      Delivers a two-arguments function which delivers a clone of a SimpleMessage and applies a mapping function to its Location part.

      Partiality of a given function means partiality of the resulting function.

      Type Parameters:
      E - the document id type of the ingoing message
      F - the document id type of the resulting message
      Returns:
      a two-arguments function

    • mapText

      public SimpleMessage<D> mapText(UnaryOperator<String> f)
      Apply a function which operates on the text part to construct a new message.

      Partiality of the given function means partiality of this method.

      Parameters:
      f - the function on text
      Returns:
      a message clone with the calculated text

    • liftMapText

      public static <X> Function<SimpleMessage<X>,SimpleMessage<X>> liftMapText(UnaryOperator<String> f)
      Lift a function which operates on the text part to one which operates on the whole Message.

      Partiality of the given function means partiality of the resulting function.

      Type Parameters:
      X - the document identifier type of the messages
      Parameters:
      f - the function on text
      Returns:
      a function operating on messages

    • error

      public static <D> SimpleMessage<D> error(PreMessage pm)
      Convenience factory Method: Construct a message of error kind from a PreMessage.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      Returns:
      a simple message of error type, no location, default level and the given text and argument content

    • error

      public static <D> SimpleMessage<D> error(PreMessage pm, @Opt @Opt Location<D> loc)
      Convenience factory Method: Construct a message of error kind from a PreMessage.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      loc - the message location
      Returns:
      a simple message of error type, default level and the given location, text and argument content

    • warning

      public static <D> SimpleMessage<D> warning(PreMessage pm, @Opt @Opt Location<D> loc)
      Convenience factory Method: Construct a message of warning kind from a PreMessage.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      loc - the message location
      Returns:
      a simple message of warning type, default level and the given location, text and argument content

    • warning

      public static <D> SimpleMessage<D> warning(PreMessage pm, @Opt @Opt Location<D> loc, int level)
      Convenience factory Method: Construct a message of warning kind from a PreMessage.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      loc - the message location
      level - the message level
      Returns:
      a simple message of warning type, default level and the given location, text and argument content

    • explode

      public static void explode(@Opt @Opt PreMessage pm)
      Convert a premessage into a simple message and throw it as an exception.
      Parameters:
      pm - the message text and arguments
      See Also:

    • explode

      public static <D> void explode(@Opt @Opt PreMessage pm, @Opt @Opt Location<D> loc)
      Convert a premessage into a simple message and throw it as an exception.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      loc - the message location
      See Also:

    • from

      public static <D> SimpleMessage<D> from(PreMessage pm, Message.Kind kind, @Opt @Opt Location<D> loc, int level)
      Create a message from a pre-message, a kind, a location, and a level.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      pm - the message text and arguments
      kind - the message kind
      loc - the message location
      level - the message level
      Returns:
      the simple message with the given properties

    • log

      public static <D> SimpleMessage<D> log(String message, Object... args)
      Convenience factory method: Construct a message of log kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • log

      public static <D> SimpleMessage<D> log(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • log

      public static <D> SimpleMessage<D> log(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of log kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • log

      public static <D> SimpleMessage<D> log(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logStart

      public static <D> SimpleMessage<D> logStart(String message, Object... args)
      Convenience factory method: Construct a message of log start kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logStart

      public static <D> SimpleMessage<D> logStart(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log start kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logStart

      public static <D> SimpleMessage<D> logStart(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of log start kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logStart

      public static <D> SimpleMessage<D> logStart(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log start kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logEnd

      public static <D> SimpleMessage<D> logEnd(String message, Object... args)
      Convenience factory method: Construct a message of log end kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log end kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of log end kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of log end kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • error

      public static <D> SimpleMessage<D> error(String message, Object... args)
      Convenience factory method: Construct a message of error kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • error

      public static <D> SimpleMessage<D> error(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of error kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • error

      public static <D> SimpleMessage<D> error(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of error kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • error

      public static <D> SimpleMessage<D> error(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of error kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • warning

      public static <D> SimpleMessage<D> warning(String message, Object... args)
      Convenience factory method: Construct a message of warning kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • warning

      public static <D> SimpleMessage<D> warning(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of warning kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • warning

      public static <D> SimpleMessage<D> warning(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of warning kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • warning

      public static <D> SimpleMessage<D> warning(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of warning kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • failure

      public static <D> SimpleMessage<D> failure(String message, Object... args)
      Convenience factory method: Construct a message of failure kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • failure

      public static <D> SimpleMessage<D> failure(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of failure kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • failure

      public static <D> SimpleMessage<D> failure(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of failure kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • failure

      public static <D> SimpleMessage<D> failure(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of failure kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • hint

      public static <D> SimpleMessage<D> hint(String message, Object... args)
      Convenience factory method: Construct a message of hint kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • hint

      public static <D> SimpleMessage<D> hint(Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of hint kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • hint

      public static <D> SimpleMessage<D> hint(Throwable ex, String message, Object... args)
      Convenience factory method: Construct a message of hint kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • hint

      public static <D> SimpleMessage<D> hint(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory method: Construct a message of hint kind with the given attributes, and set all others to default.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      ex - the cause of the message
      loc - the message location
      message - the text of the message
      args - the list of arguments
      Returns:
      the simple message with the given properties

    • ping

      public static <X> SimpleMessage.Ping<X> ping()
      Convenience factory Method: Create an instance of SimpleMessage.Ping, which is of kind Message.Kind.log.
      Type Parameters:
      X - the type of the document identifier
      Returns:
      the simple message without any further properties

    • monitor

      public static <D> Thread monitor(Thread thread, MessageReceiver<? super SimpleMessage<D>> receiver)
      Installs a handler on the given thread that reports uncaught exceptions as failure messages. Is equal to monitor(thread, receiver, false).
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      thread - the thread to monitor
      receiver - the receiver for the failure message
      Returns:
      the thread argument (for method chaining)

    • monitor

      public static <D> Thread monitor(Thread thread, MessageReceiver<? super SimpleMessage<D>> receiver, @Opt PrintStream ps)
      Installs a handler on the given thread that reports uncaught exceptions as failure messages. The handler replaces any currently installed handler.
      Type Parameters:
      D - the type of the document identifier
      Parameters:
      thread - the thread to monitor
      receiver - the receiver for the failure message
      ps - if != null, additionally the stack trace will be printed there.
      Returns:
      the thread argument (for method chaining)
      See Also:

    • wrapText

      public SimpleMessage<D> wrapText(PreMessage outer)
      Deliver a new message with the same technical data as this message, but with enhanced text. The technical data (kind, level, timestamp, and cause) are copied from this message. The text of the new message is taken from the given outer pre message. This message is reduced to a pre-message and inserted as the very first argument in the new message. The arguments in the given outer pre-message are thus shifted by one position.
      Parameters:
      outer - the message text and arguments defining the top level of text expansion
      Returns:
      a new message which represents this message inserted into the outer pre-message

    • wrapText

      public SimpleMessage<D> wrapText(String s)
      Deliver a message with the same technical data and enhanced text. The technical data kind, level, timestamp, and cause are copied from this message, but the text and all its arguments are included in the given text string. This must contain exaclty one "%s" formatting code, where this message will be inserted.
      Parameters:
      s - the text into which this message shall be wrapped
      Returns:
      a message which will appear as wrapped into the given string, whenever printed
      See Also: