org.apache.struts.action.ActionMessages Maven / Gradle / Ivy
/*
* $Id$
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.struts.action;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
/**
* A class that encapsulates messages. Messages can be either global or
* they are specific to a particular bean property.
*
* Each individual message is described by an ActionMessage
* object, which contains a message key (to be looked up in an appropriate
* message resources database), and up to four placeholder arguments used for
* parametric substitution in the resulting message.
*
* IMPLEMENTATION NOTE - It is assumed that these objects
* are created and manipulated only within the context of a single thread.
* Therefore, no synchronization is required for access to internal
* collections.
*
* @version $Rev$ $Date: 2005-08-26 21:58:39 -0400 (Fri, 26 Aug 2005)
* $
* @since Struts 1.1
*/
public class ActionMessages implements Serializable {
/**
* Compares ActionMessageItem objects.
*/
private static final Comparator ACTION_ITEM_COMPARATOR =
new Comparator() {
public int compare(Object o1, Object o2) {
return ((ActionMessageItem) o1).getOrder()
- ((ActionMessageItem) o2).getOrder();
}
};
// ----------------------------------------------------- Manifest Constants
/**
* The "property name" marker to use for global messages, as opposed to
* those related to a specific property.
*/
public static final String GLOBAL_MESSAGE =
"org.apache.struts.action.GLOBAL_MESSAGE";
// ----------------------------------------------------- Instance Variables
/**
* Have the messages been retrieved from this object?
*
* The controller uses this property to determine if session-scoped
* messages can be removed.
*
* @since Struts 1.2
*/
protected boolean accessed = false;
/**
* The accumulated set of ActionMessage objects
* (represented as an ArrayList) for each property, keyed by property
* name.
*/
protected HashMap messages = new HashMap();
/**
* The current number of the property/key being added. This is used to
* maintain the order messages are added.
*/
protected int iCount = 0;
// --------------------------------------------------------- Public Methods
/**
* Create an empty ActionMessages object.
*/
public ActionMessages() {
super();
}
/**
* Create an ActionMessages object initialized with the
* given messages.
*
* @param messages The messages to be initially added to this object. This
* parameter can be null.
* @since Struts 1.1
*/
public ActionMessages(ActionMessages messages) {
super();
this.add(messages);
}
/**
* Add a message to the set of messages for the specified property. An
* order of the property/key is maintained based on the initial addition
* of the property/key.
*
* @param property Property name (or ActionMessages.GLOBAL_MESSAGE)
* @param message The message to be added
*/
public void add(String property, ActionMessage message) {
ActionMessageItem item = (ActionMessageItem) messages.get(property);
List list;
if (item == null) {
list = new ArrayList();
item = new ActionMessageItem(list, iCount++, property);
messages.put(property, item);
} else {
list = item.getList();
}
list.add(message);
}
/**
* Adds the messages from the given ActionMessages object
* to this set of messages. The messages are added in the order they are
* returned from the properties method. If a message's
* property is already in the current ActionMessages object,
* it is added to the end of the list for that property. If a message's
* property is not in the current list it is added to the end of the
* properties.
*
* @param actionMessages The ActionMessages object to be
* added. This parameter can be null.
* @since Struts 1.1
*/
public void add(ActionMessages actionMessages) {
if (actionMessages == null) {
return;
}
// loop over properties
Iterator props = actionMessages.properties();
while (props.hasNext()) {
String property = (String) props.next();
// loop over messages for each property
Iterator msgs = actionMessages.get(property);
while (msgs.hasNext()) {
ActionMessage msg = (ActionMessage) msgs.next();
this.add(property, msg);
}
}
}
/**
* Clear all messages recorded by this object.
*/
public void clear() {
messages.clear();
}
/**
* Return true if there are no messages recorded in this
* collection, or false otherwise.
*
* @return true if there are no messages recorded in this
* collection; false otherwise.
* @since Struts 1.1
*/
public boolean isEmpty() {
return (messages.isEmpty());
}
/**
* Return the set of all recorded messages, without distinction by
* which property the messages are associated with. If there are no
* messages recorded, an empty enumeration is returned.
*
* @return An iterator over the messages for all properties.
*/
public Iterator get() {
this.accessed = true;
if (messages.isEmpty()) {
return Collections.EMPTY_LIST.iterator();
}
ArrayList results = new ArrayList();
ArrayList actionItems = new ArrayList();
for (Iterator i = messages.values().iterator(); i.hasNext();) {
actionItems.add(i.next());
}
// Sort ActionMessageItems based on the initial order the
// property/key was added to ActionMessages.
Collections.sort(actionItems, ACTION_ITEM_COMPARATOR);
for (Iterator i = actionItems.iterator(); i.hasNext();) {
ActionMessageItem ami = (ActionMessageItem) i.next();
for (Iterator msgsIter = ami.getList().iterator();
msgsIter.hasNext();) {
results.add(msgsIter.next());
}
}
return results.iterator();
}
/**
* Return the set of messages related to a specific property. If there
* are no such messages, an empty enumeration is returned.
*
* @param property Property name (or ActionMessages.GLOBAL_MESSAGE)
* @return An iterator over the messages for the specified property.
*/
public Iterator get(String property) {
this.accessed = true;
ActionMessageItem item = (ActionMessageItem) messages.get(property);
if (item == null) {
return (Collections.EMPTY_LIST.iterator());
} else {
return (item.getList().iterator());
}
}
/**
* Returns true if the get() or
* get(String) methods are called.
*
* @return true if the messages have been accessed one or
* more times.
* @since Struts 1.2
*/
public boolean isAccessed() {
return this.accessed;
}
/**
* Return the set of property names for which at least one message has
* been recorded. If there are no messages, an empty Iterator
* is returned. If you have recorded global messages, the
* String value of ActionMessages.GLOBAL_MESSAGE
* will be one of the returned property names.
*
* @return An iterator over the property names for which messages exist.
*/
public Iterator properties() {
if (messages.isEmpty()) {
return Collections.EMPTY_LIST.iterator();
}
ArrayList results = new ArrayList();
ArrayList actionItems = new ArrayList();
for (Iterator i = messages.values().iterator(); i.hasNext();) {
actionItems.add(i.next());
}
// Sort ActionMessageItems based on the initial order the
// property/key was added to ActionMessages.
Collections.sort(actionItems, ACTION_ITEM_COMPARATOR);
for (Iterator i = actionItems.iterator(); i.hasNext();) {
ActionMessageItem ami = (ActionMessageItem) i.next();
results.add(ami.getProperty());
}
return results.iterator();
}
/**
* Return the number of messages recorded for all properties (including
* global messages). NOTE - it is more efficient to call
* isEmpty if all you care about is whether or not there are
* any messages at all.
*
* @return The number of messages associated with all properties.
*/
public int size() {
int total = 0;
for (Iterator i = messages.values().iterator(); i.hasNext();) {
ActionMessageItem ami = (ActionMessageItem) i.next();
total += ami.getList().size();
}
return (total);
}
/**
* Return the number of messages associated with the specified
* property.
*
* @param property Property name (or ActionMessages.GLOBAL_MESSAGE)
* @return The number of messages associated with the property.
*/
public int size(String property) {
ActionMessageItem item = (ActionMessageItem) messages.get(property);
return (item == null) ? 0 : item.getList().size();
}
/**
* Returns a String representation of this ActionMessages' property
* name=message list mapping.
*
* @return String representation of the messages
* @see Object#toString()
*/
public String toString() {
return this.messages.toString();
}
/**
* This class is used to store a set of messages associated with a
* property/key and the position it was initially added to list.
*/
protected class ActionMessageItem implements Serializable {
/**
* The list of ActionMessages.
*/
protected List list = null;
/**
* The position in the list of messages.
*/
protected int iOrder = 0;
/**
* The property associated with ActionMessage.
*/
protected String property = null;
/**
* Construct an instance of this class.
*
* @param list The list of ActionMessages.
* @param iOrder The position in the list of messages.
* @param property The property associated with ActionMessage.
*/
public ActionMessageItem(List list, int iOrder, String property) {
this.list = list;
this.iOrder = iOrder;
this.property = property;
}
/**
* Retrieve the list of messages associated with this item.
*
* @return The list of messages associated with this item.
*/
public List getList() {
return list;
}
/**
* Set the list of messages associated with this item.
*
* @param list The list of messages associated with this item.
*/
public void setList(List list) {
this.list = list;
}
/**
* Retrieve the position in the message list.
*
* @return The position in the message list.
*/
public int getOrder() {
return iOrder;
}
/**
* Set the position in the message list.
*
* @param iOrder The position in the message list.
*/
public void setOrder(int iOrder) {
this.iOrder = iOrder;
}
/**
* Retrieve the property associated with this item.
*
* @return The property associated with this item.
*/
public String getProperty() {
return property;
}
/**
* Set the property associated with this item.
*
* @param property The property associated with this item.
*/
public void setProperty(String property) {
this.property = property;
}
/**
* Construct a string representation of this object.
*
* @return A string representation of this object.
*/
public String toString() {
return this.list.toString();
}
}
}