/*

  * 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 --------------------------------------------------------

 }