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 Foundation009 *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 at013 *014 * http://www.apache.org/licenses/LICENSE-2.0015 *016 * Unless required by applicable law or agreed to in writing, software017 * 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 and020 * limitations under the License.021 *022 */023024 package org.apache.commons.resources;025026 import java.util.Iterator;027028 /**029 * <p>030 * A class that encapsulates messages. MessageList can be either global031 * 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 appropriate036 * message resources database), and up to four placeholder arguments used for037 * parametric substitution in the resulting message.038 * </p>039 * <p>040 * <strong>IMPLEMENTATION NOTE</strong> - It is assumed that these objects041 * are created and manipulated only within the context of a single thread.042 * Therefore, no synchronization is required for access to internal043 * collections.044 * </p>045 * Orginally based on org.apache.struts.action.ActionMessages, Revision 49670.046 */047 public interface MessageList {048049 /**050 * A default key to represent "global" messages051 * that do not pertain to a particular property.052 */053 public static final String GLOBAL_MESSAGE_KEY =054 "org.apache.commons.resources.GLOBAL_MESSAGE";055056 /**057 * @return The default global message key058 */059 public String getGlobalMessageKey();060061 /**062 * @param globalMessageKey The new default global message key063 */064 public void setGlobalMessageKey(String globalMessageKey);065066 /**067 * Add a message to the set of messages for the specified property. An068 * order of the property/key is maintained based on the initial addition069 * of the property/key.070 *071 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY)072 * @param message The message to be added073 */074 public void add(String property, Message message);075076 /**077 * Add a message to the set of messages for the "global" property. An078 * order of the property/key is maintained based on the initial addition079 * of the property/key.080 *081 * @param message The message to be added082 */083 public void add(Message message);084085 /**086 * Adds the messages from the given <code>MessageList</code> object to087 * this set of messages. The messages are added in the order they are returned from088 * the properties() method. If a message's property is already in the current089 * <code>MessageList</code> object it is added to the end of the list for that090 * property. If a message's property is not in the current list it is added to the end091 * of the properties.092 *093 * @param messages The <code>MessageList</code> object to be added.094 */095 public void add(MessageList messages);096097 /**098 * Clear all messages recorded by this object.099 */100 public void clear();101102 /**103 * Determines if the MessageList's messages have been accessed one or more104 * 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 more107 * times.108 */109 public boolean isAccessed();110111 /**112 * @return Return <code>true</code> if there are no messages recorded113 * in this collection, or <code>false</code> otherwise.114 */115 public boolean isEmpty();116117 /**118 * Return the set of all recorded messages, without distinction119 * by which property the messages are associated with. If there are120 * no messages recorded, an empty enumeration is returned.121 *122 * @return All messages.123 */124 public Iterator get();125126 /**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 name131 * @return Messages related to a specific property.132 */133 public Iterator get(String property);134135 /**136 * Return the set of property names for which at least one message has137 * been recorded. If there are no messages, an empty Iterator is returned.138 * If you have recorded global messages, the String value of139 * <code>MessageList.GLOBAL_MESSAGE</code> will be one of the returned140 * property names.141 *142 * @return The property names.143 */144 public Iterator properties();145146 /**147 * Return the number of messages recorded for all properties (including148 * global messages). <strong>NOTE</strong> - it is more efficient to call149 * <code>isEmpty()</code> if all you care about is whether or not there are150 * any messages at all.151 *152 * @return The number of messages.153 */154 public int size();155156 /**157 * Return the number of messages associated with the specified property.158 *159 * @param property Property name (or MessageList.GLOBAL_MESSAGE_KEY160 * @return The number of messages for a specific property.161 */162 public int size(String property);163164 }165