001    package hirondelle.web4j.security;
002    
003    import hirondelle.web4j.request.RequestParser;
004    
005    /**
006     Determine if text is likely spam.
007     
008     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
009     {@link hirondelle.web4j.BuildImpl#forSpamDetector()} 
010     returns the configured implementation of this interface.
011     
012     <P><a href="http://en.wikipedia.org/wiki/Forum_spam">Spam</a> refers to unwanted input from 
013     undesirable parties (usually advertising of some sort) that is often POSTed to servers using automated means.
014     
015     <P>Most spam contains <em>links</em>. Implementations are encouraged to detect unwanted links.
016     
017     <P>The <tt>SpamDetectionInFirewall</tt> setting in <tt>web.xml</tt> can instruct the 
018     {@link hirondelle.web4j.security.ApplicationFirewall} to use the configured <tt>SpamDetector</tt> 
019     to reject <em>all</em> requests containing at least one parameter that appears to be spam. 
020     Such filtering is applied as a 
021     <a href="ApplicationFirewall.html#HardValidation">hard validation</a>, and will <em>not</em> result in 
022     a polished response to the end user.
023     
024     <P>If that policy is felt to be too aggressive, then the only alternative is to check <em>all 
025     items input as text</em> using {@link hirondelle.web4j.model.Check#forSpam()} (usually  
026     in a Model Object constructor). Such checks do <em>not</em> need to be applied to
027     numeric or date data, since the regular conversion validations done by {@link RequestParser} for 
028     numbers and dates will already detect and reject any spam.  
029    */
030    public interface SpamDetector {
031      
032      /** 
033       Determine if the given text is very likely spam.
034       
035       @param aText value of a request parameter.
036      */
037      boolean isSpam(String aText);
038    
039    }