Package de.vandermeer.skb.base.message

Classes for a simple 5WH message object, for details on 5WH see Wikipedia.

See: Description

Class Summary

Class	Description
Message5WH	Standard SKB message.
Message5WH_Builder	Builder for a Message5WH object.

Enum Summary

Enum	Description
E_MessageType	Types for Message5WH.

Package de.vandermeer.skb.base.message Description

Classes for a simple 5WH message object, for details on 5WH see Wikipedia. This message object 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?

The 'where' part of a message is further divided into

• Location - the location of the where part, e.g. a file in which an error was detected. The location is mandatory to use the where part.
• Line - a line in the location, e.g. a line in a file with an error. The line is optional, but must be present if column (see below) is used.
• Column - a column in the location, e.g. a column in a line in a file with an error. The column is optional and can be used along with line (see above).

In addition to that, the object also provides for information on

• Reporter - the object actually reporting the message, e.g. a shell or a compiler
• Message type - a type, e.g. information, warning, error

The package provides a set of classes for creating and processing messages:

• Message5WH - the actual message object with all the parts introduced above.
• Message5WH_Builder - a builder object that is used to create a message object.
• MessageRenderer - a renderer object that is used to render a message before printing or storing.
• E_MessageType - an enumerate for the supported message types, e.g. info, warning, error.
• FormattingTupleWrapper - a wrapper to create SLF4J formatting tuples and convert them into strings when needed. The wrapper creates a new formatting tuple and uses its getMessage() method in toString().

Creating a message

Use the builder to create a message. The following example shows a simple information message being created:

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

The builder provides methods to set the who, when, and where parts of the message as well as the reporter and the type. For the what, why, and how parts the builder provides methods to add to existing information. The where part of a message as a special case is supported with several methods to be set.

Once all information is set, the builder can be instructed to build an actual message using the build() method.

Rendering a message

The message class provides a render() method to render a message. Internally, this method creates a StrBuilder, fills it conditional with all information of the message, and returns the string representation of that builder.

Rendering the message create above using the render() method will result in the following output (printed to standard out):

        The Author: from Test_Examples at (noon) in the package API documentation showing a test message
                ==> as a demo
                ==> added to the package JavaDoc

 

Changing the render output

Changing the render output requires to create a new class inheriting from the Message5WH class and overwriting the render() method. Alternatively, one can implement a message renderer with any required functionality. The package 'managers' does exactly that: implement a message renderer that uses string templates and provides many options to render single messages, collections of messages and some classes that use message objects.

Version:

v0.2.0 build 170404 (04-Apr-17) for Java 1.8

Author:

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