/*
    * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
    *
    * 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 de.smartics.properties.spi.core.metadata.comment;
  
  import java.io.BufferedInputStream;
  import java.io.IOException;
  import java.io.InputStream;
  import java.util.List;
  import java.util.Locale;
  
  import org.apache.commons.io.IOUtils;
  import org.jdom.Document;
  import org.jdom.Element;
  import org.jdom.JDOMException;
  import org.jdom.Namespace;
  import org.jdom.input.SAXBuilder;
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  
  import de.smartics.properties.api.core.domain.PropertiesContext;
  import de.smartics.properties.api.core.domain.PropertyComment;
  import de.smartics.properties.api.core.domain.PropertyDescriptor;
  import de.smartics.properties.api.core.domain.PropertyValueComment;
  import de.smartics.util.lang.Arg;
  import de.smartics.util.lang.NullArgumentException;
  
  /**
   * Parses property comments for a property descriptors.
   */
  public final class PropertyCommentParser
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * Reference to the logger for this class.
     */
    private static final Logger LOG = LoggerFactory
        .getLogger(PropertyCommentParser.class);
  
    /**
     * The namespace of the XML files this parser can parse.
     */
    private static final Namespace PROPERTY_NS =
        Namespace
            .getNamespace("http://www.smartics.de/schema/projectdoc/doctype/property/1");
  
    // --- members --------------------------------------------------------------
  
    /**
     * The properties context to fetch information from the META-INF folder.
     */
    private final PropertiesContext context;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Default constructor.
     *
     * @param context the properties context to fetch information from the
     *          META-INF folder.
     * @throws NullArgumentException if {@code context} is <code>null</code>.
     */
    public PropertyCommentParser(final PropertiesContext context)
      throws NullArgumentException
    {
      this.context = Arg.checkNotNull("context", context);
    }
  
    // ****************************** Inner Classes *****************************
  
    // ********************************* Methods ********************************
  
    // --- init -----------------------------------------------------------------
  
    // --- get&set --------------------------------------------------------------
  
    // --- business -------------------------------------------------------------
  
    /**
     * Parses the comments for the given descriptor.
     *
     * @param descriptor the descriptor whose comments are requested to be parsed.
    * @param locale the locale to select the comments.
    * @return the comments for the given locale or the default comments, if the
    *         locale is not supported.
    */
   public PropertyComment parse(final PropertyDescriptor descriptor,
       final Locale locale)
   {
     final String path = context.createMetaInfPath(descriptor, locale);
     final ClassLoader loader = descriptor.getDeclaringType().getClassLoader(); // NOPMD
 
     InputStream input = null;
     try
     {
       final InputStream resource = loader.getResourceAsStream(path);
       if (resource != null)
       {
         input = new BufferedInputStream(resource);
         final PropertyComment comment = parse(path, input);
         return comment;
       }
       else
       {
         LOG.warn("No comments for property descriptor '{}' found: {}",
             descriptor, path);
       }
     }
     catch (final CommentException e)
     {
       LOG.warn("Cannot parse comments for property descriptor '{}': {}",
           descriptor, e);
     }
     finally
     {
       IOUtils.closeQuietly(input);
     }
 
     return PropertyComment.EMPTY_COMMENT;
   }
 
   private PropertyComment parse(final String systemId, final InputStream input)
     throws CommentException
   {
     try
     {
       final SAXBuilder parser = new SAXBuilder();
       final Document document = parser.build(input, systemId);
 
       final PropertyComment.Builder builder = new PropertyComment.Builder();
 
       final Element rootNode = document.getRootElement();
 
       final String comment =
           rootNode.getChildTextNormalize("specification", PROPERTY_NS);
       final PropertyValueComment valueComment = parseValueComment(rootNode);
       builder.withText(comment).with(valueComment);
 
       return builder.build();
     }
     catch (final JDOMException e)
     {
       throw new CommentException(systemId, e);
     }
     catch (final IOException e)
     {
       throw new CommentException(systemId, e);
     }
   }
 
   @SuppressWarnings("unchecked")
   private PropertyValueComment parseValueComment(final Element rootNode)
   {
     final Element valueRange = rootNode.getChild("valueRange", PROPERTY_NS);
     if (valueRange == null)
     {
       return null;
     }
 
     final String summary =
         valueRange.getChildTextNormalize("summary", PROPERTY_NS);
     final PropertyValueComment comment = new PropertyValueComment(summary);
 
     final List<Element> elements =
         (List<Element>) valueRange.getChildren("element", PROPERTY_NS);
     for (final Element element : elements)
     {
       final String value = element.getChildTextNormalize("value", PROPERTY_NS);
       final String description =
           element.getChildTextNormalize("description", PROPERTY_NS);
       comment.addValueComment(value, description);
     }
 
     return comment;
   }
 
   // --- object basics --------------------------------------------------------
 
 }