001    package hirondelle.web4j.webmaster;
003    import java.util.*;
005    import hirondelle.web4j.model.AppException;
006    import hirondelle.web4j.util.WebUtil;
008    /**
009     Send a simple email from the webmaster to a list of receivers.
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.
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>. 
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. 
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 {
031      /**
032       Send an email from the webmaster to a list of receivers. 
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;
041    }