/*
    * Copyright 2012 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.ci.config.utils;
  
  import java.io.ByteArrayOutputStream;
  import java.util.Iterator;
  
  import org.apache.commons.lang.StringUtils;
  import org.jdom.Content;
  import org.jdom.Document;
  import org.jdom.Element;
  import org.jdom.JDOMException;
  import org.jdom.output.XMLOutputter;
  
  import de.smartics.ci.config.hudson.HudsonConfigElement;
  import de.smartics.util.lang.Arguments;
  import de.smartics.util.lang.NullArgumentException;
  
  /**
   * Helper functions to deal with JDom instances.
   */
  public final class JDomUtils
  { // NOPMD
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    // --- members --------------------------------------------------------------
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Utility class pattern.
     */
    private JDomUtils()
    {
    }
  
    // ****************************** Inner Classes *****************************
  
    /**
     * Cursor to traverse XML elements for merging.
     */
    private static final class Cursor
    {
      /**
       * The reference to the current parent element to add new elements to.
       */
      private Element parent; // NOPMD
  
      /**
       * The iterator on the 'to be merged into target' structure.
       */
      private final Iterator<?> toBeMergedIterator;
  
      /**
       * The root element of the target structure.
       */
      private final Element targetRootElement; // NOPMD
  
      /**
       * The root element of the 'to be merged into target' structure.
       */
      private final Element rootElement;
  
      private Cursor(final Element target, final Element toBeMerged)
      {
        checkRootElementsMatch(target, toBeMerged);
  
        targetRootElement = target;
        rootElement = toBeMerged;
        parent = target;
        toBeMergedIterator = toBeMerged.getChildren().iterator();
      }
  
      private static void checkRootElementsMatch(final Element target,
          final Element toBeMerged)
      {
        Arguments.checkNotNull("target", target);
        Arguments.checkNotNull("toBeMerged", toBeMerged);
        final String targetName = target.getName();
        final String toBeMergedName = toBeMerged.getName();
        if (!targetName.equals(toBeMergedName))
        {
         throw new IllegalArgumentException(
             "The root element names of the XML subtrees to be merged do not"
                 + " match. Target is '" + targetName + "' and toBeMerged is '"
                 + toBeMergedName + "'.");
       }
     }
 
     private boolean hasNextToMerge()
     {
       return toBeMergedIterator.hasNext();
     }
 
     private Content nextSiblingMergeContent()
     {
       return (Content) toBeMergedIterator.next();
     }
   }
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- get&set --------------------------------------------------------------
 
   // --- business -------------------------------------------------------------
 
   /**
    * Merges the distinct information from the two documents.
    * <p>
    * Note that not the contents of the element is checked to determine if the
    * contents are equal. The merging algorithm simply checks the element names
    * and assumes that two elements are the same, if they have the same name and
    * are on the same level.
    * </p>
    *
    * @param target the document to add information, if missing.
    * @param toBeMerged the information to add to the {@code target}, if missing.
    * @throws NullArgumentException if either {@code target} or
    *           {@code toBeMerged} is <code>null</code>.
    * @throws JDOMException on any problem encountered while merging.
    */
   public static void merge(final Document target, final Document toBeMerged)
     throws NullArgumentException, JDOMException
   {
     Arguments.checkNotNull("target", target);
     Arguments.checkNotNull("toBeMerged", toBeMerged);
 
     merge(target.getRootElement(), toBeMerged.getRootElement());
   }
 
   /**
    * Merges the distinct information from the two elements.
    * <p>
    * Note that not the contents of the element is checked to determine if the
    * contents are equal. The merging algorithm simply checks the element names
    * and assumes that two elements are the same, if they have the same name and
    * are on the same level.
    * </p>
    *
    * @param target the element to add information, if missing.
    * @param toBeMerged the information to add to the {@code target}, if missing.
    * @throws JDOMException on any problem encountered while merging.
    */
   public static void merge(final Element target, final Element toBeMerged)
     throws JDOMException
   {
     final Cursor cursor = new Cursor(target, toBeMerged);
 
     if (target.getChildren().isEmpty())
     {
       if (cursor.hasNextToMerge())
       {
         fillWithMergeElements(cursor);
         return;
       }
       else
       {
         overwriteTextContent(target, toBeMerged);
       }
     }
 
     while (cursor.hasNextToMerge())
     {
       final Content content = cursor.nextSiblingMergeContent();
       if (content instanceof Element)
       {
         handleAsElement(cursor, content);
       }
     }
   }
 
   private static void fillWithMergeElements(final Cursor cursor)
   {
     while (cursor.hasNextToMerge())
     {
       final Content content = cursor.nextSiblingMergeContent();
       cursor.parent.addContent((Content) content.clone());
     }
   }
 
   private static void overwriteTextContent(final Element target,
       final Element toBeMerged)
   {
     final String textContent = toBeMerged.getText();
     if (StringUtils.isNotBlank(textContent))
     {
       target.setText(textContent);
     }
   }
 
   private static void handleAsElement(final Cursor cursor, final Content content)
     throws JDOMException
   {
     final Element element = (Element) content;
 
     final Element targetElement = findElementInTarget(cursor, element);
     final boolean exists = targetElement != null;
     if (exists)
     {
       merge(targetElement, element);
     }
     else
     {
       cursor.parent.addContent((Content) element.clone());
     }
   }
 
   private static Element findElementInTarget(final Cursor cursor,
       final Element element) throws JDOMException
   {
     final Element targetElement =
         HudsonConfigElement.findElement(cursor.rootElement, element,
             cursor.targetRootElement);
     return targetElement;
   }
 
   /**
    * Calculates the XPath for the given {@code element}.
    *
    * @param rootElement the root element to the element whose path is to be
    *          calculated. The returned XPath is relative to the element. May be
    *          <code>null</code> if a path from the document root is requested.
    * @param element the element relative to the {@code rootElement}.
    * @return the XPath relative to {@code rootElement} to the {@code element}.
    */
   public static String calcXPath(final Element rootElement,
       final Element element)
   {
     Arguments.checkNotNull("element", element);
 
     final StringBuilder buffer = new StringBuilder(32);
 
     buffer.append(element.getName());
     Element current = element;
     while ((current = current.getParentElement()) != rootElement) // NOPMD
     {
       buffer.insert(0, '/').insert(0, current.getName());
     }
 
     if (rootElement == null)
     {
       buffer.insert(0, '/');
     }
     return buffer.toString();
   }
 
   /**
    * Returns the string representation of the XML document.
    *
    * @param document the XML document to create its string representation.
    * @return the string representation of the XML document.
    */
   public static String toString(final Document document)
   {
     try
     {
       final ByteArrayOutputStream out = new ByteArrayOutputStream(1024);
 
       final XMLOutputter outp = new XMLOutputter();
       outp.output(document, out);
       final String string = out.toString("UTF-8");
       return string;
     }
     catch (final Exception e)
     {
       throw new IllegalStateException("Cannot stringify document.", e);
     }
   }
 
   // --- object basics --------------------------------------------------------
 
 }