/*

  * $Id: XMLResources.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.HashMap;

 import java.util.Locale;

 import java.util.Map;

 import org.apache.commons.digester.Digester;

 import org.apache.commons.logging.Log;

 import org.apache.commons.logging.LogFactory;

 import org.xml.sax.SAXException;

 /**

  * <p>Concrete implementation of 

  * {@link org.apache.commons.resources.Resources} that wraps a family

  * (one per <code>Locale</code> of XML documents 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

  * XML documents 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 XML document 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.xml</code>, and the default

  * resources would be stored in

  * <code>http://localhost/foo/Bar.xml</code>.</p>

  *

  * <p>The required structure of the XML documents is very simple:</p>

  * <ul>

  * <li>The top level element must be <code>&lt;resources&gt;</code>.</li>

  * <li>Each name-value pair is represented by a nested

  *     <code>&lt;resource&gt;</code> element.</li>

  * <li>For each <code>&lt;resource&gt;</code> element, the <code>id</code>

  *     attribute contains the resource key, and the body contains a

  *     string representation of the value.</li>

  * </ul>

  */

 public class XMLResources extends CollectionResourcesBase {

     /**

      * <p>The <code>Log</code> instance for this class.</p>

      */

     private transient Log log = LogFactory.getLog(XMLResources.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 XMLResources(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 + "'");

         }

         Map map = new HashMap();

         String name = baseUrl + getLocaleSuffix(locale) + ".xml";

         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();

             // Create and configure a new Digester instance

             if (getLog().isTraceEnabled()) {

                 getLog().trace("Creating Digester instance");

             }

             Digester digester = new Digester();

             digester.setNamespaceAware(false);

             digester.setValidating(false);

             digester.push(map);

             digester.addCallMethod("resources/resource", "put", 2,

                                    new String[] { "java.lang.Object",

                                                   "java.lang.Object" });

             digester.addCallParam("resources/resource", 0, "id");

             digester.addCallParam("resources/resource", 1);

             // Parse the input stream and populate the name-value mappings map

             if (getLog().isTraceEnabled()) {

                 getLog().trace("Parsing input resource");

             }

             digester.parse(stream);

         } catch (FileNotFoundException e) {

             // Log and swallow this exception

             if (getLog().isDebugEnabled()) {

                 getLog().debug("No resources for locale '" + locale +

                           "' from base '" + baseUrl + "'");

             }

             map.clear();

         } catch (IOException e) {

             // Log and swallow this exception

             getLog().warn("IOException loading locale '" + locale +

                      "' from base '" + baseUrl + "'", e);

             map.clear();

         } catch (SAXException e) {

             // Log and swallow this exception

             getLog().warn("SAXException loading locale '" + locale +

                      "' from base '" + baseUrl + "'", e);

             map.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) map

         return (map);

     }

     /**

      * 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(XMLResources.class);

         }

         return log;

     }

 }