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. Used ubiquituously in metatools.

Very small, but 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 "sprintf"-ed into the message.

Additionally this class provides a zoo of static factory methods. But the "create and send" methods of SimpleMessage.Sender should be preferred when possible.

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.

    • emptyArgs

      public static final Object[] emptyArgs

  • 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.
      ATTENTION: 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) 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 printf-ed into the message.
      ATTENTION: The value "null" is explicitly replaced by an empty array. For an arg-list with one single entry of value "null" use "(Object)null".

    • SimpleMessage

      public SimpleMessage(SimpleMessage<D> msg)
      Return a clone.

  • Method Details

    • getLocation

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

    • getText

      @Opt public final @Opt String getText()
      Description copied from interface: PreMessage
      Evident
      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 an access to the arguments. Possibly this is not an access which allows to modify 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).

    • 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).

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

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

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

    • 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

    • cast

      public static <E> SimpleMessage<E> cast(SimpleMessage<? extends E> message)
      Convenience method for upcasting any instance with a more specialized (=sub-class) 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:
      SimpleMessage.<Object>cast(new SimpleMessage<String>())
      Returns:
      loc

    • 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 (=sub-class) 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:
      SimpleMessage.<SimpleMessage<String>>narrow(new MessageReceiver<Message>())
      Returns:
      loc

    • narrowToBottom

      public static <D> MessageReceiver<SimpleMessage<?>> narrowToBottom(MessageReceiver<? super SimpleMessage<D>> receiver)
      Convenience method for casting a message receiver which accepts SimpleMessages with a particular document identifiers to one with an unspecified document identifier.

    • mapKind

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

    • mapLevel

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

    • liftMapKind

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

    • 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. Consider when defining the function, that location maybe null.

    • liftMapLocation

      public static <D, E> Function<SimpleMessage<D>,SimpleMessage<E>> liftMapLocation(Function<Location<D>,Location<E>> f)
      Constructs a function which maps SimpleMessages (never null to never null), when a function which maps their Location (maybe null to maybe null) is given. Partiality/totality is also lifted, unaltered.

    • mapLocation

      public static <E, F> BiFunction<Function<Location<E>,Location<F>>,SimpleMessage<E>,SimpleMessage<F>> mapLocation()
      A BiFunction which delivers a clone of a SimpleMessage and applies a mapping function to the Location part. Is used by LocationMap.

    • mapText

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

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

    • error

      public static <D> SimpleMessage<D> error(PreMessage pm)
      Convenience factory Method: Construct a message with the given kind from a PreMessage.

    • error

      public static <D> SimpleMessage<D> error(PreMessage pm, @Opt @Opt Location<D> loc)

    • warning

      public static <D> SimpleMessage<D> warning(PreMessage pm, @Opt @Opt Location<D> loc)

    • warning

      public static <D> SimpleMessage<D> warning(PreMessage pm, @Opt @Opt Location<D> loc, int level)

    • explode

      public static void explode(PreMessage pm)

    • explode

      public static <D> void explode(PreMessage pm, @Opt @Opt Location<D> loc)

    • from

      public static <D> SimpleMessage<D> from(PreMessage pm, Message.Kind kind, @Opt @Opt Location<D> loc, int level)

    • log

      public static <D> SimpleMessage<D> log(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • log

      public static <D> SimpleMessage<D> log(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • log

      public static <D> SimpleMessage<D> log(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • log

      public static <D> SimpleMessage<D> log(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes.

    • logStart

      public static <D> SimpleMessage<D> logStart(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logStart

      public static <D> SimpleMessage<D> logStart(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logStart

      public static <D> SimpleMessage<D> logStart(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logStart

      public static <D> SimpleMessage<D> logStart(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes

    • logEnd

      public static <D> SimpleMessage<D> logEnd(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • logEnd

      public static <D> SimpleMessage<D> logEnd(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes

    • error

      public static <D> SimpleMessage<D> error(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • error

      public static <D> SimpleMessage<D> error(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • error

      public static <D> SimpleMessage<D> error(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • error

      public static <D> SimpleMessage<D> error(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • warning

      public static <D> SimpleMessage<D> warning(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • warning

      public static <D> SimpleMessage<D> warning(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • warning

      public static <D> SimpleMessage<D> warning(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • warning

      public static <D> SimpleMessage<D> warning(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • failure

      public static <D> SimpleMessage<D> failure(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • failure

      public static <D> SimpleMessage<D> failure(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • failure

      public static <D> SimpleMessage<D> failure(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • failure

      public static <D> SimpleMessage<D> failure(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • hint

      public static <D> SimpleMessage<D> hint(String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • hint

      public static <D> SimpleMessage<D> hint(Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • hint

      public static <D> SimpleMessage<D> hint(Throwable ex, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • hint

      public static <D> SimpleMessage<D> hint(Throwable ex, Locatable<D> loc, String message, Object... args)
      Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

    • ping

      public static <X> SimpleMessage.Ping<X> ping()
      Convenience factory Method: Create an instance of SimpleMessage.Ping, which is of kind Message.Kind.log.

    • 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).

    • 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.
      Type Parameters:
      D - the document identifier type
      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:
      thread
      See Also:

    • wrapText

      public SimpleMessage<D> wrapText(PreMessage outer)
      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 its text and all its arguments are included in the given text PreMessage as the very first argument. All outer argument of the outer PreMessage are shifted by one position.

    • 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 »¹code %s}« formatting code, where this message will be inserted.
      See Also: