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