001    package hirondelle.web4j.model;
002    
003    import java.util.List;
004    
005    /**
006     List of {@link AppResponseMessage} objects to be shown to the user.
007    
008    <P>Used for error messages, success messages, or any such item communicated 
009     to the user. See <tt>displayMessages.tag</tt> in the example application 
010     for an illustration of rendering a <tt>MessageList</tt>.
011    
012     <P>If a message needs to survive a redirect, it must be placed in 
013     session scope, not request scope. Typically, successful edits to the 
014     database use a redirect (to avoid the 
015     <a href='http://www.javapractices.com/Topic181.cjp'>duplicate-upon-browser-reload</a>
016     problem), so success messages will almost always be placed in session 
017     scope. Conversely, failure messages will usually be placed in request
018     scope.
019    
020     <P><em>Design Note</em><br>
021     The forces which WEB4J resolves are :
022     <ul>
023     <li>messages can be shown to the user upon both success and failure 
024     <li>redirect/forward behavior can occur for either success or failure
025     <li>rendering may be the same for both success and failure messages
026     <li>rendering may differ between success and failure messages
027     <li>the message may or may not include parameters 
028    </ul>
029    
030     <P>This item is provided as an interface because 
031     {@link AppException} needs to be both an <tt>Exception</tt>
032     and a <tt>MessageList</tt>.
033    */
034    public interface MessageList {
035    
036      /**
037       Add a simple {@link AppResponseMessage} to this list.
038      
039       <P>The argument satisfies the same conditions as {@link AppResponseMessage#forSimple}.
040      */
041      void add(String aErrorMessage);
042       
043      /**
044       Add a compound {@link AppResponseMessage} to this list.
045        
046       <P>The arguments satisfy the same conditions as {@link AppResponseMessage#forCompound}.
047      */
048      void add(String aErrorMessage, Object... aParams);
049      
050      /** Add all {@link AppResponseMessage}s attached to <tt>aAppEx</tt> to this list.  */
051      void add(AppException aAppEx);
052      
053      /**
054       Return <tt>true</tt> only if there are no messages in this list.
055      
056       <P>Note that this method name conflicts with the <tt>empty</tt> keyword 
057       of JSTL. Thus, {@link #isNotEmpty} is supplied as an alternative.
058      */
059      boolean isEmpty();
060      
061      /** Return the negation of {@link #isEmpty}.  */
062      boolean isNotEmpty();
063      
064      /**
065       Return an unmodifiable <tt>List</tt> of {@link AppResponseMessage}s.
066      */
067      List<AppResponseMessage> getMessages();
068      
069    }