/*

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

 }