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