/*
    * 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.projectdoc;
  
  import static de.smartics.util.lang.StaticAnalysis.UNCHECKED;
  
  import java.io.BufferedInputStream;
  import java.io.IOException;
  import java.io.InputStream;
  import java.util.List;
  import java.util.Locale;
  
  import javax.annotation.CheckForNull;
  
  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.jdom.output.XMLOutputter;
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  
  import de.smartics.properties.api.core.domain.DocumentMetaData;
  import de.smartics.properties.api.core.domain.ProjectdocMetaData;
  import de.smartics.properties.api.core.domain.PropertiesContext;
  import de.smartics.properties.api.core.domain.PropertyDescriptor;
  import de.smartics.properties.spi.core.metadata.projectdoc.ProjectdocAnnotationCollector.Defaults;
  import de.smartics.util.lang.Arg;
  
  /**
   * Parses projectdoc information from property XML descriptors.
   */
  public abstract class ProjectdocMetaDataParser
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * Reference to the logger for this class.
     */
    private static final Logger LOG = LoggerFactory
        .getLogger(ProjectdocMetaDataParser.class);
  
    // --- members --------------------------------------------------------------
  
    /**
     * The properties context to fetch information from the META-INF folder.
     */
    protected final PropertiesContext context;
  
    /**
     * The metadata defaults to use.
     */
    protected final Defaults defaults;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Convenience constructor without defaults.
     *
     * @param context the properties context to fetch information from the
     *          META-INF folder.
     * @throws NullPointerException if {@code context} is <code>null</code>.
     */
    protected ProjectdocMetaDataParser(final PropertiesContext context)
      throws NullPointerException
    {
      this(context, null);
    }
  
    /**
     * Default constructor.
     *
     * @param context the properties context to fetch information from the
     *          META-INF folder.
     * @param defaults the metadata defaults to use.
     * @throws NullPointerException if {@code context} is <code>null</code>.
     */
    protected ProjectdocMetaDataParser(final PropertiesContext context,
        final Defaults defaults) throws NullPointerException
    {
     this.context = Arg.checkNotNull("context", context);
     this.defaults = defaults;
   }
 
   // ****************************** Inner Classes *****************************
 
   /**
    * Provide access to information relevant for parsing and storing the parsed
    * information.
    */
   public final class ParserContext
   {
 
     // ******************************** Fields ********************************
 
     // --- constants ----------------------------------------------------------
 
     // --- members ------------------------------------------------------------
 
     /**
      * The descriptor whose comments are requested to be parsed.
      */
     private final PropertyDescriptor descriptor;
 
     /**
      * The locale to select the comments.
      */
     private final Locale locale;
 
     /**
      * The identifier of the document.
      */
     private final String systemId;
 
     /**
      * The parsed document to extract information from.
      */
     private final Document document;
 
     /**
      * The container where the parsed information is put to. You may safely cast
      * this instance to the type that has been passed to
      * {@link #parseBase(PropertyDescriptor, Locale, ProjectdocMetaData)}.
      */
     private final ProjectdocMetaData metaData;
 
     // ***************************** Initializer ******************************
 
     // ***************************** Constructors *****************************
 
     private ParserContext(final PropertyDescriptor descriptor,
         final Locale locale, final String systemId, final Document document,
         final ProjectdocMetaData metaData)
     {
       this.descriptor = descriptor;
       this.locale = locale;
       this.systemId = systemId;
       this.document = document;
       this.metaData = metaData;
     }
 
     // ***************************** Inner Classes ****************************
 
     // ******************************** Methods *******************************
 
     // --- init ---------------------------------------------------------------
 
     // --- get&set ------------------------------------------------------------
 
     /**
      * Returns the descriptor whose comments are requested to be parsed.
      *
      * @return the descriptor whose comments are requested to be parsed.
      */
     public PropertyDescriptor getDescriptor()
     {
       return descriptor;
     }
 
     /**
      * Returns the locale to select the comments.
      *
      * @return the locale to select the comments.
      */
     public Locale getLocale()
     {
       return locale;
     }
 
     /**
      * Returns the identifier of the document.
      *
      * @return the identifier of the document.
      */
     public String getSystemId()
     {
       return systemId;
     }
 
     /**
      * Returns the parsed document to extract information from.
      *
      * @return the parsed document to extract information from.
      */
     public Document getDocument()
     {
       return document;
     }
 
     /**
      * Returns the container where the parsed information is put to. You may
      * safely cast this instance to the type that has been passed to
      * {@link #parseBase(PropertyDescriptor,Locale,ProjectdocMetaData)}.
      *
      * @return the container where the parsed information is put to.
      */
     public ProjectdocMetaData getMetaData()
     {
       return metaData;
     }
 
     // --- business -----------------------------------------------------------
 
     // --- object basics ------------------------------------------------------
   }
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- get&set --------------------------------------------------------------
 
   // --- business -------------------------------------------------------------
 
   /**
    * Parses the comments for the given descriptor.
    * <p>
    * This method is overridden by subclasses to return their specific
    * implementation of the {@link DocumentMetaData}.
    * </p>
    *
    * @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. May be <code>null</code> if no information
    *         is provided.
    */
   @CheckForNull
   public ProjectdocMetaData parse(final PropertyDescriptor descriptor,
       final Locale locale)
   {
     try
     {
       final ProjectdocMetaData metaData = new ProjectdocMetaData();
       parseBase(descriptor, locale, metaData);
       return metaData;
     }
     catch (final MetaDataException e)
     {
       LOG.warn("Cannot parse meta data for property descriptor '{}': {}",
           descriptor, e);
       return null;
     }
   }
 
   /**
    * 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.
    * @param metaData the container where the parsed information is put to.
    * @throws MetaDataException if the meta data cannot be read.
    */
   protected final void parseBase(final PropertyDescriptor descriptor,
       final Locale locale, final ProjectdocMetaData metaData)
     throws MetaDataException
   {
     final String path = calcPath(descriptor, locale);
 
     final ClassLoader loader = descriptor.getDeclaringType().getClassLoader();
 
     InputStream input = null;
     try
     {
       final InputStream resource = load(path, loader);
       if (resource != null)
       {
         input = new BufferedInputStream(resource);
         parse(descriptor, path, locale, input, metaData);
       }
       else
       {
         throw new MetaDataException(path);
       }
     }
     finally
     {
       IOUtils.closeQuietly(input);
     }
   }
 
   /**
    * Calculates the path to a resource to be parsed.
    *
    * @param descriptor the descriptor to the resource.
    * @param locale the requested locale.
    * @return the path to the resource.
    */
   protected abstract String calcPath(final PropertyDescriptor descriptor,
       final Locale locale);
 
   private InputStream load(final String path, final ClassLoader loader)
   {
     InputStream input = loader.getResourceAsStream(path);
     if (input == null)
     {
       input = loader.getResourceAsStream('/' + path);
     }
     return input;
   }
 
   private DocumentMetaData parse(final PropertyDescriptor descriptor,
       final String systemId, final Locale locale, final InputStream input,
       final ProjectdocMetaData metaData) throws MetaDataException
   {
     try
     {
       final SAXBuilder parser = new SAXBuilder();
       final Document document = parser.build(input, systemId);
 
       final Element rootNode = document.getRootElement();
       addIdInfo(metaData, rootNode);
       addFiling(metaData, rootNode);
       addDescription(metaData, rootNode);
 
       final ParserContext context =
           new ParserContext(descriptor, locale, systemId, document, metaData);
       parseAdditional(context);
 
       return metaData;
     }
     catch (final JDOMException e)
     {
       throw new MetaDataException(systemId, e);
     }
     catch (final IOException e)
     {
       throw new MetaDataException(systemId, e);
     }
   }
 
   /**
    * The hook that allows to add further information.
    *
    * @param context to provide access to information relevant for parsing and
    *          storing the parsed information.
    * @throws MetaDataException if the meta data cannot be read.
    */
   protected void parseAdditional(final ParserContext context)
     throws MetaDataException
   {
   }
 
   private void addIdInfo(final ProjectdocMetaData metaData,
       final Element rootNode)
   {
     if (defaults != null)
     {
       metaData.setName(defaults.getName());
       metaData.setSpace(defaults.getSpace());
       metaData.setTitle(defaults.getTitle());
     }
 
     final Element identification = rootNode.getChild("identification", getNs());
     if (identification != null)
     {
       final String space =
           identification.getChildTextNormalize("space", getNs());
       metaData.setSpace(space);
       final String title =
           identification.getChildTextNormalize("title", getNs());
       metaData.setTitle(title);
     }
 
     final String name = rootNode.getChildTextNormalize("name", getNs());
     metaData.setName(name);
   }
 
   private void addFiling(final ProjectdocMetaData metaData,
       final Element rootNode)
   {
     final Element filing = rootNode.getChild("filing", getNs());
     if (filing != null)
     {
       addParents(metaData, filing);
       addCategories(metaData, filing);
       addTags(metaData, filing);
       setSortKey(metaData, filing);
     }
   }
 
   @SuppressWarnings(UNCHECKED)
   private void addParents(final ProjectdocMetaData metaData,
       final Element filing)
   {
     final Element parentsElement = filing.getChild("parents", getNs());
     if (parentsElement != null)
     {
       final List<Element> parents =
           parentsElement.getChildren("parent", getNs());
       for (final Element parent : parents)
       {
         final String parentName = parent.getTextNormalize();
         metaData.addParent(parentName);
       }
     }
   }
 
   @SuppressWarnings(UNCHECKED)
   private void addCategories(final ProjectdocMetaData metaData,
       final Element filing)
   {
     final Element categoriesElement = filing.getChild("categories", getNs());
     if (categoriesElement != null)
     {
       final List<Element> categories =
           categoriesElement.getChildren("category", getNs());
       for (final Element category : categories)
       {
         final String categoryName = category.getTextNormalize();
         metaData.addCategory(categoryName);
       }
     }
   }
 
   @SuppressWarnings(UNCHECKED)
   private void addTags(final ProjectdocMetaData metaData, final Element filing)
   {
     final Element tagsElement = filing.getChild("tags", getNs());
     if (tagsElement != null)
     {
       final List<Element> tags = tagsElement.getChildren("tag", getNs());
       for (final Element tag : tags)
       {
         final String tagName = tag.getTextNormalize();
         metaData.addTag(tagName);
       }
     }
   }
 
   private void setSortKey(final ProjectdocMetaData metaData,
       final Element filing)
   {
     final String sortKey = filing.getChildTextNormalize("sortKey", getNs());
     metaData.setSortKey(sortKey);
   }
 
   @SuppressWarnings(UNCHECKED)
   private void addDescription(final ProjectdocMetaData metaData,
       final Element rootNode)
   {
     final Element description = rootNode.getChild("description", getNs());
     if (description != null)
     {
       final Element audienceElement = description.getChild("audience", getNs());
       if (audienceElement != null)
       {
         final List<Element> members =
             audienceElement.getChildren("member", getNs());
         for (final Element member : members)
         {
           final String memberName = member.getTextNormalize();
           metaData.addAudience(memberName);
         }
       }
 
       final Element shortDescriptionElement =
           description.getChild("shortDescription", getNs());
       final String shortDescription = toString(shortDescriptionElement);
       metaData.setShortDescription(shortDescription);
 
       final Element summaryElement = description.getChild("summary", getNs());
       final String summary = toString(summaryElement);
       metaData.setSummary(summary);
 
       final Element notesElement = description.getChild("notes", getNs());
       final String notes = toString(notesElement);
       metaData.addNote(notes);
     }
   }
 
   /**
    * Returns the namespace of the elements parsed by this parser.
    *
    * @return the namespace of the elements parsed by this parser.
    */
   protected abstract Namespace getNs();
 
   private static String toString(final Element element)
   {
     final XMLOutputter outp = new XMLOutputter();
     final StringBuilder buffer = new StringBuilder(1024);
 
     final List<?> children = element.getContent();
     final String string = outp.outputString(children);
     buffer.append(string);
 
     return buffer.toString().trim();
   }
 
   // --- object basics --------------------------------------------------------
 
 }