SimpleMessage (BandM metatools API doc)

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
```
Used ubiquituously in ^meta_tools to model messages.
Very small, but in most cases sufficient information content: The abstract Message class is only enhanced by a Location, which points to a document(/some documents), and 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.Generator should be preferred when possible.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SimpleMessage.Generator<D>` Convenience factory class for creating `SimpleMessage`s and sending them immediately, --- all in one call.
`static class`	`SimpleMessage.Ping<D>` Log message with not more informative content than "I am still alive".

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

Field Summary

Fields
Modifier and Type	Field and Description
`protected @Opt Location<D>`	`location` Optional document position the message is related to.
`protected @Opt 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 and Description
`SimpleMessage(Message.Kind k, @Opt Exception e, @Opt String t)`
`SimpleMessage(Message.Kind k, @Opt Exception e, @Opt String t, @Opt Locatable<D> l)`
`SimpleMessage(SimpleMessage<D> msg)` return a clone.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static <D> SimpleMessage<D>`	`error(Exception ex, Locatable<D> loc, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`error(Exception ex, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`error(Locatable<D> loc, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`error(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`failure(Exception th)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`failure(Exception exception, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`failure(Locatable<D> loc, Exception exception)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`failure(Locatable<D> loc, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`failure(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`@Opt Location<D>`	`getLocation()`
`@Opt String`	`getText()`
`static <D> SimpleMessage<D>`	`hint(Locatable<D> loc, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`hint(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <X> Function<SimpleMessage<X>,SimpleMessage<X>>`	`liftMapKind(Function<Message.Kind,Message.Kind> f)` Lift a function which operates on the `Kind` part to one which operates on the whole Message.
`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.
`static <X> Function<SimpleMessage<X>,SimpleMessage<X>>`	`liftMapText(Function<String,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, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`log(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`logEnd(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`logStart(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`makeMessage(Message.Kind k, Exception e, String t, Locatable<D> l)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`SimpleMessage<D>`	`mapKind(Function<Message.Kind,Message.Kind> f)` Apply a function which operates on the `Kind` part to construct a new message.
`static <D,E> BiFunction<Function<Location<D>,Location<E>>,SimpleMessage<D>,SimpleMessage<E>>`	`mapLocation()` A `BiFunction` which delivers a clone of a SimpleMessage and applies a mapping function on the `Location` part.
`<E> SimpleMessage<E>`	`mapLocation(Function<Location<D>,Location<E>> f)` Apply a function which operates on the `Location` part to construct a new message.
`SimpleMessage<D>`	`mapText(Function<String,String> f)` Apply a function which operates on the `text` part to construct a new message.
`static <D> Function<SimpleMessage<D>,String>`	`messageToString(Function<? super Location<D>,? extends String> formatLoc)` Reified function for converting a message to a string, using a given transformation function for the `Location` part.
`static <D> Function<SimpleMessage<D>,String>`	`messageToString(Function<? super Location<D>,? extends String> formatLoc, Function<? super Message.Kind,String> formatKind)`
`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.
`static <D> Thread`	`monitor(Thread thread, MessageReceiver<? super SimpleMessage<D>> receiver, PrintStream ps)` Installs a handler on the given thread that reports uncaught exceptions as failure messages.
`static <X> SimpleMessage.Ping<X>`	`ping()` Convenience factory Method: Create an instance of `SimpleMessage.Ping`, which is of kind `Message.Kind.log`.
`String`	`render(Object... formatHints)` NOT YET OPERATIVE; simply calls `Message.toString()`
`String`	`toString()` Convert a message to a string, using the java default "toString(Object)" for the `Location` part.
`String`	`toString(Function<? super Location<D>,? extends String> formatLoc)` Convert a message to a string, using a given transformation function for the `Location` part.
`String`	`toString(Function<? super Location<D>,? extends String> formatLoc, Function<? super Message.Kind,String> formatKind)`
`static <D> SimpleMessage<D>`	`warning(Locatable<D> loc, String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.
`static <D> SimpleMessage<D>`	`warning(String message)` Convenience factory Method: Create a message of the indicated kind and with the given attributes.

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

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

Field Detail
- 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.)
- location
```
@Opt
protected final @Opt Location<D> location
```
  Optional document position the message is related to.

Constructor Detail

SimpleMessage

public SimpleMessage(Message.Kind k,
                     @Opt
                     @Opt Exception e,
                     @Opt
                     @Opt String t)

Parameters:: k - (never null); e - (maybe null); t - (maybe null)

SimpleMessage

public SimpleMessage(Message.Kind k,
                     @Opt
                     @Opt Exception e,
                     @Opt
                     @Opt String t,
                     @Opt
                     @Opt Locatable<D> l)

Parameters:: k - (never null); e - (maybe null); t - (maybe null); l - (maybe 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 String getText()
```
Returns:

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

messageToString

public static <D> Function<SimpleMessage<D>,String> messageToString(Function<? super Location<D>,? extends String> formatLoc)

Reified function for converting a message to a string, using a given transformation function for the Location part.

messageToString

public static <D> Function<SimpleMessage<D>,String> messageToString(Function<? super Location<D>,? extends String> formatLoc,
                                                                    Function<? super Message.Kind,String> formatKind)

toString
```
public String toString(Function<? super Location<D>,? extends String> formatLoc)
```
Convert a message to a string, using a given transformation function for the Location part.

toString

public String toString(Function<? super Location<D>,? extends String> formatLoc,
                       Function<? super Message.Kind,String> formatKind)

toString
```
public String toString()
```
Convert a message to a string, using the java default "toString(Object)" for the Location part.

Overrides:

toString in class Message

render
```
public String render(Object... formatHints)
```
Description copied from class: Message

NOT YET OPERATIVE; simply calls Message.toString()

Overrides:

render in class Message

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

liftMapKind

public static <X> Function<SimpleMessage<X>,SimpleMessage<X>> liftMapKind(Function<Message.Kind,Message.Kind> f)

Lift a function which operates on the 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. (This function is used by e.g. xslt/base/TPathCache, d2d2/base/Main+others.)

mapLocation
```
public static <D,E> BiFunction<Function<Location<D>,Location<E>>,SimpleMessage<D>,SimpleMessage<E>> mapLocation()
```
A BiFunction which delivers a clone of a SimpleMessage and applies a mapping function on the Location part. Is used by FIXME ?????

mapText
```
public SimpleMessage<D> mapText(Function<String,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(Function<String,String> f)

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