java.lang.Object
- eu.bandm.tools.message.Message
- - eu.bandm.tools.message.SimpleMessage<D>

Direct Known Subclasses:

SimpleMessage.Ping
```
public class SimpleMessage<D>
extends Message
```
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 Generator should be preferred when possible.

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`SimpleMessage.Ping<D>`	Log message with not more informative content than "I am still alive".
`static class`	`SimpleMessage.Sender<E>`

Nested classes/interfaces inherited from class eu.bandm.tools.message.Message
Message.Kind

Field Summary

Fields
Modifier and Type	Field	Description
`protected @Opt java.lang.Object[]`	`args`	Optional pieces of information.
`static java.lang.Object[]`	`emptyArgs`
`protected @Opt Location<D>`	`location`	Optional document position the message is related to.
`protected @Opt java.lang.String`	`text`	Contains the textual information of the message (maybe null).

Fields inherited from class eu.bandm.tools.message.Message
cause, kind, timestamp

Constructor Summary

Constructors
Constructor	Description
`SimpleMessage(Message.Kind k, @Opt java.lang.Throwable e, @Opt Locatable<D> l, @Opt java.lang.String t, java.lang.Object... a)`	Main constructor which sets all field values.
`SimpleMessage(SimpleMessage<D> msg)`	return a clone.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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.
`static <D> SimpleMessage<D>`	`error(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`error(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`error(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`error(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`failure(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`failure(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`failure(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`failure(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`java.lang.Object[]`	`getArgs()`
`@Opt Location<D>`	`getLocation()`
`@Opt java.lang.String`	`getText()`
`static <D> SimpleMessage<D>`	`hint(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`hint(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`hint(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`hint(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <X> java.util.function.Function<SimpleMessage<X>,SimpleMessage<X>>`	`liftMapKind(java.util.function.Function<Message.Kind,Message.Kind> f)`	Lift a function which operates on the `Message.Kind` part to one which operates on the whole Message.
`static <D,E> java.util.function.Function<SimpleMessage<D>,SimpleMessage<E>>`	`liftMapLocation(java.util.function.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.
`static <X> java.util.function.Function<SimpleMessage<X>,SimpleMessage<X>>`	`liftMapText(java.util.function.Function<java.lang.String,java.lang.String> f)`	Lift a function which operates on the `text` part to one which operates on the whole Message.
`static <D> SimpleMessage<D>`	`log(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`log(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`log(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`log(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logEnd(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logEnd(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logEnd(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`logEnd(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logStart(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logStart(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`logStart(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`logStart(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`SimpleMessage<D>`	`mapKind(java.util.function.Function<Message.Kind,Message.Kind> f)`	Apply a function which operates on the `Message.Kind` part to construct a new message.
`static <E,F> java.util.function.BiFunction<java.util.function.Function<Location<E>,Location<F>>,SimpleMessage<E>,SimpleMessage<F>>`	`mapLocation()`	A `BiFunction` which delivers a clone of a SimpleMessage and applies a mapping function on the `Location` part.
`<E> SimpleMessage<E>`	`mapLocation(java.util.function.Function<Location<D>,Location<E>> f)`	Apply a function which operates on the `Location` part to construct a new message.
`SimpleMessage<D>`	`mapText(java.util.function.Function<java.lang.String,java.lang.String> f)`	Apply a function which operates on the `text` part to construct a new message.
`static <D> java.util.function.Function<SimpleMessage<D>,java.lang.String>`	`messageToString(java.util.function.Function<? super Location<D>,? extends java.lang.String> formatLoc)`	Create a reified function for converting a message to a string, using a given transformation function for the `Location` part.
`static <D> java.util.function.Function<SimpleMessage<D>,java.lang.String>`	`messageToString(java.util.function.Function<? super Location<D>,? extends java.lang.String> formatLoc, java.util.function.Function<? super Message.Kind,java.lang.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`.
`static <D> java.lang.Thread`	`monitor(java.lang.Thread thread, MessageReceiver<? super SimpleMessage<D>> receiver)`	Installs a handler on the given thread that reports uncaught exceptions as failure messages.
`static <D> java.lang.Thread`	`monitor(java.lang.Thread thread, MessageReceiver<? super SimpleMessage<D>> receiver, java.io.PrintStream ps)`	Installs a handler on the given thread that reports uncaught exceptions as failure messages.
`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.
`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.
`static <X> SimpleMessage.Ping<X>`	`ping()`	Convenience factory Method: Create an instance of `SimpleMessage.Ping`, which is of kind `Message.Kind.log`.
`java.lang.String`	`toString()`	Convert a message to a string, using the java default "toString(Object)" for the `Location` part.
`java.lang.String`	`toString(java.util.function.Function<? super Location<D>,? extends java.lang.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`.
`java.lang.String`	`toString(java.util.function.Function<? super Location<D>,? extends java.lang.String> formatLoc, java.util.function.Function<? super Message.Kind,java.lang.String> formatKind)`	Convert a message to a string, using the function arguments to print the `Location` and the `Message.Kind` parts.
`static <D> SimpleMessage<D>`	`warning(Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`warning(java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.
`static <D> SimpleMessage<D>`	`warning(java.lang.Throwable ex, Locatable<D> loc, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes
`static <D> SimpleMessage<D>`	`warning(java.lang.Throwable ex, java.lang.String message, java.lang.Object... args)`	Convenience factory Method: Construct a message with the given kind and attributes, and set all others to default.

Methods inherited from class eu.bandm.tools.message.Message
explode, getCause, getKind, getStackTrace, getThrowable, getTimeStamp, isCritical

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail
- location
```
@Opt
protected final @Opt Location<D> location
```
  Optional document position the message is related to.
- text
```
@Opt
protected final @Opt java.lang.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 java.lang.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 java.lang.Object[] emptyArgs
```

Constructor Detail
- SimpleMessage
```
public SimpleMessage(Message.Kind k,
                     @Opt
                     @Opt java.lang.Throwable e,
                     @Opt
                     @Opt Locatable<D> l,
                     @Opt
                     @Opt java.lang.String t,
                     java.lang.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
  
  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 Detail

getLocation
```
@Opt
public final @Opt Location<D> getLocation()
```
Returns:

(maybe null) the text location related to the message.

getText
```
@Opt
public final @Opt java.lang.String getText()
```
Returns:

(maybe null) the text contents related to the message.

getArgs
```
public final java.lang.Object[] getArgs()
```
Returns:

the argument array contained in this message. Is never null, but possibly empty.

messageToString
```
public static <D> java.util.function.Function<SimpleMessage<D>,java.lang.String> messageToString(java.util.function.Function<? super Location<D>,? extends java.lang.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 in MessagePrinter.setMessageToString(Function).

messageToString

public static <D> java.util.function.Function<SimpleMessage<D>,java.lang.String> messageToString(java.util.function.Function<? super Location<D>,? extends java.lang.String> formatLoc,
                                                                                                       java.util.function.Function<? super Message.Kind,java.lang.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 in MessagePrinter.setMessageToString(Function).

toString
```
public java.lang.String toString(java.util.function.Function<? super Location<D>,? extends java.lang.String> formatLoc,
                                 java.util.function.Function<? super Message.Kind,java.lang.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 of the argument list is executed.

toString
```
public java.lang.String toString(java.util.function.Function<? super Location<D>,? extends java.lang.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 java.lang.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 much 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(java.util.function.Function<Message.Kind,Message.Kind> f)

Apply a function which operates on the Message.Kind part to construct a new message.

liftMapKind

public static <X> java.util.function.Function<SimpleMessage<X>,SimpleMessage<X>> liftMapKind(java.util.function.Function<Message.Kind,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(java.util.function.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> java.util.function.Function<SimpleMessage<D>,SimpleMessage<E>> liftMapLocation(java.util.function.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.
(This function is used by e.g. xslt/base/TPathCache, d2d2/base/Main+others.)

mapLocation

public static <E,F> java.util.function.BiFunction<java.util.function.Function<Location<E>,Location<F>>,SimpleMessage<E>,SimpleMessage<F>> mapLocation()

A BiFunction which delivers a clone of a SimpleMessage and applies a mapping function on the Location part. Is used by LocationMap.

mapText

public SimpleMessage<D> mapText(java.util.function.Function<java.lang.String,java.lang.String> f)

Apply a function which operates on the text part to construct a new message.

liftMapText

public static <X> java.util.function.Function<SimpleMessage<X>,SimpleMessage<X>> liftMapText(java.util.function.Function<java.lang.String,java.lang.String> f)

Lift a function which operates on the text part to one which operates on the whole Message.