com.marringtons.string
Class Messages

java.lang.Object
  com.marringtons.string.Messages

public class Messages

extends Object

Use this class when developing a GUI it is necessary to communicate information messages, problems and errors to the client. Many, if not most, programs are interactive - accepting commands from a user and processing accordingly. The user needs reports of problems that arise during this interaction - whether the problem is caused by a program error or by invalid input. This class records problems against a key. These problems can later be listed and retrieved by key. Usually the key is related to a user input field so that the GUI can display the problem and relate it to the entry field that may have caused it. "Number out of range" is a lousy message if a form includes multiple numeric fields. It is also a lousy message anyway in that it does not provide enough information - but that is another story. A request from the user will cause a problem instance to be created. As the request is processed, any problems that may arise can be recorded. Lastly the GUI can display the problems recorded as part of the user response. Messages created use MessageFormat, so allow parameter replacement to add variable elements. Use this rather than string concatenation as it will later allow easier language translation. Messages that allow exceptions and Throwable instances to be added will write the message to the long and record a log id into the problem message for reference. There is even a convenience constructor to create a problem with a single exception message.

   void myServlet()
     {
       Messages problems = new Messages();
       ...
       String yearString = getArg( "years");
       if (! validateYears( yearString))
         problems.add( 
           "years::Sorry, I don't understand the age ''{0}''", yearString);
       ...
       problems..add( "date::it is the wrong year");
       ...
       try
         { saveFile( name) }
       catch (Exception e)
         { problems.add( e, Message.pattern("writing file {0}").format( name)); }
    
       // or to drop all other messages
       try
         { process() }
       catch (Throwable e)
         {
           respond new Messages( e, "processing file");
           return;	// all done as problem is very fatal
         }
   
       respond( problems);
     }
   
   void aggregateServlet()
     {
       Messages problems = process1();
       Messages moreProblems = process2();
       problems.add( moreProblems);
       showProblems( problems);
     }
   
  
 

Author:

Paul Marrington

See Also:

Format

Constructor Summary

Messages()
Deprecated. only to be used by getThreadInstance() or getSessionInstance()

Messages(Throwable throwable, Object message)
Deprecated.

Method Summary

void	add(Messages moreProblems) When you get problems from multiple sources you will need to add them all together to make one big problem.
String	add(Object object) Add a simple problem message.
String	add(String key, Object message) Add a simple problem message with a specified key.
String	add(Throwable throwable) When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem.
String	add(Throwable throwable, Object message) When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem.
String	add(Throwable throwable, String key, Object message) When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem.
String	first() Used to iterate through all the problems.
String	get() Retrieve all messages associated with the general key (*).
String	get(String keyToRetrieve) Retrieve all messages for a specific key appended and separated by line-feeds.
static Messages	getInstance() Retrieve a message instance that is not tied to any data persister.
static Messages	getSessionInstance()
static Messages	getThreadInstance()
String	next() Used to iterate through all the problems.
boolean	none() See if there are any problems.
String	toString() Override toString to provide a better representation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Messages

public Messages()

Deprecated. only to be used by getThreadInstance() or getSessionInstance()

Sets the default key to be the global problem indication (*).

Messages

public Messages(Throwable throwable,
                Object message)

Deprecated.

There are times when we get a fatal error that needs to be recorded as a new problem list. It will be recorded against the global key (*).

Parameters:

throwable - Exception that caused the problem.

message - Message to give more information for the problem.

Method Detail

getThreadInstance

public static Messages getThreadInstance()

Returns:

Messages associated with this thread. Usually used as error messages to be displayed in response to a browser request.

getSessionInstance

public static Messages getSessionInstance()

Returns:

Messages associated with this session. Used to collate messages from non-interactive threads with information for the user. A classic example is an alarm or countdown timer.

getInstance

public static Messages getInstance()

Retrieve a message instance that is not tied to any data persister.

Returns:

New Messages().

add

public void add(Messages moreProblems)

When you get problems from multiple sources you will need to add them all together to make one big problem.

Parameters:

moreProblems - more problems to add to the list.

add

public String add(Object object)

Add a simple problem message. The key can be specified as part of the string using a :: separator.

Parameters:

object - to set as a problem message using @see toString();

Returns:

the formatted message set

add

public String add(String key,
                  Object message)

Add a simple problem message with a specified key.

Parameters:

key - to save message under for later retrieval in groups.

message - to set as a problem message

Returns:

the formatted message set

add

public String add(Throwable throwable)

When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem. This version uses the exception message as the problem display message.

Parameters:

throwable - an exception to log and record in problem

Returns:

the formatted message set

add

public String add(Throwable throwable,
                  Object message)

When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem.

Parameters:

message - to set as a problem message

throwable - an exception to log and record in problem

Returns:

the formatted message set

add

public String add(Throwable throwable,
                  String key,
                  Object message)

When a problem is generated because of an exception, the exception and stack are logged and the log reference ID is added to the message recorded as a problem.

Parameters:

message - to set as a problem message

throwable - an exception to log and record in problem

key - to save message under for later retrieval in groups.

Returns:

the formatted message set

none

public boolean none()

See if there are any problems.

   if (problems.none()) finishProcessing();
 

Returns:

true if there are no messages to report

get

public String get(String keyToRetrieve)

Retrieve all messages for a specific key appended and separated by line-feeds.

Parameters:

keyToRetrieve -

Returns:

message (empty if there are none)

get

public String get()

Retrieve all messages associated with the general key (*).

Returns:

All messages associated with the general key (*).

first

public String first()

Used to iterate through all the problems.

Returns:

The first problem key (or null of none).

See Also:

next()

next

public String next()

Used to iterate through all the problems.

Returns:

The next problem key (or null of no more).

See Also:

first()

toString

public String toString()

Override toString to provide a better representation.

Returns:

a human readable list of problems - sorted by key (key: value).