LocaleAction


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.acting;
17  
18  import org.apache.avalon.framework.configuration.Configurable;
19  import org.apache.avalon.framework.configuration.Configuration;
20  import org.apache.avalon.framework.configuration.ConfigurationException;
21  import org.apache.avalon.framework.parameters.Parameters;
22  import org.apache.avalon.framework.thread.ThreadSafe;
23  
24  import org.apache.cocoon.environment.Redirector;
25  import org.apache.cocoon.environment.SourceResolver;
26  import org.apache.cocoon.i18n.I18nUtils;
27  
28  import java.util.HashMap  ;
29  import java.util.Locale  ;
30  import java.util.Map  ;
31  
32  /**
33   * An action that locates and provides to the pipeline locale information
34   * looked up in a range of ways.
35   *
36   * <h1>Configuration</h1>
37   * <p>A sample configuration (given in the &lt;map:matchers&gt; section of the
38   * sitemap) is given below. This configuration shows default values.
39   * </p>
40   * <pre>
41   *   &lt;map:action name="locale" SRC="org.apache.cocoon.acting.LocaleAction"&gt;
42   *     &lt;locale-attribute&gt;locale&lt;/locale-attribute&gt;
43   *     &lt;use-locale&gt;true&lt;/use-locale&gt;
44   *     &lt;default-locale language="en" country="US"/&gt;
45   *     &lt;store-in-request&gt;false&lt;store-in-request&gt;
46   *     &lt;create-session&gt;false&lt;create-session&gt;
47   *     &lt;store-in-session&gt;false&lt;store-in-session&gt;
48   *     &lt;store-in-cookie&gt;false&lt;store-in-cookie&gt;
49   *   &lt;/map:action&gt;
50   * </pre>
51   *
52   * <p>Above configuration parameters mean:
53   *   <ul>
54   *     <li><b>locale-attribute</b> specifies the name of the request
55   *     parameter / session attribute / cookie that is to be used as a locale
56   *     (defaults to <code>locale</code>)</li>
57   *     <li><b>use-locale</b> specifies whether the primary locale provided
58   *     by the user agent (or server default, is no locale passed by the agent)
59   *     is to be used</li>
60   *     <li><b>default-locale</b> specifies the default locale to be used when
61   *     none found.</li>
62   *     <li><b>store-in-request</b> specifies whether found locale should be
63   *     stored as request attribute.</li>
64   *     <li><b>create-session</b> specifies whether session should be created
65   *     when storing found locale as session attribute.</li>
66   *     <li><b>store-in-session</b> specifies whether found locale should be
67   *     stored as session attribute.</li>
68   *     <li><b>store-in-cookie</b> specifies whether found locale should be
69   *     stored as cookie.</li>
70   *   </ul>
71   * </p>
72   *
73   * <h1>Usage</h1>
74   * <p>This action will be used in a pipeline like so:</p>
75   * <pre>
76   *   &lt;map:act type="locale"&gt;
77   *     &lt;map:generate SRC="file_{language}_{country}_{variant}.xml"/&gt;
78   *     ...
79   *   &lt;/map:match&gt;
80   * </pre>
81   * <p>or</p>
82   * <pre>
83   *   &lt;map:act type="locale"&gt;
84   *     &lt;map:generate SRC="file_{locale}.xml"/&gt;
85   *     ...
86   *   &lt;/map:match&gt;
87   * </pre>
88   *
89   * <h1>Locale Identification</h1>
90   * <p>Locales will be tested in following order:</p>
91   * <ul>
92   *   <li>Locale provided as a request parameter</li>
93   *   <li>Locale provided as a session attribute</li>
94   *   <li>Locale provided as a cookie</li>
95   *   <li>Locale provided using a sitemap parameter<br>
96   *   (&lt;map:parameter name="locale" value="{1}"/&gt; style parameter within
97   *   the &lt;map:match&gt; node)</li>
98   *   <li>Locale provided by the user agent, or server default,
99   *   if <code>use-locale</code> is set to <code>true</code></li>
100  *   <li>The default locale, if specified in the matcher's configuration</li>
101  * </ul>
102  * <p>First found locale will be returned.</p>
103  *
104  * <h1>Sitemap Variables</h1>
105  * <p>Once locale has been found, the following sitemap variables
106  * will be available to sitemap elements contained within the action:</p>
107  * <ul>
108  *   <li>{locale}: The locale string</li>
109  *   <li>{language}: The language of the found locale</li>
110  *   <li>{country}: The country of the found locale</li>
111  *   <li>{variant}: The variant of the found locale</li>
112  * </ul>
113  *
114  * @author <a HREF="mailto:Marcus.Crafter@osa.de">Marcus Crafter</a>
115  * @author <a HREF="mailto:kpiroumian@flagship.ru">Konstantin Piroumian</a>
116  * @author <a HREF="mailto:lassi.immonen@valkeus.com">Lassi Immonen</a>
117  * @author <a HREF="mailto:vgritsenko@apache.org">Vadim Gritsenko</a>
118  * @version CVS $Id: LocaleAction.java 36530 2004-08-17 14:50:12Z vgritsenko $
119  */
120 public class LocaleAction extends ServiceableAction implements ThreadSafe, Configurable {
121 
122     private static final String   DEFAULT_DEFAULT_LANG = "en";
123     private static final String   DEFAULT_DEFAULT_COUNTRY = "US";
124     private static final String   DEFAULT_DEFAULT_VARIANT = "";
125 
126     /**
127       * Default locale attribute name.
128      */
129     public static final String   LOCALE = "locale";
130 
131     /**
132      * Configuration element name for locale attribute name.
133      */
134     public static final String   LOCALE_ATTR = "locale-attribute";
135 
136 
137     /**
138      * Constant representing the request storage configuration attribute
139      */
140     public static final String   STORE_REQUEST = "store-in-request";
141 
142     /**
143      * Constant representing the session creation configuration attribute
144      */
145     public static final String   CREATE_SESSION = "create-session";
146 
147     /**
148      * Constant representing the session storage configuration attribute
149      */
150     public static final String   STORE_SESSION = "store-in-session";
151 
152     /**
153      * Constant representing the cookie storage configuration attribute
154      */
155     public static final String   STORE_COOKIE = "store-in-cookie";
156 
157 
158     /**
159      * Name of the locale request parameter, session attribute, cookie.
160      */
161     private String   localeAttribute;
162 
163     /**
164      * Whether to query locale provided by the user agent or not.
165      */
166     private boolean useLocale;
167 
168     /**
169      * Default locale if no other found and {@link #useLocale} is false.
170      */
171     private Locale   defaultLocale;
172 
173     /**
174      * Store the locale in request. Default is not to do this.
175      */
176     private boolean storeInRequest;
177 
178     /**
179      * Store the locale in session, if available. Default is not to do this.
180      */
181     private boolean storeInSession;
182 
183     /**
184      * Should we create a session if needed. Default is not to do this.
185      */
186     private boolean createSession;
187 
188     /**
189      * Should we add a cookie with the locale. Default is not to do this.
190      */
191     private boolean storeInCookie;
192 
193     /**
194      * Configure this action.
195      *
196      * @param config configuration information (if any)
197      */
198     public void configure(Configuration config)
199     throws ConfigurationException {
200         this.storeInRequest = config.getChild(STORE_REQUEST).getValueAsBoolean(false);
201         this.createSession = config.getChild(CREATE_SESSION).getValueAsBoolean(false);
202         this.storeInSession = config.getChild(STORE_SESSION).getValueAsBoolean(false);
203         this.storeInCookie = config.getChild(STORE_COOKIE).getValueAsBoolean(false);
204         if (getLogger().isDebugEnabled()) {
205             getLogger().debug((this.storeInRequest ? "will" : "won't") + " set values in request");
206             getLogger().debug((this.createSession ? "will" : "won't") + " create session");
207             getLogger().debug((this.storeInSession ? "will" : "won't") + " set values in session");
208             getLogger().debug((this.storeInCookie ? "will" : "won't") + " set values in cookies");
209         }
210 
211         this.localeAttribute = config.getChild(LOCALE_ATTR).getValue(LOCALE);
212         this.useLocale = config.getChild("use-locale").getValueAsBoolean(true);
213 
214         Configuration child = config.getChild("default-locale", false);
215         if (child != null) {
216             this.defaultLocale = new Locale  (child.getAttribute("language", DEFAULT_DEFAULT_LANG),
217                                             child.getAttribute("country", DEFAULT_DEFAULT_COUNTRY),
218                                             child.getAttribute("variant", DEFAULT_DEFAULT_VARIANT));
219         }
220 
221         if (getLogger().isDebugEnabled()) {
222             getLogger().debug("Locale attribute name is " + this.localeAttribute);
223             getLogger().debug((this.useLocale ? "will" : "won't") + " use request locale");
224             getLogger().debug("default locale " + this.defaultLocale);
225         }
226     }
227 
228     /**
229      * Action which obtains the current environments locale information, and
230      * places it in the objectModel (and optionally in a session/cookie).
231      */
232     public Map   act(Redirector redirector,
233                    SourceResolver resolver,
234                    Map   objectModel,
235                    String   source,
236                    Parameters params)
237     throws Exception   {
238         // Obtain locale information from request, session, cookies, or params
239         Locale   locale = I18nUtils.findLocale(objectModel,
240                                              localeAttribute,
241                                              params,
242                                              defaultLocale,
243                                              useLocale);
244 
245         if (locale == null) {
246             if (getLogger().isDebugEnabled()) {
247                 getLogger().debug("No locale found.");
248             }
249 
250             return null;
251         }
252 
253         String   localeStr = locale.toString();
254         if (getLogger().isDebugEnabled()) {
255             getLogger().debug("Found locale: " + localeStr);
256         }
257 
258         I18nUtils.storeLocale(objectModel,
259                               localeAttribute,
260                               localeStr,
261                               storeInRequest,
262                               storeInSession,
263                               storeInCookie,
264                               createSession);
265 
266         // Set up a map for sitemap parameters
267         Map   map = new HashMap  ();
268         map.put("language", locale.getLanguage());
269         map.put("country", locale.getCountry());
270         map.put("variant", locale.getVariant());
271         map.put("locale", localeStr);
272         return map;
273     }
274 
275     /**
276      * Helper method to retreive the attribute value containing locale
277      * information. See class documentation for locale determination algorythm.
278      *
279      * @deprecated See I18nUtils.findLocale
280      * @param objectModel requesting object's environment
281      * @return locale value or <code>null</null> if no locale was found
282      */
283     public static String   getLocaleAttribute(Map   objectModel,
284                                             String   localeAttrName) {
285         Locale   locale = I18nUtils.findLocale(objectModel,
286                                              localeAttrName,
287                                              null,
288                                              null,
289                                              true);
290         return locale.toString();
291     }
292 }
293
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags