001 /*
002 * $Id: MessageList.java 366395 2006-01-06 02:42:19Z niallp $
003 * $Revision: 366395 $
004 * $Date: 2006-01-06 02:42:19 +0000 (Fri, 06 Jan 2006) $
005 *
006 * ====================================================================
007 *
008 * Copyright 2003-2006 The Apache Software Foundation
009 *
010 * Licensed under the Apache License, Version 2.0 (the "License");
011 * you may not use this file except in compliance with the License.
012 * You may obtain a copy of the License at
013 *
014 * http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing, software
017 * distributed under the License is distributed on an "AS IS" BASIS,
018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019 * See the License for the specific language governing permissions and
020 * limitations under the License.
021 *
022 */
023
024 package org.apache.commons.resources;
025
026 import java.util.Iterator;
027
028 /**
029 * <p>
030 * A class that encapsulates messages. MessageList can be either global
031 * or they are specific to a particular bean property.
032 * </p>
033 * <p>
034 * Each individual message is described by an <code>Message</code>
035 * object, which contains a message key (to be looked up in an appropriate
036 * message resources database), and up to four placeholder arguments used for
037 * parametric substitution in the resulting message.
038 * </p>
039 * <p>
040 * <strong>IMPLEMENTATION NOTE</strong> - It is assumed that these objects
041 * are created and manipulated only within the context of a single thread.
042 * Therefore, no synchronization is required for access to internal
043 * collections.
044 * </p>
045 * Orginally based on org.apache.struts.action.ActionMessages, Revision 49670.
046 */
047 public interface MessageList {
048
049 /**
050 * A default key to represent "global" messages
051 * that do not pertain to a particular property.
052 */
053 public static final String GLOBAL_MESSAGE_KEY =
054 "org.apache.commons.resources.GLOBAL_MESSAGE";
055
056 /**
057 * @return The default global message key
058 */
059 public String getGlobalMessageKey();
060
061 /**
062 * @param globalMessageKey The new default global message key
063 */
064 public void setGlobalMessageKey(String globalMessageKey);
065
066 /**
067 * Add a message to the set of messages for the specified property. An
068 * order of the property/key is maintained based on the initial addition
069 * of the property/key.
070 *
071 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY)
072 * @param message The message to be added
073 */
074 public void add(String property, Message message);
075
076 /**
077 * Add a message to the set of messages for the "global" property. An
078 * order of the property/key is maintained based on the initial addition
079 * of the property/key.
080 *
081 * @param message The message to be added
082 */
083 public void add(Message message);
084
085 /**
086 * Adds the messages from the given <code>MessageList</code> object to
087 * this set of messages. The messages are added in the order they are returned from
088 * the properties() method. If a message's property is already in the current
089 * <code>MessageList</code> object it is added to the end of the list for that
090 * property. If a message's property is not in the current list it is added to the end
091 * of the properties.
092 *
093 * @param messages The <code>MessageList</code> object to be added.
094 */
095 public void add(MessageList messages);
096
097 /**
098 * Clear all messages recorded by this object.
099 */
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