001    package hirondelle.web4j.request;
002    
003    import java.util.Locale;
004    import javax.servlet.http.HttpServletRequest;
005    
006    /**
007     Return the {@link Locale} associated with a given request.
008    
009     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
010     {@link hirondelle.web4j.BuildImpl#forLocaleSource()} 
011     returns the configured implementation of this interface. See {@link LocaleSourceImpl} for a default implementation. 
012     This interface is similar to {@link TimeZoneSource}, and is used in much the same way.
013     
014     <P>In general, a {@link Locale} is used for two distinct operations :
015    <ul>
016     <li>render objects such as <tt>Integer</tt>, <tt>Date</tt>, and so on
017     <li>translate text from one language to another 
018    </ul> 
019    
020     <P>Since almost all applications at least <em>render</em> data, then almost all applications 
021     will also use a {@link Locale} - <em>even single-language applications.</em> 
022     
023     <P>In a single-language application, the returned <tt>Locale</tt> is used by WEB4J for 
024     rendering these items : 
025    <ul>
026     <li>user response messages containing numbers and dates
027     <li>presenting <tt>ResultSets</tt> as reports (dates, numbers)
028     <li>prepopulating forms (dates, numbers)
029     <li>displaying dates with {@link hirondelle.web4j.ui.tag.ShowDate}
030    </ul>
031    
032     <P>If the application is multilingual, then the returned <tt>Locale</tt> is <em>also</em>
033      used for translating text. See {@link hirondelle.web4j.ui.translate.Translator} and related classes 
034      for more information. 
035     
036     <P>A very large number of policies can be defined by implementations of this interface. 
037     Possible sources of <tt>Locale</tt> information include :
038    <ul>
039     <li>a single setting in <tt>web.xml</tt>, place into application scope upon startup 
040     <li>an object stored in session scope
041     <li>a request parameter
042     <li>a request header
043     <li>a cookie
044    </ul>
045    
046     <P>All WEB4J applications have at least one {@link Locale} - the <tt>DefaultLocale</tt> setting 
047     configured in <tt>web.xml</tt>. (This allows the application's <tt>Locale</tt> to be set 
048     explicitly, independent of the server's default <tt>Locale</tt> setting, or of browser 
049     header settings.) For applications which use only a single language, that <tt>Locale</tt> defines 
050     how WEB4J will format the items mentioned above. For multilingual applications, this <tt>web.xml</tt> setting is 
051     reinterpreted as the <em>default</em> <tt>Locale</tt>, which is overridden by implementations of this 
052     interface. 
053    */
054    public interface LocaleSource {
055      
056      /** Return a {@link Locale} corresponding to a given underlying request.  */
057      public Locale get(HttpServletRequest aRequest);
058      
059    }