/*
 * Created on 28.11.2003
 *
 * (c) Stabsstelle IKT-Strategie des Bundes
 */
package at.gv.egovernment.moa.ss.erechtclient.util;

import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

import org.apache.xerces.parsers.DOMParser;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;

import at.gv.egovernment.moa.ss.erechtclient.init.XMLParserErrorHandler;


/**
 * @author Gregor Karlinger (mailto:gregor.karlinger@cio.gv.at) 
 */
public class DOMUtils
{
  private static final String SAX_NAMESPACES_FEATURE = "http://xml.org/sax/features/namespaces";
  private static final String XERCES_CREATE_ENTITY_REF_NODES_FEATURE =
    "http://apache.org/xml/features/dom/create-entity-ref-nodes";
  protected static final String XERCES_DEFER_NODE_EXPANSION_ =
    "http://apache.org/xml/features/dom/defer-node-expansion";

  /* ---------------------------------------------------------------------------------------------------- */
  
  /**
   * Gets the first text node of the specified element.
   * 
   * @param elem The element.
   *
   * @return the first text node of the specified element, or <code>null</code> if <code>element</code>
   *         equals <code>null</code>, or if the element has no text node.
   */
  public static String getText(Element elem)
  {
    if (elem == null) return null;
    NodeList childNodes = elem.getChildNodes();
    for (int i = 0; i < childNodes.getLength(); i++)
    {
      Node currNode = childNodes.item(i);
      if (currNode.getNodeType() == Node.TEXT_NODE) return currNode.getNodeValue();
    }
    return null;
  }

  /* ---------------------------------------------------------------------------------------------------- */
  
  /**
   * Gets the first text node of the specified child element from the specified parent element.
   * 
   * @param parent The parent.
   * 
   * @param childNS The namespace of the child element.
   * 
   * @param childLocName The local name of the child element.
   * 
   * @return the first text node of the specified child, or <code>null</code> if <code>parent</code> equals
   *         <code>null</code> or has no child element with the specified namespace and local name, or if 
   *         the child element has no text node.
   */
  public static String getChildText(Element parent, String childNS, String childLocName)
  {
    if (parent == null) return null;
    Element child = getChildElem(parent, childNS, childLocName);
    if (child == null) return null;
    return getText(child);
  }

  /* ---------------------------------------------------------------------------------------------------- */

  /**
   * Gets the first child element of the specified parent with the specified namspace and local name.
   * 
   * @param parent The parent.
   * 
   * @param childNS The namespace of the child element to be searched for.
   * 
   * @param childLocName The local name of the child element to be searched for.
   * 
   * @return the first child element as described above, or <code>null</code> if <code>parent</code> is
   *         null or has no child elements with for the specified namespace and local name.
   */
  public static Element getChildElem(Element parent, String childNS, String childLocName)
  {
    List childElems = getChildElems(parent, childNS, childLocName, true);
    return (childElems == null) ? null : (Element) childElems.get(0);
  }

  /* ---------------------------------------------------------------------------------------------------- */

  /**
   * Gets all or the first child element(s) of the specified parent with the specified namspace and local 
   * name.
   * 
   * @param parent The parent.
   * 
   * @param childNS The namespace of the child elements to be searched for.
   * 
   * @param childLocName The local name of the child elements to be searched for.
   * 
   * @param firstOnly Specifies wheter only the first or all child elements with the specified namespace and
   *                  local name should be returned.
   * 
   * @return a <code>java.util.List</code> with objects of type <code>org.w3c.dom.Element</code>; each 
   *         element in the list represents a child element as specified above. If <code>parent</code> 
   *         equals <code>null</code>, or if there are no child elements as specified above, <code>null
   *         </code> will be returned.
   */
  public static List getChildElems(Element parent, String childNS, String childLocName, boolean firstOnly)
  {
    if (parent == null) return null;

    ArrayList childElems = new ArrayList();
    NodeList childNodes = parent.getChildNodes();
    for (int i = 0; i < childNodes.getLength(); i++)
    {
      Node currNode = childNodes.item(i);
      if (currNode.getNodeType() == Node.ELEMENT_NODE)
      {
        Element currElem = (Element) currNode;
        if (childNS.equals(currElem.getNamespaceURI()) && childLocName.equals(currElem.getLocalName()))
        {
          childElems.add(currElem);
          if (firstOnly) break;
        }
      }
    }
    return (childElems.size() == 0) ? null : childElems;
  }

  /* ---------------------------------------------------------------------------------------------------- */

  public static Document parseWellFormed(InputStream is) throws Exception
  {
    DOMParser xmlParser = new DOMParser();
    try
    {
      xmlParser.setFeature(SAX_NAMESPACES_FEATURE, true);
      xmlParser.setFeature(XERCES_CREATE_ENTITY_REF_NODES_FEATURE, false);
      xmlParser.setFeature(XERCES_DEFER_NODE_EXPANSION_, false);
      xmlParser.setErrorHandler(new XMLParserErrorHandler(false, true, true));
    }
    catch (SAXException e)
    {
      String message = "Initialization of XML parser failed.";
      throw new Exception(message, e);
    }
    try
    {
      xmlParser.parse(new InputSource(is));
      return xmlParser.getDocument();
    }
    catch (Exception e)
    {
      String message = "Wellformed parsing failed.";
      throw new Exception(message, e);
    }
  }
}