source: other-projects/trunk/gs3-webservices-democlient/src/GS3DemoClient/org/greenstone/gs3client/data/ParseUtil.java@ 15222

/**
 *#########################################################################
 * ParseUtil.java - part of the demo-client for Greenstone 3, of the 
 * Greenstone digital library suite from the New Zealand Digital Library 
 * Project at the  * University of Waikato, New Zealand.
 * <BR><BR>
 * Copyright (C) 2008 New Zealand Digital Library Project
 * <BR><BR>
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * <BR><BR>
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *########################################################################
 */

package org.greenstone.gs3client.data;

import java.util.HashMap;
import java.util.Vector;

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


// Perhaps can use GSXML.extractParams() for at least half of this and 
// GSXML.getChildByTagName() for the other? 
// -> No, extractParams() only extracts <ParamList> child elements <param>s. 
// Then it returns a hashmap of (name, value) pairs.
// And getChildByTagName returns any Node, not the Element we want.
/** 
 *  Some useful, general response XML message parsing functions 
 *  for the JavaClient's data classes.
 *  @author ak19
*/
public class ParseUtil {
    /** 
     * @param tag is the XML element from which the body text value will 
     * be extracted.
     * @return the bodyText nested within the tag element, if any. Otherwise, this 
     * method returns empty String. */
    public static String getBodyTextValue(Element tag) {
        Node textNode = tag.getFirstChild();
        return (textNode == null) ? "" : textNode.getNodeValue();
    }
    
    /**
     * @param el is the element whose child elements are returned.
     * @param childrenName is the name of the child elements to be extracted and
     * returned.
     * @return a vector containing all child elements of parent that are 
     * called childrenName. Returns null if there are no such child elements.
    */
    public static Vector getAllChildElementsCalled(Element el, 
            String childrenName) 
    {
        Vector v = null;
        if(el.hasChildNodes()) {
            NodeList nl = el.getChildNodes();
            // Get only those of its direct children that are called 
            // <childrenName>
            v = new Vector(nl.getLength());
            for(int i = 0; i < nl.getLength(); i++) {
                Node n = nl.item(i);
                // For Element Nodes, getNodeName() returns the tag name,
                // and it *never* returns null for *any* Node type
                if(n.getNodeName().equals(childrenName)) {
                    v.add((Element)n);
                }   
            } 
        }
        return v;
    }
    
    /**
     * Given an xml element ('parent'), it looks through its direct children 
     * to find the &lt;listElementName&gt; tag and extracts each child called
     * &lt;childElementName&gt; element from it. These are all added into a Vector
     * which is returned.
     * @param parent is the XML element from which the specified descendant 
     * elements are identified and returned.
     * @param listElementName is the name of the child element of parent that we
     * are looking for, whose child elements will be returned.  
     * @return a vector of Element items, all children &lt;childelementName&gt; of   
     * the <b>first</b> &lt;listElementName&gt; child of parameter called parent.
    */
    public static Vector getListElementsAsArray(Element parent,
            String listElementName, String childElementName)
    {
        NodeList nl = parent.getElementsByTagName(listElementName);
        if(nl.getLength() > 0) {
             // ensure <listELementName> has children, if so, get its children 
             Element eList = (Element)nl.item(0); // first <listElementName>
             return getAllChildElementsCalled(eList, childElementName);
        }
        return null;
    }
    
    /**
     *  Method that returns the first child element of parent whose tagname is 
     *  childElementName.
     *  @param parent is the element whose child element (if called 
     *  childElementName) is returned.
     *  @param childElementName is the name of the child element to look for in
     *  parent. 
     *  @return the first *child* element of &lt;parent&gt; that is 
     *  &lt;childElementName&gt;. Null is returned if there are none. 
    */
    public static Element getFirstChildElementCalled(Element parent,
            String childElementName)
    {
        // find all <childElementName>s, children of parent
        NodeList nl = parent.getChildNodes();
        // Find and return first <childElementName>, if any
        for(int i = 0; i < nl.getLength(); i++) {
            Node n = nl.item(i);
            if(n.getNodeName().equals(childElementName))    
                // now we know n is an Element *and* is the one we want
                return (Element)n; 
        }
        return null;
    }
    
    /**
     *  Method that returns the first descendant element of parent whose tagname 
     *  is descElementName.
     *  @param parent is the element whose descendant element (if called 
     *  descElementName) is returned.
     *  @param descElementName is the name of the descendant element to look for
     *  in parent.
     *  @return the first <b>descendant</b> element of &lt;parent&gt; that is 
     *  &lt;descElementName&gt;. Null is returned if there are none. 
    */
    public static Element getFirstDescElementCalled(Element parent,
            String descElementName)
    {
        // find all <descElementName>s
        NodeList nl = parent.getElementsByTagName(descElementName);
        if(nl.getLength() > 0) // then return first <descElementName>
             return (Element)nl.item(0); // we know it's an element 
        return null; // else
    }
    
    /** 
     * Given an Element &lt;parentEl&gt;, finds all direct child elements called
     * &lt;elName&gt; that have an attribute named attrName:
     * &lt;elName attrName=value&gt;bodytext&lt;/elName&gt;
     * This is particularly useful for extracting info for those cases where 
     * elName=&lt;displayItem&gt; and where the attrName is "name".
     * @param parentEl is the parent element whose children are searched
     * @param elName is the name to search for among the child elements of parentEl
     * @param attrName is the name of the attribute to look for in the child 
     * element (of parentEl) whose tag name is elName.
     * @return a Hashmap of all the (value, body) instances found.
    */
    public static HashMap getElementValuesForAttr(Element parentEl, 
            String elName, String attrName) 
    {
        HashMap map = new HashMap(10);
        NodeList nl = parentEl.getChildNodes();
        if(nl == null || nl.getLength() == 0)
            return map;
        for(int i = 0; i < nl.getLength(); i++) {
            Node n = nl.item(i); 
            // Look for all <elName> children of <parentEl>
            if(n.getNodeName().equals(elName)){ // processing all <elName>s
                // Retrieve value of all attributes named attrName in
                // <elName attrName=value>bodytext</elName>
                // and the body of the element
                Element e = (Element)n; // we now know it's an element and the
                                        // one we want
                if(e.hasAttribute(attrName)){
                    // Get the value for the attribute named attrName
                    // and put it as the key in a map entry
                    // The associated map entry's value is the *bodytext*
                    // of the element <elName>bodytext</elName>
                    String bodytext = e.hasChildNodes() ?
                        e.getFirstChild().getNodeValue() : "";
                    map.put(e.getAttribute(attrName), bodytext);
                }   
            }
        }
        return map;
    }
}