/*
    * $Id: PropertyResources.java 348371 2005-11-23 04:56:51Z niallp $
    * $Revision: 348371 $
    * $Date: 2005-11-22 23:56:51 -0500 (Tue, 22 Nov 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.io.FileNotFoundException;
  import java.io.IOException;
  import java.io.InputStream;
  import java.net.URL;
  import java.util.Locale;
  import java.util.Map;
  import java.util.Properties;
  
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogFactory;
  
  /***
   * <p>Concrete implementation of 
   * {@link org.apache.commons.resources.Resources} that wraps a family
   * (one per <code>Locale</code>) of properties files that share a base URL
   * and have name suffixes reflecting the <code>Locale</code> for which
   * the document's messages apply.  Resources are looked up in a hierarchy
   * of properties files in a manner identical to that performed by
   * <code>java.util.ResourceBundle.getBundle().</code>.</p>
   *
   * <p>The base URL passed to our constructor must contain the base name
   * of the properties file family.
   * For example, if the configuration URL is passed as
   * <code>http://localhost/foo/Bar</code>, the resources for the
   * <code>en_US</code> Locale would be stored under URL
   * <code>http://localhost/foo/Bar_en_US.properties</code>, and the default
   * resources would be stored in
   * <code>http://localhost/foo/Bar.properties</code>.</p>
   */
  public class PropertyResources extends CollectionResourcesBase {
  
      /***
       * <p>The <code>Log</code> instance for this class.</p>
       */
      private transient Log log = LogFactory.getLog(PropertyResources.class);
  
      // ----------------------------------------------------------- Constructors
  
      /***
       * <p>Create a new 
       * {@link org.apache.commons.resources.Resources} instance with the specified
       * logical name and base resource URL.</p>
       *
       * @param name Logical name of the new instance
       * @param base Base URL of the family of properties files that contain
       *  the resource keys and values
       */
      public PropertyResources(String name, String base) {
          super(name, base);
      }
  
  
      // ------------------------------------------------------ Protected Methods
  
  
      /***
       * <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 Map getLocaleMap(String baseUrl, Locale locale) {
 
         if (getLog().isDebugEnabled()) {
             getLog().debug("Loading locale '" + locale + "' resources from base '" +
                     baseUrl + "'");
         }
 
         Properties props = new Properties();
         String name = baseUrl + getLocaleSuffix(locale) + ".properties";
         InputStream stream = null;
 
         try {
 
             // Open an input stream to the URL for this locale (if any)
             if (getLog().isTraceEnabled()) {
                 getLog().trace("Absolute URL is '" + name + "'");
             }
             URL url = new URL(name);
             stream = url.openStream();
 
             // Parse the input stream and populate the name-value mappings map
             if (getLog().isTraceEnabled()) {
                 getLog().trace("Parsing input resource");
             }
             props.load(stream);
 
         } catch (FileNotFoundException e) {
 
             // Log and swallow this exception
             if (getLog().isDebugEnabled()) {
                 getLog().debug("No resources for locale '" + locale +
                           "' from base '" + baseUrl + "'");
             }
             props.clear();
 
         } catch (IOException e) {
 
             getLog().warn("IOException loading locale '" + locale +
                      "' from base '" + baseUrl + "'", e);
             props.clear();
 
         } finally {
 
             // Close the input stream that was opened earlier
             if (stream != null) {
                 try {
                     stream.close();
                 } catch (IOException e) {
                     getLog().error("Error closing stream.", e);
                 }
                 stream = null;
             }
 
         }
 
         // Return the populated (or empty) properties
         return (props);
 
     }
 
 
     /***
      * 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(PropertyResources.class);
         }
         return log;
     }
 
 }