Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at
 
     http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


=======================
Locale Selector Portlet
=======================

  Overviews:
  ----------

   The goal of Locale Selector is that Jetpseed user selects the preferred
   locale for J2 on Locale Selector Portlet.

   Currently, J2 determines the locale from Browser Preferred Locale or
   System Default Locale. Introducing Locale Selector, J2 gets the preferred
   locale by the following order:

    1. User Persistence Database
    2. Session Attribute
    3. Browser Preferred Locale
    4. System Default Locale


  Design:
  -------

   i) Process to set prefered locale

                        User's Prefered Locale
                                 | Select the locale by user
                                 V
                      ---------------------------
                      | Locale Selector Portlet |
                      ---------------------------
                                 | Set Prefered Locale
                                 V
                   -------------------------------------
                   | User's Persistence Database(TODO) |
                   |              and                  |
                   |      Application Scope Session    |
                   -------------------------------------


   ii) Process to get prefered locale

                   -------------------------------------
                   | User's Persistence Database(TODO) |
                   |              or                   |
                   |      Application Scope Session    |
                   -------------------------------------
                                 | Get Prefered Locale
                                 V
             -------------------------------------------------
             |        Jetspeed2(Portal Container)            |
             | o.a.j.localization.impl.LocalizationValveImpl |
             |   o.a.j.engine.servlet.ServletRequestImpl     |
             -------------------------------------------------
                                 | Prefered Locale Info
                                 V
                    Portlets, Libraries or Frameworks


  Task Lists:
  -----------

   Added Classes
   -------------

    o org.apache.jetspeed.portlets.localeselector.LocaleSelectorPortlet
      (Class for Locale Selector Portlet)

     - Set the selected locale to User's Persistence Database. (if not anon)
     - Set the selected locale to the session attribute [Done]
       (The name of the session key is "org.apache.jetspeed.prefered.locale".)


   Added Resources
   ---------------

    o org.apache.jetspeed.portlets.localeselector.resources.LocaleSelectorResources.properties

     - Message resource file for Locale Selector Portlet [Done]

    o org.apache.jetspeed.portlets.localeselector.resources.LocaleSelectorResources_en.properties

     - English message resource file for Locale Selector Portlet [Done]

    o org.apache.jetspeed.portlets.localeselector.resources.LocaleSelectorResources_ja.properties

     - Japanese message resource file for Locale Selector Portlet [Done]


   Added Methods
   -------------

    o org.apache.jetspeed.engine.servlet.ServletRequestImpl#getLocale()

     - Return the selected locale [Done]

    o org.apache.jetspeed.engine.servlet.ServletRequestImpl#getLocales()

     - Return the selected locale [Done]

    o org.apache.jetspeed.engine.servlet.ServletRequestImpl#getHeader()

     - Rewrite the value for Accept-language header

    o org.apache.jetspeed.engine.servlet.ServletRequestImpl#getHeaders()

     - Rewrite the value for Accept-language header


   Modified Methods
   ----------------

    o org.apache.jetspeed.localization.impl.LocalizationValveImpl#invoke()

     - Get the selected locale from User's Persistence Database. (if not anon)
     - Get the selected locale from the session attribute. [Done]
       (The name of the session key is "org.apache.jetspeed.prefered.locale".)


  Current Version:
  ----------------

   - Session based Locale Selector
   - Support JSTL(Taglibs fmt 1.0.4)
     (if your portlet uses HttpServletRequest#getLocale or
      HttpServletRequest#getLocales, your i18n mechanism will work.)
   - Support English and Japanese locale on Locale Selector Portlet
     (not including the resource files other than en and ja, though you can
      select them. I expects l10n translator's contributions :))


  Future Version:
  ---------------

   - User's Persistance Database&Session based Locale Selector
   - Support JSTL(Taglibs fmt 1.1 or later), and other frameworks
     (For JSTL 1.1, need to implement ServletRequestImpl#getHeaders().)