de.vandermeer.skb.base.message

Class Message5WH

java.lang.Object

de.vandermeer.skb.base.message.Message5WH

All Implemented Interfaces:

Skb_Renderable

public class Message5WH
extends Object
implements Skb_Renderable

Standard SKB message. This message class contains information following the 5WH news style (see also Wikipedia):

• Who is it about?
• What happened?
• When did it take place?
• Where did it take place?
• Why did it happen?
• How did it happen?

In addition to that, the class also provides for information on the reporter (the object reporting the message) and the message type (i.e. an error, a warning or an information).

The class comprises methods to build a message (add*, set*), methods to access a message (get*) and some additional methods to process a complete message (asST, render, toString). Additionally, it carries an enumerate EMessageType for typing messages. Message properties that have a "set" method (reporter, type, when, where, who) can only be set once and are immutable afterwards. For message properties that have an "add" method (how, what, why) information can be appended unlimited, but once added it cannot be removed.

The simplest way to create a message is to use the the builder methods. The following example creates a new message and sets all of its properties:

Message5WH msg=new Message5WH()
        .setWho("from "+this.getClass().getSimpleName())
        .addWhat("showing a test message")
        .setWhen(null)
        .setWhere("the class API documentation", 0, 0)
        .addWhy("as a demo")
        .addHow("added to the class JavaDoc")
        .setReporter("The Author")
        .setType(EMessageType.INFO)
;
 

This message will print to the following lines:

The Author: info from Message5WHTests in the class API documentation >> showing a test message 
       ==> as a demo 
       ==> added to the class JavaDoc
 

Version:

v0.0.3 build 150618 (18-Jun-15) for Java 1.8

Author:

Sven van der Meer <vdmeer.sven@mykolab.com>

Field Summary

Fields

Modifier and Type	Field and Description
protected int	initialCapacity Initial capacity for StrBuilder members
static String	messageSTGroup The default STGroup definition for the 5WH message class.
static Map<String,List<String>>	stChunks

Constructor Summary

Constructors

Constructor and Description
Message5WH() Simple constructor setting/loading defaults for the object.

Method Summary

Modifier and Type	Method and Description
Message5WH	addHow(Object... how) Builder method: adds to the How? part of the message.
Message5WH	addWhat(Object... what) Builder method: adds to the What? part of the message.
Message5WH	addWhy(Object... why) Builder method: adds to the Why? part of the message.
org.apache.commons.lang3.text.StrBuilder	getHow() Returns the How? part of the message.
Object	getReporter() Returns the reporter of the message
EMessageType	getType() Returns the type of the message.
org.apache.commons.lang3.text.StrBuilder	getWhat() Returns the What? part of the message.
Object	getWhen() Returns the When? part of the message.
org.stringtemplate.v4.ST	getWhere() Returns the Where? part of the message.
Object	getWho() Returns the Who? part of the message.
org.apache.commons.lang3.text.StrBuilder	getWhy() Returns the Why? part of the message.
String	render() Renders the message for output.
Message5WH	setReporter(Object reporter) Builder method: sets the Reporter of the message.
Message5WH	setSTG(org.stringtemplate.v4.STGroup stg) Sets a new STGroup for the message.
Message5WH	setType(EMessageType type) Builder method: sets the type of the message.
Message5WH	setWhen(Object when) Builder method: sets the When? part of the message.
Message5WH	setWhere(Object where)
Message5WH	setWhere(Object where, int line, int column) Builder method: sets the Where? part of the message.
Message5WH	setWhere(Object where, org.antlr.v4.runtime.ParserRuleContext lineAndColumn) Builder method: sets the Where? part of the message.
Message5WH	setWhere(Object where, org.antlr.v4.runtime.RecognitionException lineAndColumn) Builder method: sets the Where? part of the message.
Message5WH	setWhere(Object where, org.antlr.v4.runtime.Token lineAndColumn) Builder method: sets the Where? part of the message.
Message5WH	setWhere(StackTraceElement ste) Builder method: sets the Where? part of the message.
Message5WH	setWho(Object who) Builder method: sets the Who? part of the message.
Set<String>	testSTG(org.stringtemplate.v4.STGroup stg) Tests the given STGroup.
String	toString() Returns a string representation of the message for debugging purpose, but not the rendered output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.vandermeer.skb.base.Skb_Renderable

OBJECT_TO_RENDERABLE_VALUE

Field Detail

messageSTGroup

public static final String messageSTGroup

The default STGroup definition for the 5WH message class.

See Also:

Constant Field Values

stChunks

public static final Map<String,List<String>> stChunks

initialCapacity

protected int initialCapacity

Initial capacity for StrBuilder members

Constructor Detail

Message5WH

public Message5WH()

Simple constructor setting/loading defaults for the object. It does not set any implicit defaults for any part of the message (5WH) nor the reporter or the message type. All of those members are initialised with the standard object default "null". This initial capacity for all StrBuilder parts of the message (what, why and how) is set to 50 (characters).

Method Detail

addHow

public Message5WH addHow(Object... how)

Builder method: adds to the How? part of the message. If the argument is null, no change will be done. Otherwise if nothing was set to How? yet, the given argument will be used as initial value. If not, then the argument will be appended as is w/o any implicit separators.

Parameters:

how - additional information for How?

Returns:

this to allow concatenation

addWhat

public Message5WH addWhat(Object... what)

