/*

  * $Id: PropertyResources.java 348371 2005-11-23 04:56:51Z niallp $

  * $Revision: 348371 $

  * $Date: 2005-11-23 04:56:51 +0000 (Wed, 23 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;

     }

 }