/*

  * $Id: CollectionResourcesBase.java 354330 2005-12-06 06:05:19Z niallp $

  * $Revision: 354330 $

  * $Date: 2005-12-06 06:05:19 +0000 (Tue, 06 Dec 2005) $

  *

  * ====================================================================

  *

  *  Copyright 2003-2005 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.

  *

  */

 package org.apache.commons.resources.impl;

 import java.util.ArrayList;

 import java.util.HashMap;

 import java.util.HashSet;

 import java.util.Iterator;

 import java.util.List;

 import java.util.Locale;

 import java.util.Map;

 import java.util.Set;

 import org.apache.commons.logging.Log;

 import org.apache.commons.logging.LogFactory;

 import org.apache.commons.resources.ResourcesException;

 import org.apache.commons.resources.ResourcesKeyException;

 /**

  * <p>Abstract base classes for 

  * {@link org.apache.commons.resources.Resources} implementations that

  * store their name-value mappings for each supported <code>Locale</code>

  * in a URL-accessible resource file with a common base URL.  Subclasses

  * need only override <code>loadLocale()</code> to manage the details of

  * loading the name-value mappings for a particular Locale.</p>

  */

 public abstract class CollectionResourcesBase extends ResourcesBase {

     /**

      * <p>The logging instance for this class.</p>

      */

     private transient Log log =

         LogFactory.getLog(CollectionResourcesBase.class);

     /**

      * <p>Create a new {@link org.apache.commons.resources.Resources} instance with the specified

      * logical name and base URL.</p>

      *

      * @param name Logical name of the new instance

      * @param base Base URL of the resource files that contain the per-Locale

      *  name-value mappings for this {@link org.apache.commons.resources.Resources} instance

      */

     public CollectionResourcesBase(String name, String base) {

         super(name);

         this.base = base;

     }

     // ----------------------------------------------------- Instance Variables

     /**

      * <p>The base URL for the per-Locale resources files containing the

      * name-value mappings for this {@link org.apache.commons.resources.Resources} instance.</p>

      */

     private String base = null;

     /**

      * <p>The default <code>Locale</code> to use when no <code>Locale</code>

      * is specified by the caller.</p>

      */

     private Locale defaultLocale = Locale.getDefault();

     /**

      * <p>The previously calculated <code>Locale</code> lists returned

      * by <code>getLocaleList()</code>, keyed by <code>Locale</code>.</p>

      */

     private Map lists = new HashMap();

     /**

      * <p>The previously calculated name-value mappings <code>Map</code>s

      * returned by <code>getLocaleMap()</code>, keyed by <code>Locale</code>.

      * </p>

      */

     private Map maps = new HashMap();

     // ------------------------------------------------------------- Properties

     /**

      * Set the default locale.

      * @param defaultLocale The default Locale.

      */

     public void setDefaultLocale(Locale defaultLocale) {

         this.defaultLocale = defaultLocale;

     }

     /**

      * Return the default locale.

      * @return The default Locale.

      */

     public Locale getDefaultLocale() {

         return defaultLocale;

     }

     /**

      * @see org.apache.commons.resources.impl.ResourcesBase#getKeys()

      */

     public Iterator getKeys() {

         synchronized (maps) {

             Set results = new HashSet();

             Iterator locales = maps.keySet().iterator();

             while (locales.hasNext()) {

                 Locale locale = (Locale) locales.next();

                 Map map = (Map) maps.get(locale);

                 results.addAll(map.keySet());

             }

             return (results.iterator());

         }

     }

     // ---------------------------------------------- Content Retrieval Methods

     /**

      * <p>Return the content for the specified <code>key</code> as an

      * Object, localized based on the specified <code>locale</code>.

      * </p>

      *

      * @param key Identifier for the requested content

      * @param locale Locale with which to localize retrieval,

      *  or <code>null</code> for the default Locale

      * @return The content for the specified key.

      *

      * @exception ResourcesException if an error occurs retrieving or

      *  returning the requested content

      * @exception ResourcesKeyException if the no value for the specified

      *  key was found, and <code>isReturnNull()</code> returns

      *  <code>false</code>

      */

     public Object getObject(String key, Locale locale) {

         if (getLog().isTraceEnabled()) {

             getLog().trace("Retrieving message for key '" + key + "' and locale '"

                       + locale + "'");

         }

         if (locale == null) {

             locale = defaultLocale;

         }

         // Prepare local variables we will need

         List list = getLocaleList(locale);

         int n = list.size();

         // Search through the Locale hierarchy for this resource key

         for (int i = 0; i < n; i++) {

             Map map = getLocaleMap((Locale) list.get(i));

             if (map.containsKey(key)) {

                 Object object  = map.get(key);

                 if (getLog().isTraceEnabled()) {

                     getLog().trace("Retrieved object for key '" + key + 

                                    "' and locale '" + locale +

                                    "' is '" + object + "'");

                 }

                 return object;

             }

         }

         if (getLog().isTraceEnabled()) {

             getLog().trace("No message found for key '" + key + 

                            "' and locale '" + locale + "'");

         }

         // No value for this key was located in the entire hierarchy

         if (isReturnNull()) {

             return (null);

         } else {

             throw new ResourcesKeyException(key);

         }

     }

     // ------------------------------------------------------ Lifecycle Methods

     /**

      * <p>This method must be called when the manager of this resource

      * decides that it's no longer needed.  After this method is called,

      * no further calls to any of the <code>getXxx()</code> methods are

      * allowed.</p>

      *

      * @exception ResourcesException if an error occurs during finalization

      */

     public void destroy() {

         synchronized (lists) {

             lists.clear();

         }

         synchronized (maps) {

             maps.clear();

         }

     }

     // ------------------------------------------------------ Protected Methods

     /**

      * <p>Return a <code>List</code> of Locales that should be searched

      * when locating resources for the specified Locale.  The returned

      * list will start with the specified Locale itself, followed by Locales

      * that do not specify variant, country, or language modifiers.  For

      * example, if you pass in a Locale for the <code>en_US_POSIX</code>

      * combination, the returned list will have Locale instances for

      * the following country/language/variant combinations:</p>

      * <ul>

      * <li><code>en_US_POSIX</code></li>

      * <li><code>en_US</code></li>

      * <li><code>en</code></li>

      * <li>(zero-length country, language, and variant)</li>

      * </ul>

      *

      * <p>The search order calculated by this method makes it easy for

      * {@link org.apache.commons.resources.Resources} implementations to implement hierarchical search

      * strategies similar to that employed by the standard Java class

      * <code>java.util.ResourceBundle</code>.</p>

      *

      * @param locale Locale on which to base the list calculation

      * @return A List of locales.

      */

     protected List getLocaleList(Locale locale) {

         synchronized (lists) {

             // Optimized lookup of any previously cached Map for this Locale

             List list = (List) lists.get(locale);

             if (list != null) {

                 return (list);

             }

             // Calculate, cache, and return the list for this Locale

             list = new ArrayList();

             String language = locale.getLanguage();

             int languageLength = language.length();

             String country = locale.getCountry();

             int countryLength = country.length();

             String variant = locale.getVariant();

             int variantLength = variant.length();

             list.add(locale);

             if (variantLength > 0) {

                 list.add(new Locale(language, country, ""));

             }

             if ((countryLength > 0) && (languageLength > 0)) {

                 list.add(new Locale(language, "", ""));

             }

             if ((languageLength > 0) || (countryLength > 0)) {

                 list.add(new Locale("", "", ""));

             }

             lists.put(locale, list);

             return (list);

         }

     }

     /**

      * <p>Return the <code>Map</code> to be used to resolve name-value

      * mappings for the specified <code>Locale</code>.  Caching is utilized

      * to ensure that a call to <code>getLocaleMap(base,locale)</code>

      * occurs only once per <code>Locale</code>.</p>

      *

      * @param locale Locale for which to return a name-value mappings Map

      * @return A name-value Map for the specified locale.

      */

     protected Map getLocaleMap(Locale locale) {

         synchronized (maps) {

             // Optimized lookup of any previously cached Map for this Locale

             Map map = (Map) maps.get(locale);

             if (map != null) {

                 return (map);

             }

             // Calculate, cache, and return the map for this Locale

             map = getLocaleMap(base, locale);

             maps.put(locale, map);

             return (map);

         }

     }

     /**

      * <p>Return a <code>Map</code> containing the name-value mappings for

      * the specified base URL and requested <code>Locale</code>, if there

      * are any.  If there are no defined mappings for the specified

      * <code>Locale</code>, return an empty <code>Map</code> instead.</p>

      *

      * <p>Concrete subclasses must override this method to perform the

      * appropriate lookup.  A typical implementation will construct an

      * absolute URL based on the specified base URL and <code>Locale</code>,

      * retrieve the specified resource file (if any), and parse it into

      * a <code>Map</code> structure.</p>

      *

      * <p>Caching of previously retrieved <code>Map</code>s (if any) should

      * be performed by callers of this method.  Therefore, this method should

      * always attempt to retrieve the specified resource and load it

      * appropriately.</p>

      *

      * @param baseUrl Base URL of the resource files for this 

      * {@link org.apache.commons.resources.Resources} instance

      * @param locale <code>Locale</code> for which name-value mappings

      *  are requested

      * @return A name-value Map for the specified URL and locale.

      */

     protected abstract Map getLocaleMap(String baseUrl, Locale locale);

     /**

      * <p>Return the <code>Locale</code>-specific suffix for the specified

      * <code>Locale</code>.  If the specified <code>Locale</code> has

      * zero-length language and country components, the returned suffix

      * will also have zero length.  Otherwise, it will contain an

      * underscore character followed by the non-zero-length language,

      * country, and variant properties (separated by underscore characters).

      *

      * @param locale <code>Locale</code> for which a suffix string

      *  is requested

      * @return The locale specific suffix.

      */

     protected String getLocaleSuffix(Locale locale) {

         if (locale == null) {

             locale = defaultLocale;

         }

         String language = locale.getLanguage();

         if (language == null) {

             language = "";

         }

         String country = locale.getCountry();

         if (country == null) {

             country = "";

         }

         if ((language.length() < 1) && (country.length() < 1)) {

             return ("");

         }

         StringBuffer sb = new StringBuffer();

         if (language.length() > 0) {

             sb.append('_');

             sb.append(language.toLowerCase());

         }

         if (country.length() > 0) {

             sb.append('_');

             sb.append(country.toUpperCase());

         }

         String variant = locale.getVariant();

         if ((variant != null) && (variant.length() > 0)) {

             sb.append('_');

             sb.append(variant);

         }

         return (sb.toString());

     }

     /**

      * Accessor method for Log instance.

      *

      * The Log instance variable is transient and

      * accessing it through this method ensures it

      * is re-initialized when this instance is

      * de-serialized.

      *

      * @return The Log instance.

      */

     private Log getLog() {

         if (log == null) {

             log =  LogFactory.getLog(CollectionResourcesBase.class);

         }

         return log;

     }

 }