Builder method: adds to the What? part of the message. If the argument is null, no change will be done. Otherwise if nothing was set to What? yet, the given argument will be used as initial value. If not, then the argument will be appended as is w/o any implicit separators.

Parameters:

what - additional information for What?

Returns:

this to allow concatenation

addWhy

public Message5WH addWhy(Object... why)

Builder method: adds to the Why? part of the message. If the argument is null, no change will be done. Otherwise if nothing was set to Why? yet, the given argument will be used as initial value. If not, then the argument will be appended as is w/o any implicit separators.

Parameters:

why - additional information for Why?

Returns:

this to allow concatenation

setSTG

public Message5WH setSTG(org.stringtemplate.v4.STGroup stg)

Sets a new STGroup for the message. The STGroup contains the two templates used for rendering a message: where and message5wh. The default templates are defined in messageSTGroup.

Parameters:

stg - new STGroup

Returns:

returns always self, but only sets the new STGroup if it contains the two required functions with all arguments

testSTG

public Set<String> testSTG(org.stringtemplate.v4.STGroup stg)

Tests the given STGroup. The test basically looks into the STGroup for the two required templates where and message5wh and their required arguments. The required arguments are provided by stChunks.

Parameters:

stg - STGroup to test

Returns:

null if input group was null, a set size 0 of everything was ok, a set size > 0 with detailed error messages otherwise

render

public String render()

Renders the message for output.

Specified by:

render in interface Skb_Renderable

Returns:

returns a rendered version of the message as string

getHow

public org.apache.commons.lang3.text.StrBuilder getHow()

Returns the How? part of the message.

Returns:

How? part, null if no set

getReporter

public Object getReporter()

Returns the reporter of the message

Returns:

message reporter, null if not set

getType

public EMessageType getType()

Returns the type of the message.

Returns:

message type, null if not set

getWhat

public org.apache.commons.lang3.text.StrBuilder getWhat()

Returns the What? part of the message.

Returns:

What? part, null if no set

getWhen

public Object getWhen()

Returns the When? part of the message.

Returns:

When? part, null if no set

getWhere

public org.stringtemplate.v4.ST getWhere()

Returns the Where? part of the message.

Returns:

Where? part, null if no set

getWho

public Object getWho()

Returns the Who? part of the message.

Returns:

Who? part, null if no set

getWhy

public org.apache.commons.lang3.text.StrBuilder getWhy()

Returns the Why? part of the message.

Returns:

Why? part, null if no set

setReporter

public Message5WH setReporter(Object reporter)

Builder method: sets the Reporter of the message. Since null is a valid value for this member of the message, no further check is applied to the argument.

Parameters:

reporter - new reporter

Returns:

this to allow concatenation

setType

public Message5WH setType(EMessageType type)

Builder method: sets the type of the message. Since null is a valid value for this member of the message, no further check is applied to the argument.

Parameters:

type - new type

Returns:

this to allow concatenation

setWhen

public Message5WH setWhen(Object when)

Builder method: sets the When? part of the message. Since null is a valid value for this part of the message, no further check is applied to the argument.

Parameters:

when - new When? part

Returns:

this to allow concatenation

setWhere

public Message5WH setWhere(Object where,
                           int line,
                           int column)

Builder method: sets the Where? part of the message. Nothing will be set if the first parameter is null.

Parameters:

where - location for Where?

line - line for Where?, ignored if <1;

column - column for Where?, ignored if <1

Returns:

this to allow concatenation

setWhere

public Message5WH setWhere(Object where,
                           org.antlr.v4.runtime.RecognitionException lineAndColumn)

Builder method: sets the Where? part of the message. Line and column information are taken from the recognition exception, if they are larger than 0. Nothing will be set if the two parameters are null.

Parameters:

where - location for Where?

lineAndColumn - source for the Where? part

Returns:

this to allow concatenation

setWhere

public Message5WH setWhere(Object where)

setWhere

public Message5WH setWhere(Object where,
                           org.antlr.v4.runtime.Token lineAndColumn)

Builder method: sets the Where? part of the message. Line and column information are taken from the token, if they are larger than 0. Nothing will be set if the two parameters are null.

Parameters:

where - location for Where?

lineAndColumn - source for the Where? part

Returns:

this to allow concatenation

setWhere

public Message5WH setWhere(Object where,
                           org.antlr.v4.runtime.ParserRuleContext lineAndColumn)

Builder method: sets the Where? part of the message. Line and column information are taken from the tree, if they are larger than 0. Nothing will be set if the two parameters are null.

Parameters:

where - location for Where?

lineAndColumn - source for the Where? part

Returns:

this to allow concatenation

setWhere

public Message5WH setWhere(StackTraceElement ste)

Builder method: sets the Where? part of the message. Three values are taken from the stack trace: class name and method name for the location of Where? and line number for the the line. If the stack trace is null or class name and method are empty, nothing will be set. A line number of 0 will be ignored.

Parameters:

ste - source for the Where? part

Returns:

this to allow concatenation

setWho

public Message5WH setWho(Object who)

Builder method: sets the Who? part of the message. Since null is a valid value for this part of the message, no further check is applied to the argument.

Parameters:

who - new Who? part

Returns:

this to allow concatenation

toString

public String toString()

Returns a string representation of the message for debugging purpose, but not the rendered output. To render the message, i.e. to get the message as a text for logging or console output, please use render().

Overrides:

toString in class Object

Returns:

(debug) string representation of the message