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

import java.util.ArrayList;
import java.util.List;

import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

/**
 * @author Gregor Karlinger (mailto:gregor.karlinger@cio.gv.at) 
 */
public class DOMUtils
{
  /* ---------------------------------------------------------------------------------------------------- */
  
  /**
   * 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;
  }
}