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

/**
 *#########################################################################
 * NodeData.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.Iterator;
import java.util.Set;
import java.util.Map.Entry;

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

import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import org.greenstone.gs3client.data.ClassifierNodeData;
import org.greenstone.gsdl3.util.GSXML;

/** 
 * Abstract superclass NodeData can represent either a the information in
 * a &lt;classifierNode&gt; (stored in a ClassifierNodeData object) or in a
 * &lt;documentNode&gt; (stored in a DocumentNodeData object).
 * @author ak19 
*/
public abstract class NodeData {
    /** The unique nodeID identifying this documentNode or classificationNode */
    public final String nodeID;
    
    /** Since we are setting the descendents lazily (only setting the children
     * each time), we have a little flag to indicate whether this node has
     * any children. */
    public final boolean hasChildren;
    /** stores this NodeData's tag element: can be either 
     * &lt;documentNode&gt; or &lt;classifierNode&gt; */
    protected final Element nodeTag; 
    
    /** Map of the metadata (name, value) pairs of this document- 
     * or classifier-node */
    protected Map nodeMetadata = null;

    /** @return an array of the children of this NodeData, however such a
     * structure may be stored internally by a NodeData subclass. */
    public abstract NodeData[] getChildren();
    
    /** Constructor that extracts the nodeID value from the given nodeTag:
     * &lt;classifierNode nodeID = "x" /&gt; 
     * or &lt;documentNode nodeID = "x" /&gt; */
    public NodeData(Element nodeTag) {
        this.nodeTag = nodeTag; // store this node's tag information. Useful
                     // for when we are setting the children of this NodeData

        // We'd definitely have the nodeID attribute, but to be on the safe 
        // side, check it's there first:
        this.nodeID = nodeTag.hasAttribute(GSXML.NODE_ID_ATT) ?
        nodeTag.getAttribute(GSXML.NODE_ID_ATT) : "";
        
        // To determine whether this DocumentNodeData has children, we need 
        // to know whether the DocumentNodeElement it represents has child 
        // DocNodeElements. This kind of information is embedded inside a 
        // nodeStructure element which will often contain a repeat of the  
        // nodeTag-documentNodeElement itself. Therefore, we get the nodeTag's 
        // first descendent element that is a documentNodeElement and check 
        // whether it too has the same nodeID. If so, then we check whether  
        // that documentNodeElement has child nodes - which in that case will 
        // all be documentNodeElements. 
        Element innerDocNode = ParseUtil.getFirstDescElementCalled(
                       nodeTag, GSXML.DOC_NODE_ELEM);
        if(innerDocNode == null
           || !innerDocNode.getAttribute(GSXML.NODE_ID_ATT).equals(this.nodeID)) 
        {
            innerDocNode = this.nodeTag;
        }
        this.hasChildren = innerDocNode.hasChildNodes();
    }   
    
    /** 
     * Sets member metadataList if there is a &lt;metadataList&gt; subelement in
     * docNodeTag: first get the &lt;metadataList&gt; then its &lt;metadata&gt; 
     * children 
     * @param nodeTag is a documentNode or classifierNode XML Element that
     * contains metadata information which is used to set this NodeData object's
     * metadata (if there are any, the HashMap nodeMetadata will be set). */
    public void setMetadataList(Element nodeTag) {
        NodeList metaList = nodeTag.getElementsByTagName(
                GSXML.METADATA_ELEM);
        // will return empty metaList collection if there's none, so check for
        // size instead of null:
        int size = metaList.getLength(); 
        if(size > 0) {
            if(nodeMetadata == null) // if we check for this, can call 
                        // setMetadataList() on this DocNodeData obj many times 
                        // - each time with different <metadata> name-val pairs
                nodeMetadata = new HashMap(size);
            for(int i = 0; i < size; i++) {
                // we know each is an element, as we got all desc elements
                // of this <documentNode> that are <metadata>
                Element meta = (Element)metaList.item(i); 
                String name = meta.getAttribute(GSXML.NAME_ATT);
                Node e = meta.getFirstChild(); 
                // If not null, e should be a textNode now: get its value
                String bodyText = (e == null) ? "" : (String)e.getNodeValue();
                // nodeMetadata.put(name, bodyText);
                if(nodeMetadata.containsKey(name)) {
                    // key already exists, get the array of values mapping to that
                    // metadata name (= key)
                    Vector values = (Vector)nodeMetadata.get(name);
                    // check if the last value is the same as
                    // what we're trying to insert
                    String value = (String)values.get(values.size()-1);
                    if(!value.equals(bodyText)) // don't add duplicates
                        // append the new metadata value to the vector v:
                        values.add(bodyText);
                } else { // create a new (key, val) pair by creating a new vector 
                    // (= value) mapping to the new key
                    Vector values = new Vector();
                    values.add(bodyText);
                    nodeMetadata.put(name, values);
                }
            }
        }
    }
    
