1 package org.apache.struts2;
2
3 import java.util.List;
4 import java.util.Set;
5 import java.util.Map;
6
7 /***
8 * Collection of messages. Supports nesting messages by field name.
9 *
10 * <p>Uses keys when adding instead of actual messages to decouple code from messages.
11 *
12 * @author crazybob@google.com (Bob Lee)
13 */
14 public interface Messages {
15
16
17
18 /***
19 * Message severity.
20 */
21 public enum Severity {
22
23 /***
24 * Informational messages.
25 */
26 INFO,
27
28 /***
29 * Warning messages.
30 */
31 WARN,
32
33 /***
34 * Error messages.
35 */
36 ERROR,
37 }
38
39 /***
40 * Gets nested messages for the given field.
41 *
42 * <p>Supports dot notation to represent nesting. For example:
43 *
44 * <pre>
45 * messages.forField("foo").forField("bar") == messages.forField("foo.bar")
46 * </pre>
47 *
48 * @param fieldName name of the field
49 * @return nested {@code Messages} for given field name
50 */
51 Messages forField(String fieldName);
52
53 /***
54 * Gets map of field name to messages for that field.
55 *
56 * @return map of field name to {@code Messages}
57 */
58 Map<String, Messages> forFields();
59
60 /***
61 * Adds informational message.
62 *
63 * @param key message key
64 * @see Severity.INFO
65 */
66 void addInformation(String key);
67
68 /***
69 * Adds informational message.
70 *
71 * @param key message key
72 * @param arguments message arguments
73 * @see Severity.INFO
74 */
75 void addInformation(String key, String... arguments);
76
77 /***
78 * Adds warning message.
79 *
80 * @param key message key
81 * @see Severity.WARN
82 */
83 void addWarning(String key);
84
85 /***
86 * Adds warning message.
87 *
88 * @param key message key
89 * @param arguments message arguments
90 * @see Severity.WARN
91 */
92 void addWarning(String key, String... arguments);
93
94 /***
95 * Adds error message.
96 *
97 * @param key message key
98 * @see Severity.ERROR
99 */
100 void addError(String key);
101
102 /***
103 * Adds error message.
104 *
105 * @param key message key
106 * @param arguments message arguments
107 * @see Severity.ERROR
108 */
109 void addError(String key, String... arguments);
110
111 /***
112 * Adds message.
113 *
114 * @param severity message severity
115 * @param key message key
116 */
117 void add(Severity severity, String key);
118
119 /***
120 * Adds request-scoped message.
121 *
122 * @param severity message severity
123 * @param key message key
124 * @param arguments message arguments
125 */
126 void add(Severity severity, String key, String... arguments);
127
128 /***
129 * Gets set of severities for which this {@code Messages} instance has messages. Not recursive.
130 *
131 * @return unmodifiable set of {@link Severity} sorted from least to most severe
132 */
133 Set<Severity> getSeverities();
134
135 /***
136 * Gets message strings for the given severity. Not recursive.
137 *
138 * @param severity message severity
139 * @return unmodifiable list of messages
140 */
141 List<String> forSeverity(Severity severity);
142
143 /***
144 * Gets error message strings for this {@code Messages} instance. Not recursive.
145 *
146 * @return unmodifiable list of messages
147 */
148 List<String> getErrors();
149
150 /***
151 * Gets error message strings for this {@code Messages} instance. Not recursive.
152 *
153 * @return unmodifiable list of messages
154 */
155 List<String> getWarnings();
156
157 /***
158 * Gets informational message strings for this {@code Messages} instance. Not recursive.
159 *
160 * @return unmodifiable list of messages
161 */
162 List<String> getInformation();
163
164 /***
165 * Returns true if this or a nested {@code Messages} instance has error messages.
166 *
167 * @see Severity.ERROR
168 */
169 boolean hasErrors();
170
171 /***
172 * Returns true if this or a nested {@code Messages} instance has warning messages.
173 *
174 * @see Severity.WARN
175 */
176 boolean hasWarnings();
177
178 /***
179 * Returns true if this or a nested {@code Messages} instance has informational messages.
180 *
181 * @see Severity.INFO
182 */
183 boolean hasInformation();
184
185 /***
186 * Returns true if this and all nested {@code Messages} instances have no messages.
187 */
188 boolean isEmpty();
189
190 /***
191 * Returns true if this and all nested {@code Messages} instances have no messages for the given severity.
192 *
193 * @param severity message severity
194 */
195 boolean isEmpty(Severity severity);
196 }