View Javadoc

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      // TODO: Use Object[] for args instead of String[].
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 }