View Javadoc

1   /*
2    * $Id: Messages.java 502296 2007-02-01 17:33:39Z niallp $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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      // TODO: Use Object[] for args instead of String[].
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 }