1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 package org.apache.commons.resources;
25
26 import java.util.Iterator;
27
28 /***
29 * <p>
30 * A class that encapsulates messages. MessageList can be either global
31 * or they are specific to a particular bean property.
32 * </p>
33 * <p>
34 * Each individual message is described by an <code>Message</code>
35 * object, which contains a message key (to be looked up in an appropriate
36 * message resources database), and up to four placeholder arguments used for
37 * parametric substitution in the resulting message.
38 * </p>
39 * <p>
40 * <strong>IMPLEMENTATION NOTE</strong> - It is assumed that these objects
41 * are created and manipulated only within the context of a single thread.
42 * Therefore, no synchronization is required for access to internal
43 * collections.
44 * </p>
45 * Orginally based on org.apache.struts.action.ActionMessages, Revision 49670.
46 */
47 public interface MessageList {
48
49 /***
50 * A default key to represent "global" messages
51 * that do not pertain to a particular property.
52 */
53 public static final String GLOBAL_MESSAGE_KEY =
54 "org.apache.commons.resources.GLOBAL_MESSAGE";
55
56 /***
57 * @return The default global message key
58 */
59 public String getGlobalMessageKey();
60
61 /***
62 * @param globalMessageKey The new default global message key
63 */
64 public void setGlobalMessageKey(String globalMessageKey);
65
66 /***
67 * Add a message to the set of messages for the specified property. An
68 * order of the property/key is maintained based on the initial addition
69 * of the property/key.
70 *
71 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY)
72 * @param message The message to be added
73 */
74 public void add(String property, Message message);
75
76 /***
77 * Add a message to the set of messages for the "global" property. An
78 * order of the property/key is maintained based on the initial addition
79 * of the property/key.
80 *
81 * @param message The message to be added
82 */
83 public void add(Message message);
84
85 /***
86 * Adds the messages from the given <code>MessageList</code> object to
87 * this set of messages. The messages are added in the order they are returned from
88 * the properties() method. If a message's property is already in the current
89 * <code>MessageList</code> object it is added to the end of the list for that
90 * property. If a message's property is not in the current list it is added to the end
91 * of the properties.
92 *
93 * @param messages The <code>MessageList</code> object to be added.
94 */
95 public void add(MessageList messages);
96
97 /***
98 * Clear all messages recorded by this object.
99 */
100 public void clear();
101
102 /***
103 * Determines if the MessageList's messages have been accessed one or more
104 * times. Returns <code>true</code> if the <code>get()</code> or
105 * <code>get(String)</code> methods are called.
106 * @return <code>true</code> if the messages have been accessed one or more
107 * times.
108 */
109 public boolean isAccessed();
110
111 /***
112 * @return Return <code>true</code> if there are no messages recorded
113 * in this collection, or <code>false</code> otherwise.
114 */
115 public boolean isEmpty();
116
117 /***
118 * Return the set of all recorded messages, without distinction
119 * by which property the messages are associated with. If there are
120 * no messages recorded, an empty enumeration is returned.
121 *
122 * @return All messages.
123 */
124 public Iterator get();
125
126 /***
127 * Return the set of messages related to a specific property.
128 * If there are no such messages, an empty enumeration is returned.
129 *
130 * @param property Property name
131 * @return Messages related to a specific property.
132 */
133 public Iterator get(String property);
134
135 /***
136 * Return the set of property names for which at least one message has
137 * been recorded. If there are no messages, an empty Iterator is returned.
138 * If you have recorded global messages, the String value of
139 * <code>MessageList.GLOBAL_MESSAGE</code> will be one of the returned
140 * property names.
141 *
142 * @return The property names.
143 */
144 public Iterator properties();
145
146 /***
147 * Return the number of messages recorded for all properties (including
148 * global messages). <strong>NOTE</strong> - it is more efficient to call
149 * <code>isEmpty()</code> if all you care about is whether or not there are
150 * any messages at all.
151 *
152 * @return The number of messages.
153 */
154 public int size();
155
156 /***
157 * Return the number of messages associated with the specified property.
158 *
159 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY
160 * @return The number of messages for a specific property.
161 */
162 public int size(String property);
163
164 }
165