com.levigo.util.swing.messaging
Class MessageManager

java.lang.Object
  com.levigo.util.swing.messaging.MessageManager

public class MessageManager
extends Object

A class to handle messages forwarded to user, which can mean displaying them to the user.

This class is a singleton; to get an instance call getInstance()

To post a Message call one of the MessageManager's displayXXXMessage(...) methods

To register/deregister MessageListener,
call addMessageListener()/removeMessageListener()

To register/deregister a MessageFactory,
call addMessageFactory()/removeMessageFactory()

You can add an Default Error/Debug Stream, means protocolling error messages to Standard Err and debug information on Standard Out
Simply call addDefaultDebugStream()/addDefaultErrorStream() These methods can be called multiple times, but add only one DefaultStream.

Author:

Carolin Koehler

Method Summary

static void	addDefaultDebugStream() Adds the default Debug Stream to MessageManager Posts all messages to Standard Out
static void	addDefaultErrorStream() Adds the default Error Stream to MessageManager Posts only Errors to Standard Err
static void	addMessageFactory(MessageFactory aFactory) Adds a given MessageFactory.
static void	addMessageListener(MessageListener l) Adds a given MessageListener to the MessageManager.
static MessageResult	displayMessage(Component source, Message messageToDisplay) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier, Object... messageParameters) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier, Object[] messageParameters, Throwable e) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier, Throwable e) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier, Throwable e, boolean ignoreSuppression) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(Component source, String messageIdentifier, Throwable e, Object... messageParameters) Creates an appropriate MessageEvent Object and forwards it to all registered listeners.
static MessageResult	displayMessage(MessageEvent evt) Forwards given MessageEvent to all registered listeners.
static int	getListenerCount(Class listenerClass) Returns the total number of listeners of the supplied type registered as MessageListener at MessageManager.
static List	getListenerList() Returns a list of current registered listeners at MessageManager.
static Message	getMessage(String messageKey, Object[] messageParameters, Exception e) Returns the Messagethat was generated by the MessageFactory system for the given Message key.
static Collection	getSuppressableMessages() Returns a Collection of Messageidentifiers of messages that are allowed to be suppressed by the user.
static boolean	isMessageSuppressed(String messageKey) Returns true if the user has switched off this message.
static void	removeMessageFactory(MessageFactory aFactory) Removes a given Message Factory
static void	removeMessageListener(MessageListener l) Removes a given MessageListener from MessageManager's listener list
static void	setPreferenceStore(com.levigo.util.preferences.PreferenceStore prefStore) Specify the PreferenceStorewhere the suppressed messages per user are stored.
static void	suppressMessage(String messageIdentifier) Deregisters a message.
static void	unsuppressMessage(String messageIdentifier) Registers a message.

Methods inherited from class java.lang.Object

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

Method Detail

addDefaultErrorStream

public static void addDefaultErrorStream()

Adds the default Error Stream to MessageManager Posts only Errors to Standard Err

getListenerCount

public static int getListenerCount(Class listenerClass)

Returns the total number of listeners of the supplied type registered as MessageListener at MessageManager.

Parameters:

listenerClass -

getListenerList

public static List getListenerList()

Returns a list of current registered listeners at MessageManager.

Returns:

list of registered listener instances

addDefaultDebugStream

public static void addDefaultDebugStream()

Adds the default Debug Stream to MessageManager Posts all messages to Standard Out

addMessageListener

public static void addMessageListener(MessageListener l)

Adds a given MessageListener to the MessageManager. The same instance of a MessageListener can only be added once.

Parameters:

l - The listener that receives the MessageEvents

removeMessageListener

public static void removeMessageListener(MessageListener l)

Removes a given MessageListener from MessageManager's listener list

Parameters:

l -

displayMessage

public static MessageResult displayMessage(Component source,
                                           Message messageToDisplay)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageToDisplay - the message to be displayed

Returns:

MessageResult

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier,
                                           Throwable e)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

