001: /**
002: * Copyright 2006 Webmedia Group Ltd.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: **/package org.araneaframework.framework;
016:
017: import java.util.Map;
018: import java.util.Set;
019: import org.araneaframework.http.UpdateRegionProvider;
020:
021: /**
022: * A context for adding messages to a central pool of messages for later
023: * output with a consistent look.
024: * <p>A good example is {@link org.araneaframework.framework.filter.StandardMessagingFilterWidget}.
025: * It registers a MessageContext in the environment and if a childservice needs to output a
026: * message which should have a consistent look (location on the screen, styles etc.) it adds
027: * the message via <code>showMessage(String,String)</code>.
028: * </p>
029: * <p>
030: * A widget can use the MessageContext from the environment to output the accumulated
031: * messages.
032: * </p>
033: * <p>
034: * Permanent messages should stay in MessageContext until explicitly cleared, other messages should
035: * be cleared after the user has seen them once.
036: * </p>
037: *
038: * @author "Toomas Römer" <toomas@webmedia.ee>
039: * @author Jevgeni Kabanov (ekabanov <i>at</i> araneaframework <i>dot</i> org)
040: * @author Taimo Peelo (taimo@araneaframework.org)
041: */
042: public interface MessageContext extends UpdateRegionProvider {
043: /** @since 1.1 */
044: public static final String MESSAGE_REGION_KEY = "messages";
045:
046: /**
047: * A message type indicating its an error message.
048: */
049: public static final String ERROR_TYPE = "error";
050:
051: /**
052: * A message type indicating its an info message.
053: */
054: public static final String WARNING_TYPE = "warning";
055:
056: /**
057: * A message type indicating its an info message.
058: */
059: public static final String INFO_TYPE = "info";
060:
061: /**
062: * Shows a message <code>message</code> of type <code>type</code> to the user.
063: * Message is cleared after the user sees it once.
064: */
065: public void showMessage(String type, String message);
066:
067: /**
068: * Shows <code>messages</code> of given <code>type</code> to the user.
069: * Messages are cleared after the user sees them once.
070: *
071: * @param messages Set<String>
072: * @since 1.1
073: */
074: public void showMessages(String type, Set messages);
075:
076: /**
077: * Removes a message <code>message</code> of type <code>type</code>.
078: * @since 1.1
079: */
080: public void hideMessage(String type, String message);
081:
082: /**
083: * Removes messages <code>message</code> of type <code>type</code>.
084: * @param messages Set<String>
085: *
086: * @since 1.1
087: */
088: public void hideMessages(String type, Set messages);
089:
090: /**
091: * Shows an error message to the user.
092: */
093: public void showErrorMessage(String message);
094:
095: /**
096: * Hides an error message from user.
097: * @since 1.1
098: */
099: public void hideErrorMessage(String message);
100:
101: /**
102: * Shows a warning message to the user.
103: */
104: public void showWarningMessage(String message);
105:
106: /**
107: * Hides a warning message from user.
108: * @since 1.1
109: */
110: public void hideWarningMessage(String message);
111:
112: /**
113: * Shows an informative message to the user.
114: */
115: public void showInfoMessage(String message);
116:
117: /**
118: * Hides an info message from user.
119: * @since 1.1
120: */
121: public void hideInfoMessage(String message);
122:
123: /**
124: * Clears all non-permanent messages.
125: */
126: public void clearMessages();
127:
128: /**
129: * Shows a permanent message <code>message</code> of type <code>type</code> to the user.
130: * The message will be shown until hidden explicitly.
131: */
132: public void showPermanentMessage(String type, String message);
133:
134: /**
135: * Clears the specific permanent message, under all message types where it might be present.
136: * @param message to be removed from permanent messages
137: */
138: public void hidePermanentMessage(String message);
139:
140: /**
141: * Clears all of the permanent messages.
142: */
143: public void clearPermanentMessages();
144:
145: /**
146: * Clears all messages (both permanent and usual).
147: */
148: public void clearAllMessages();
149:
150: /**
151: * Returns all messages as a Map. The keys
152: * of the Map are the different message types encountered so far and under the keys
153: * are the messages in a Collection.
154: * <p>
155: * A child service should do as follows to access the messages
156: * <pre>
157: * <code>
158: * ...
159: * MessageContext msgCtx = (MessageContext) getEnvironment().requireEntry(MessageContext.class);
160: * Map map = msgCtx.getMessages();
161: * Collection list = (Collection) map.get(MessageContext.ERROR_TYPE); // collection contains all the error messages
162: * </code>
163: * </pre>
164: * The map could be null if this service was not used. The collection is null if no messages of
165: * that type been added to the messages.
166: * </p>
167: *
168: * @since 1.1
169: */
170: public Map getMessages();
171: }
|