Copyright 2004 The Apache Software Foundation

Licensed 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().)