    /** Called when setting descendents lazily: only the children of this
     * node are set. We don't care to setDescendents now, will set it later
     * when necessary. 
     * @param v is an empty/non-null Vector which will, at method's end, contain  
     * all the Document- or ClassifierNodeData objects that are children of
     * this NodeData object. */
    protected void setChildren(Vector v, Map idsToNodes_map) 
    {
        // first get all child elements of type docNode or classifierNode:
        NodeList children = nodeTag.getChildNodes();
        if(children.getLength() == 0)
            return; // no children, this.childnodes remains at null
        
        int size = children.getLength();
        for(int i = 0; i < size; i++) {
            Node n = children.item(i);
            // For Element-nodes, getNodeName() returns the tag name.
            // It *never* returns null for *any* Node type
            if(n.getNodeName().equals(GSXML.CLASS_NODE_ELEM)) {
                Element nodeElementTag = (Element)n;
                if(!nodeElementTag.hasAttribute(GSXML.NODE_ID_ATT))
                    continue; // should not ever be the case
                    // skip any element that does not have a nodeID Attr
                
                String id = nodeElementTag.getAttribute(GSXML.NODE_ID_ATT);
                if(!idsToNodes_map.containsKey(id)) 
                    v.add(new ClassifierNodeData(nodeElementTag));
                else
                    v.add(idsToNodes_map.get(id));
            } else if(n.getNodeName().equals(GSXML.DOC_NODE_ELEM)) {
                Element nodeElementTag = (Element)n;
                if(!nodeElementTag.hasAttribute(GSXML.NODE_ID_ATT))
                    continue; // should not ever be the case
                    // skip any element that does not have a nodeID Attr
                
                String id = nodeElementTag.getAttribute(GSXML.NODE_ID_ATT);
                if(!idsToNodes_map.containsKey(id))
                    v.add(new DocumentNodeData(nodeElementTag));
                else
                    v.add(idsToNodes_map.get(id));
            } // else: tends to be an empty textNode ("#text"), skip that
        }
    }
    
    /** @return a hashmap of this document's metadata (name, val) pairs.
     * A null is returned if the nodeMetadata has not been set yet. */
    public Map getMetadataList() { return nodeMetadata; }
    

    /** @return the title of this docNodeData object, if any is set. If it's 
     * not been set yet (title metadata not yet set, a null is returned. */
    public String getTitle() {
        // Each metadata (like Title) may be an array of values. 
        // Here we return the first title in the array.
        if(this.nodeMetadata != null && this.nodeMetadata.containsKey("Title")) 
        {   // we know there's a title key now 
            
            Vector v = (Vector)this.nodeMetadata.get("Title");
            return (String)v.get(0); // return first Title element 
        } 
        else return null; // when nodeMetadata == null or no Title key
    }
    
    /** @return the title of this docNodeData object, if any.
     * Otherwise the nodeID is returned.
     * This method is useful for displaying this docNodeData object as a 
     * node in a JTree. Some meaningful displayable value is returned, 
     * unlike getTitle() which returns a null if title is not set yet. */
    public String toString() { 
        String title = getTitle(); 
        return (title == null) ? this.nodeID : title;
    }
    
    /** @return the details contained in this NodeData object.
     * Useful for debugging purposes. */
    public String show() { return this.nodeID; }
    
    /** @return a String representation of the contains of the 
     * nodeMetadata list (useful for debugging purposes). */
    public String showMeta() {
        StringBuffer buf = new StringBuffer();
        if(nodeMetadata != null && !nodeMetadata.isEmpty()) {
            buf.append("Metadata:\n");
            Set entrySet = nodeMetadata.entrySet();
            Iterator i = entrySet.iterator();
            while(i.hasNext()) {
                Entry entry = (Entry)i.next(); // Map.Entry
                buf.append("   name: " + (String)entry.getKey() + " values: ");
                Vector values = (Vector)entry.getValue();
                for(int j = 0; j < values.size(); j++)
                    buf.append((String)values.get(j) + ", ");
                buf.append("\n");
            }
        }
        return buf.toString();
    }
}