/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (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.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2001 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.util;

import org.w3c.dom.*;

/**
 * A class which wraps around the DOM <CODE>Element</CODE> class, providing some
 * additional functionality.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 * @see org.w3c.dom.Element
 */
public class DOMElementHelper
{
  /*--------------------------------------------------------------------------------
   * Attributes
   *--------------------------------------------------------------------------------
   */

  private Element elt;  // element housed by this helper class

  /*--------------------------------------------------------------------------------
   * Constructor
   *--------------------------------------------------------------------------------
   */

  /**
   * Constructs a new <CODE>DOMElementHelper</CODE> to wrap a specific <CODE>Element</CODE>.
   *
   * @param elt The <CODE>Element</CODE> to be wrapped.
   */
  public DOMElementHelper(Element elt)
  {
    this.elt = elt;

  } // end constructor

  /*--------------------------------------------------------------------------------
   * Internal static operations
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns the content of all text nodes underneath a specified <CODE>Element</CODE>, concatenated
   * together into a single string.
   *
   * @param e The <CODE>Element</CODE> to extract text from.
   * @return The text content under this <CODE>Element</CODE> node.  If the specified <CODE>Element</CODE>
   *         has no text nodes underneath it, returns <CODE>null.</CODE>
   */
  private static String getTextOfElement(Element e)
  {
    NodeList kids = e.getChildNodes();
    if (kids==null)
      return null;  // no text?

    StringBuffer b = null;
    for (int i=0; i<kids.getLength(); i++)
    { // look for an ELEMENT_NODE node matching the desired name
      Node t = kids.item(i);
      if ((t.getNodeType()==Node.TEXT_NODE) || (t.getNodeType()==Node.CDATA_SECTION_NODE))
      { // append to the string under construction
	if (b==null)
	  b = new StringBuffer();
	else
	  b.append(' ');
	b.append(t.getNodeValue());

      } // end if

    } // end for

    if (b==null)
      return null;  // no TEXT nodes
    else
      return b.toString();  // return the concatenation
    
  } // end getTextOfElement

  /*--------------------------------------------------------------------------------
   * External operations
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns the <CODE>Element</CODE> wrapped by this object.
   *
   * @return See above.
   */
  public Element getElement()
  {
    return elt;

  } // end getElement

  /**
   * Searches for the first sub-element of the wrapped <CODE>Element</CODE> with the given name.
   *
   * @param name Name of the sub-element to search for.
   * @return The first sub-element of the wrapped <CODE>Element</CODE> with the specified name.
   *         If the <CODE>Element</CODE> has no child <CODE>Elements</CODE> with the given name,
   *         the method returns <CODE>null</CODE>.
   */
  public Element getSubElement(String name)
  {
    NodeList kids = elt.getChildNodes();
    if (kids==null)
      return null;  // no children?
    for (int i=0; i<kids.getLength(); i++)
    { // look for an ELEMENT_NODE node matching the desired name
      Node t = kids.item(i);
      if ((t.getNodeType()==Node.ELEMENT_NODE) && (t.getNodeName().equals(name)))
	return (Element)t;

    } // end for

    return null;  // not found

  } // end getSubElement

  /**
   * Returns the content of all text nodes underneath the wrapped <CODE>Element</CODE>, concatenated
   * together into a single string.
   *
   * @return The text content under the wrapped <CODE>Element</CODE> node.  If the wrapped <CODE>Element</CODE>
   *         has not text nodes underneath it, returns <CODE>null.</CODE>
   */
  public String getElementText()
  {
    return getTextOfElement(elt);

  } // end getElementText

  /**
   * Returns the content of all text nodes underneath the first sub-element of the wrapped
   * <CODE>Element</CODE>, with the given name, concatenated together into a single string.
   *
   * @param name The name of the sub-element to search for.
   * @return The text content under the specified sub-element of the wrapped <CODE>Element</CODE> node.
   *         If the wrapped <CODE>Element</CODE> does not have a sub-element with the given name, or
   *         that sub-element has no text nodes underneath it, returns <CODE>null.</CODE>
   */
  public String getSubElementText(String name)
  {
    Element se = getSubElement(name);
    if (se==null)
      return null;
    else
      return getTextOfElement(se);

  } // end getSubElementText

  /**
   * Determines whether the wrapped <CODE>Element</CODE> has a sub-element with the given name.
   *
   * @param name Name of the sub-element to search for.
   * @return <CODE>true</CODE> if the wrapped <CODE>Element</CODE> has a sub-element with the
   *         specified name, <CODE>false</CODE> if not.
   */
  public boolean hasChildElement(String name)
  {
    Element tmp = getSubElement(name);
    return (tmp==null) ? false : true;

  } // end hasChildElement

  /**
   * Determines whether the wrapped <CODE>Element</CODE> has an attribute with the given name.
   *
   * @param name Name of the attribute to search for.
   * @return <CODE>true</CODE> if the wrapped <CODE>Element</CODE> has an attribute with the
   *         specified name, <CODE>false</CODE> if not.
   */
  public boolean hasAttribute(String name)
  {
    return !(StringUtil.isStringEmpty(elt.getAttribute(name)));

  } // end hasAttribute

  /**
   * Returns the value of a specified attribute of the wrapped <CODE>Element</CODE>, expressed as
   * an integer.
   *
   * @param name Name of the attribute to search for.
   * @return An <CODE>Integer</CODE> object containing the value of the specified attribute.  If
   *         the wrapped <CODE>Element</CODE> has no such attribute, or if the attribute's value
   *         cannot be expressed as an integer, returns <CODE>null</CODE>.
   */
  public Integer getAttributeInt(String name)
  {
    String tmp = elt.getAttribute(name);
    if (StringUtil.isStringEmpty(tmp))
      return null;
    try
    { // convert to an Integer
      return new Integer(tmp);

    } // end try
    catch (NumberFormatException nfe)
    { // return a null value on error
      return null;

    } // end catch

  } // end getAttributeInt

} // end DOMElementHelper