001    package hirondelle.web4j.webmaster;
002    
003    import java.util.*;
004    
005    import hirondelle.web4j.model.AppException;
006    import hirondelle.web4j.util.WebUtil;
007    
008    /**
009     Send a simple email from the webmaster to a list of receivers.
010     
011     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
012     {@link hirondelle.web4j.BuildImpl#forEmailer()} 
013     returns the configured implementation of this interface.
014     
015     <P>Implementations of this interface will be called by the framework when it needs 
016     to send an email. For example, {@link TroubleTicket} uses such an implementation to 
017     send diagnostic information to the webmaster. The from-address is taken from the 
018     webmaster email configured in <tt>web.xml</tt>. 
019     
020     <P><b>Sending Email on a Separate Thread</b><br>
021     Some implementations might send emails on a separate worker thread.
022     However, such implementations can be tricky. If your application creates a thread on its own, then
023     the Servlet Container will likely not be able to shut down in the regular way. The thread 
024     will be unknown to the Container, and will likely prevent it from shutting down. 
025     
026     <P>The {@link EmailerImpl} default implementation of this interface doesn't use a 
027     separate worker thread. See <tt>web.xml</tt> in the example applications for more details. 
028    */
029    public interface Emailer {
030      
031      /**
032       Send an email from the webmaster to a list of receivers. 
033      
034       @param aToAddresses contains email addresses of the receivers, as a List of Strings that satisfy 
035       {@link WebUtil#isValidEmailAddress(String)}
036       @param aSubject satisfies {@link hirondelle.web4j.util.Util#textHasContent}
037       @param aBody satisfies {@link hirondelle.web4j.util.Util#textHasContent}
038      */
039      void sendFromWebmaster(List<String> aToAddresses, String aSubject, String aBody) throws AppException;
040      
041    }