IMessageManager.java

package com.digiarea.closure.model.validation;

import java.util.ArrayList;

import javafx.scene.control.Control;

/**
 * This interface provides for managing typed messages in a form. Typed messages
 * are messages associated with a type that indicates their severity (error,
 * warning, information). The interface is responsible for:
 * <ul>
 * <li>Bridging the concept of typed messages and control decorations</li>
 * <li>Adding one or more messages per control in a form</li>
 * <li>Rolling the local messages up to the form header</li>
 * <li>Adding one or more general messages to the form header</li>
 * </ul>
 * <p>
 * To use it in a form, do the following:
 * <ol>
 * <li>For each interactive control, add a listener to it to monitor user input</li>
 * <li>Every time the input changes, validate it. If there is a problem, add a
 * message with a unique key to the manager. If there is already a message with
 * the same key in the manager, its type and message text will be replaced (no
 * duplicates). Note that you add can messages with different keys to the same
 * control to track multiple problems with the user input.</li>
 * <li>If the problem has been cleared, remove the message using the key
 * (attempting to remove a message that is not in the manager is safe).</li>
 * <li>If something happens in the form that is not related to any control, use
 * the other <code>addMessage</code> method.</li>
 * </ol>
 * <p>
 * This interface should only be referenced. It must not be implemented or
 * extended.
 * </p>
 * 
 * @since 3.3
 * @see IMessageProvider
 * @see IManagedForm
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IMessageManager {

	public ArrayList<MessageCategory> getCategories();

	/**
	 * Adds a message that should be associated with the provided control. Note
	 * that subsequent calls using the same key will not result in duplicate
	 * messages. Instead, the previous message with the same key will be
	 * replaced with the new message.
	 * 
	 * @param key
	 *            the unique message key
	 * @param messageText
	 *            the message to add
	 * @param data
	 *            an object for application use (can be <code>null</code>)
	 * @param type
	 *            the message type
	 * @param control
	 *            the control to associate the message with
	 */
	void addMessage(String categoryKey, Object key, String messageText,
			Object data, int type, Control control);

	/**
	 * Removes the general message with the provided key. Does nothing if
	 * message for the key does not exist.
	 * 
	 * @param key
	 *            the key of the message to remove
	 */
	void removeMessage(Object key);

	/**
	 * Removes all the general messages. If there are local messages associated
	 * with controls, the replacement message may show up drawing user's
	 * attention to these local messages. Otherwise, the container will clear
	 * the message area.
	 */
	void removeMessages();

	/**
	 * Removes a keyed message associated with the provided control. Does
	 * nothing if the message for that key does not exist.
	 * 
	 * @param key
	 *            the id of the message to remove
	 * @param control
	 *            the control the message is associated with
	 */
	void removeMessage(Object key, Control control);

	/**
	 * Removes all the messages associated with the provided control. Does
	 * nothing if there are no messages for this control.
	 * 
	 * @param control
	 *            the control the messages are associated with
	 */
	void removeMessages(Control control);

	/**
	 * Removes all the local field messages and all the general container
	 * messages.
	 */
	void removeAllMessages();

	/**
	 * Updates the message container with the messages currently in the manager.
	 * There are two scenarios in which a client may want to use this method:
	 * <ol>
	 * <li>When controls previously managed by this manager have been disposed.</li>
	 * <li>When automatic update has been turned off.</li>
	 * </ol>
	 * In all other situations, the manager will keep the form in sync
	 * automatically.
	 * 
	 * @see #setAutoUpdate(boolean)
	 */
	void update();

	/**
	 * Controls whether the form is automatically updated when messages are
	 * added or removed. By default, auto update is on. Clients can turn it off
	 * prior to adding or removing a number of messages as a batch. Turning it
	 * back on will trigger an update.
	 * 
	 * @param enabled
	 *            sets the state of the automatic update
	 */
	void setAutoUpdate(boolean enabled);

	/**
	 * Tests whether the form will be automatically updated when messages are
	 * added or removed.
	 * 
	 * @return <code>true</code> if auto update is active, <code>false</code>
	 *         otherwise.
	 */
	boolean isAutoUpdate();

	/**
	 * When message manager is used in context of a form, and there are
	 * hyperlink listeners for messages in the header, the hyperlink event will
	 * carry an object of type <code>IMessage[]</code> as an href. You can use
	 * this method to create a summary text from this array consistent with the
	 * tool tip used by the form header.
	 * 
	 * @param messages
	 *            an array of messages
	 * @return a textual representation of the messages with one message per
	 *         line.
	 */
	String createSummary(IMessage[] messages);

}