001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.resources;
019
020 import java.util.Iterator;
021
022 /**
023 * <p>
024 * A class that encapsulates messages. MessageList can be either global
025 * or they are specific to a particular bean property.
026 * </p>
027 * <p>
028 * Each individual message is described by an <code>Message</code>
029 * object, which contains a message key (to be looked up in an appropriate
030 * message resources database), and up to four placeholder arguments used for
031 * parametric substitution in the resulting message.
032 * </p>
033 * <p>
034 * <strong>IMPLEMENTATION NOTE</strong> - It is assumed that these objects
035 * are created and manipulated only within the context of a single thread.
036 * Therefore, no synchronization is required for access to internal
037 * collections.
038 * </p>
039 * Orginally based on org.apache.struts.action.ActionMessages, Revision 49670.
040 */
041 public interface MessageList {
042
043 /**
044 * A default key to represent "global" messages
045 * that do not pertain to a particular property.
046 */
047 public static final String GLOBAL_MESSAGE_KEY =
048 "org.apache.commons.resources.GLOBAL_MESSAGE";
049
050 /**
051 * @return The default global message key
052 */
053 public String getGlobalMessageKey();
054
055 /**
056 * @param globalMessageKey The new default global message key
057 */
058 public void setGlobalMessageKey(String globalMessageKey);
059
060 /**
061 * Add a message to the set of messages for the specified property. An
062 * order of the property/key is maintained based on the initial addition
063 * of the property/key.
064 *
065 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY)
066 * @param message The message to be added
067 */
068 public void add(String property, Message message);
069
070 /**
071 * Add a message to the set of messages for the "global" property. An
072 * order of the property/key is maintained based on the initial addition
073 * of the property/key.
074 *
075 * @param message The message to be added
076 */
077 public void add(Message message);
078
079 /**
080 * Adds the messages from the given <code>MessageList</code> object to
081 * this set of messages. The messages are added in the order they are returned from
082 * the properties() method. If a message's property is already in the current
083 * <code>MessageList</code> object it is added to the end of the list for that
084 * property. If a message's property is not in the current list it is added to the end
085 * of the properties.
086 *
087 * @param messages The <code>MessageList</code> object to be added.
088 */
089 public void add(MessageList messages);
090
091 /**
092 * Clear all messages recorded by this object.
093 */
094 public void clear();
095
096 /**
097 * Determines if the MessageList's messages have been accessed one or more
098 * times. Returns <code>true</code> if the <code>get()</code> or
099 * <code>get(String)</code> methods are called.
100 * @return <code>true</code> if the messages have been accessed one or more
101 * times.
102 */
103 public boolean isAccessed();
104
105 /**
106 * @return Return <code>true</code> if there are no messages recorded
107 * in this collection, or <code>false</code> otherwise.
108 */
109 public boolean isEmpty();
110
111 /**
112 * Return the set of all recorded messages, without distinction
113 * by which property the messages are associated with. If there are
114 * no messages recorded, an empty enumeration is returned.
115 *
116 * @return All messages.
117 */
118 public Iterator get();
119
120 /**
121 * Return the set of messages related to a specific property.
122 * If there are no such messages, an empty enumeration is returned.
123 *
124 * @param property Property name
125 * @return Messages related to a specific property.
126 */
127 public Iterator get(String property);
128
129 /**
130 * Return the set of property names for which at least one message has
131 * been recorded. If there are no messages, an empty Iterator is returned.
132 * If you have recorded global messages, the String value of
133 * <code>MessageList.GLOBAL_MESSAGE</code> will be one of the returned
134 * property names.
135 *
136 * @return The property names.
137 */
138 public Iterator properties();
139
140 /**
141 * Return the number of messages recorded for all properties (including
142 * global messages). <strong>NOTE</strong> - it is more efficient to call
143 * <code>isEmpty()</code> if all you care about is whether or not there are
144 * any messages at all.
145 *
146 * @return The number of messages.
147 */
148 public int size();
149
150 /**
151 * Return the number of messages associated with the specified property.
152 *
153 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY
154 * @return The number of messages for a specific property.
155 */
156 public int size(String property);
157
158 }
159