e - An exception that will be attached to the message.

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier,
                                           Throwable e,
                                           boolean ignoreSuppression)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. In difference to other message displaying methods, this one ignores possible settings regarding suppressed messages. Therefore this method should be used with care - and only where it is appropriate to ignore suppression settings - e.g. when the connection to the preference store is already broken (see SQLPreferenceStore#queryPreferenceValue()).

The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialogwith the correct parent frame.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

e - An exception that will be attached to the message.

ignoreSuppression - Ignores if the message might be suppressed

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier,
                                           Throwable e,
                                           Object... messageParameters)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

messageParameters - fillers for possible placeholders in message body text

e - An exception that will be attached to the message.

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier,
                                           Object[] messageParameters,
                                           Throwable e)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

messageParameters - fillers for possible placeholders in message body text

e - An exception that will be attached to the message.

displayMessage

public static MessageResult displayMessage(Component source,
                                           String messageIdentifier,
                                           Object... messageParameters)

Creates an appropriate MessageEvent Object and forwards it to all registered listeners. The source should contain a reference to a component, since this may be used by listeners to open e.g. a Dialog with the correct parent frame.

Note:
You can use the predefined message types in this class, or define types for your own. But respect the RESERVED_MESSAGE_MAX_ID. It is imperative, that your type ID is larger than RESERVED_MESSAGE_MAX_ID.

Parameters:

source - a component within the component hierarchy of the Frame which initiates the message. Null is a valid argument for the component, if there is no way of getting a reasonable component.

messageIdentifier - the identifier to look up in the resource

messageParameters - fillers for possible placeholders in message body text

displayMessage

public static MessageResult displayMessage(MessageEvent evt)

Forwards given MessageEvent to all registered listeners.

Parameters:

evt - the event

Returns:

MessageResult message result of the recipients

suppressMessage

public static void suppressMessage(String messageIdentifier)

Deregisters a message.

If a message, described by a message Identifier, should not be delivered, you can deregister it here.

Parameters:

messageIdentifier -

unsuppressMessage

public static void unsuppressMessage(String messageIdentifier)

Registers a message.

If a message was deregistered, you can register it again by this method. This method does nothing, message was not deregisterd.

Parameters:

messageIdentifier -

See Also:

suppressMessage(String)

addMessageFactory

public static void addMessageFactory(MessageFactory aFactory)

Adds a given MessageFactory.

Note:
MessageManager inspects its factories in the order of registering In detail, the very last registered factory will be inspect at first and so on. To add a factory also means to change the order of searching for message contents, If you want to be sure, that a factory is inspecting first, call this method. MessageManager doesn't hold a factory twice. If it is already registered, a call of this method will change only the order to inspect.

Parameters:

aFactory -

removeMessageFactory

public static void removeMessageFactory(MessageFactory aFactory)

Removes a given Message Factory

Parameters:

aFactory - resource to be removed

setPreferenceStore

public static void setPreferenceStore(com.levigo.util.preferences.PreferenceStore prefStore)

Specify the PreferenceStorewhere the suppressed messages per user are stored.

isMessageSuppressed

public static boolean isMessageSuppressed(String messageKey)

Returns true if the user has switched off this message.

getSuppressableMessages

public static Collection getSuppressableMessages()

Returns a Collection of Messageidentifiers of messages that are allowed to be suppressed by the user.

Returns:

A collection of Strings that represent the message keys

getMessage

public static Message getMessage(String messageKey,
                                 Object[] messageParameters,
                                 Exception e)

Returns the Messagethat was generated by the MessageFactory system for the given Message key.

It is recommended NOT to use this method to display messages; use the variants of displayMessage() instead.

Parameters:

messageKey - The key of the message that's used for the message lookup by the MessageFactoryHolder

messageParameters - Fillers for possible placeholders in message body text; leave null if you do not want to provide any

e - An exception that will be attached to the message; leave null if you do not want to provide any

Returns:

Message