1 /*
2 * Copyright 2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.commons.scaffold.util;
18
19
20 import java.util.Iterator;
21
22 /**
23 * <p>
24 * A class that encapsulates messages. Messages can be either global
25 * or they are specific to a particular bean property.
26 * </p>
27 * <p>
28 * Each individual message is described by an <code>Message</code>
29 * object, which contains a message key (to be looked up in an appropriate
30 * message resources database), and up to four placeholder arguments used for
31 * parametric substitution in the resulting message.
32 * </p>
33 * <p>
34 * <strong>IMPLEMENTATION NOTE</strong> - It is assumed that these objects
35 * are created and manipulated only within the context of a single thread.
36 * Therefore, no synchronization is required for access to internal
37 * collections.
38 * </p>
39 * @author David Geary
40 * @author Craig R. McClanahan
41 * @author David Winterfeldt
42 * @author David Graham
43 * @author Ted Husted
44 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
45 */
46 public interface Messages {
47
48 public static final String GLOBAL_MESSAGE_KEY = "GLOBAL_MESSAGE";
49
50 /**
51 * Add a message to the set of messages for the specified property. An
52 * order of the property/key is maintained based on the initial addition
53 * of the property/key.
54 *
55 * @param property Property name (or Messages.GLOBAL_MESSAGE_KEY)
56 * @param message The message to be added
57 */
58 public void add(String property, Message message);
59
60 /**
61 * Add a message to the set of messages for the "global" property. An
62 * order of the property/key is maintained based on the initial addition
63 * of the property/key.
64 *
65 * @param message The message to be added
66 */
67 public void add(Message message);
68
69 /**
70 * Adds the messages from the given <code>Messages</code> object to
71 * this set of messages. The messages are added in the order they are returned from
72 * the properties() method. If a message's property is already in the current
73 * <code>Messages</code> object it is added to the end of the list for that
74 * property. If a message's property is not in the current list it is added to the end
75 * of the properties.
76 *
77 * @param messages The <code>Messages</code> object to be added.
78 */
79 public void add(Messages messages);
80
81 /**
82 * Clear all messages recorded by this object.
83 */
84 public void clear();
85
86 /**
87 * Return <code>true</code> if there are no messages recorded
88 * in this collection, or <code>false</code> otherwise.
89 * @deprecated Use isEmpty instead.
90 */
91 public boolean empty();
92
93 /**
94 * Return <code>true</code> if there are no messages recorded
95 * in this collection, or <code>false</code> otherwise.
96 */
97 public boolean isEmpty();
98
99 /**
100 * Return the set of all recorded messages, without distinction
101 * by which property the messages are associated with. If there are
102 * no messages recorded, an empty enumeration is returned.
103 */
104 public Iterator get();
105
106 /**
107 * Return the set of messages related to a specific property.
108 * If there are no such messages, an empty enumeration is returned.
109 *
110 * @param property Property name (or ActionMessages.GLOBAL_MESSAGE_KEY)
111 */
112 public Iterator get(String property);
113
114 /**
115 * Return the set of property names for which at least one message has
116 * been recorded. If there are no messages, an empty Iterator is returned.
117 * If you have recorded global messages, the String value of
118 * <code>Messages.GLOBAL_MESSAGE</code> will be one of the returned
119 * property names.
120 */
121 public Iterator properties();
122
123 /**
124 * Return the number of messages recorded for all properties (including
125 * global messages). <strong>NOTE</strong> - it is more efficient to call
126 * <code>empty()</code> if all you care about is whether or not there are
127 * any messages at all.
128 */
129 public int size();
130
131 /**
132 * Return the number of messages associated with the specified property.
133 *
134 * @param property Property name (or Messages.GLOBAL_MESSAGE_KEY
135 */
136 public int size(String property);
137
138 } // end Messages