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 }