source: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/data/DocumentNodeData.java@ 26180

/**
 *#########################################################################
 * DocumentNodeData.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.Vector;
import java.util.Map;
import java.util.HashMap;
import java.util.Map.Entry;

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


/** 
 * Represents the data stored in the &lt;documentNode&gt; Elements
 * of Greenstone 3's XML response messages. A DocumentNodeData may
 * have descendants of type DocumentNodeData. Some DocumentNodeData
 * objects are the root of a structure, others are internal nodes or
 * leaves. 
 * See p.47 to p.49 in the manual.
 * @author ak19
 */
public class DocumentNodeData extends NodeData {
    /** NodeType of this DocumentNodeData: root, internal or leaf */
    public final String nodeType;
    /** DocType can be Hierarchical for instance */
    public final String docType;
    /** Rank of this DocumentNodeData if the &lt;documentNode&gt; 
     * Element was returned in a search result */
    public final double rank;
    
    // not set initially, only set after calling  
    // setDescendentsOfRootNode(<nodeStructure>)
    /** Reference to this doc's root */
    protected DocumentNodeData rootDoc = null; 
    /** children of this node: part of &lt;nodeStructure&gt; Element */
    protected DocumentNodeData[] childnodes = null; 
    
    /** A Hashmap to store &lt;nodeStructureInfo&gt; of a DocumentNodeData
     * (if it has any) */
    protected HashMap nodeStructureInfo_map = null;
    
    /** The text content of the document */
    protected String nodeContent = null;
        
    /** Given tags of the form 
     * &lt;documentNode nodeID="HASHac0a04dd14571c60d7fbfd.4.2"
     * nodeType="x" docType="y"&gt;
     * &lt;nodeContent>Text&lt;/nodeContent&gt;
     * &lt;nodeStructureInfo>&lt;info name="i" value="1" /&gt;
     * &lt;info name = "ii" value = "2" /&gt;&lt;/nodeStructureInfo&gt;
     * &lt;metadataList&gt;&lt;metadata name="a"&gt;Value
     * &lt;/metadata&gt;&lt;/metadataList&gt;
     * &lt;nodeStructure&gt;
     *      &lt;documentNode ....>&lt;/documentNode&gt;
     *      &lt;documentNode ....>&lt;/documentNode&gt;
     * &lt;/nodeStructure&gt;
     * &lt;/documentNode&gt;
     * this constructor extracts the nodeId out of it and any other fields 
     * that might be set in the docNodeTag &lt;documentNode&gt; element.
     * @param docNodeTag is an &lt;documentNode&gt; XML element to construct
     * this DocumentNodeData object from  
    */
    public DocumentNodeData(Element docNodeTag){
        // We'd definitely have the nodeID attribute, but to be on the safe 
        // side:
        super(docNodeTag);
                
        // this.nodeType and this.docType will be set: these attributes are
        // there in the <documentNode> elements of all Query Responses as
        // well as in <documentNode>s of documentStructureRetrieve responses.
        this.nodeType = docNodeTag.hasAttribute(GSXML.NODE_TYPE_ATT) ?
                docNodeTag.getAttribute(GSXML.NODE_TYPE_ATT) 
                : GSXML.NODE_TYPE_ROOT; //DEFAULTING TO ROOT IF NONE SPECIFIED!
                
        this.docType = docNodeTag.hasAttribute(GSXML.DOC_TYPE_ATT) ?
                docNodeTag.getAttribute(GSXML.DOC_TYPE_ATT) : "";
                // OR default to GSXML.DOC_TYPE_SIMPLE????
        
        String rankVal = docNodeTag.hasAttribute(GSXML.NODE_RANK_ATT) ? 
                docNodeTag.getAttribute(GSXML.NODE_RANK_ATT) : "0";
        this.rank = Double.parseDouble(rankVal);        
                
        // If <documentNode> has no <metadataList> child, then member variable
        // metadataList remains null and can be set later if and as required.
        setMetadataList(docNodeTag);
        
        // structureInfo either initialised if there <documentNode> has a child
        // element called <nodeStructureInfo>, else it remains null. 
        setNodeStructInfo(docNodeTag);
        
        // Sets member nodeContent (the text content of the document) to the
        // document's text if this <documentNode> has a child <nodeContent>. 
        // If there is no such child, nodeContent will be set to empty string. 
        setNodeContent(docNodeTag);
    }
    
    /** Given a &lt;nodeStructure&gt;&lt;/nodeStructure&gt; element returned   
     * from a request for the *ENTIRE* nodeStructure, this method will find the  
     * &lt;documentNode&gt; that is the Root (nodeType=ROOT) and from there
     * on proceed to set all descendent &lt;documentNode&gt;s.
     * If either the root or any descendent &lt;documentNode&gt;s have already 
     * been instantiated at any point during program execution, it will
     * be reused, else a new object representing that descendent/root
     * &lt;documentNode&gt; will be created.
     * The nodeIDsToDocNodes_map is a mapping of nodeIDs to existing 
     * documentNodeData objects, so that the DocumentNodeData objects with 
     * the same ID need not be instantiated where they already exist.
     * This method returns the rootNode if it completes successfully,
     * otherwise it returns null.
     * @param nodeStructure is the &lt;nodeStructure&gt;&lt;/nodeStructure&gt; 
     * element returned from a request for the *ENTIRE* nodeStructure
     * @param nodeIDsToDocNodes_map is the Map of node IDs to DocumentNodeData
     * objects being maintained
     * @return the root DocumentNodeData object of the &lt;documentNode&gt;s
     * in the &lt;nodeStructure&gt;
    */
    public DocumentNodeData setDescendentsOfRootNode(Element nodeStructure, 
            Map nodeIDsToDocNodes_map) 
    {
        // First find <documentNode> inside <nodeStructure> where 
        // nodeType==ROOT. This always happens to be the first 
        // <documentNode> child of <nodeStructure> 
        // Use this root <docNode> to set its children and all descendents
        // If there is no <docNode nodetype==ROOT>, return false.
        Element rootDocNodeTag = ParseUtil.getFirstChildElementCalled(
                nodeStructure, GSXML.DOC_NODE_ELEM);
        
        // These cases shouldn't occur, but to be on the safe side -
        // Actually, this happens with project gutenberg searches: where
        // docType and nodeType are not set and the <nodeStructure>
        // contains no child <documentNode>. In such cases, make this
        // documentNodeData the root.
        if(rootDocNodeTag == null) {
            rootDoc = this;
            return rootDoc;
        }
        String type = rootDocNodeTag.getAttribute(GSXML.NODE_TYPE_ATT);
        if(!type.equals(GSXML.NODE_TYPE_ROOT)) {
            rootDoc = this; // Case of first <docNode> of <nodeStructure>
            return rootDoc; // nodetype != root -> this shouldn't happen
                // but if there's only 1 node and it's a leaf, make it
                // the root. This actually happens in simple image collections
                // which have no substructures containing further images
            //return null;    
        }
        // We found the root node Element we want, get its NodeID,
        // and then start processing the root node for descendents
        String ID = rootDocNodeTag.hasAttribute(GSXML.NODE_ID_ATT) ?
                    rootDocNodeTag.getAttribute(GSXML.NODE_ID_ATT) : "";
                    
        // try to find this ID in HashMap of already instantiated
        // documentNodeData objects - if it exists, set children
        // on that. If it doesn't, then create new object and set
        // the children+descendents on that. (Creating new object
        // will automatically add it to the hashMap
        DocumentNodeData root = null;
        if(nodeIDsToDocNodes_map.containsKey(ID))
            root = (DocumentNodeData)nodeIDsToDocNodes_map.get(ID);
        else  {
            // not in HashMap, so create a new docNode (this will set
            // nodeType and docType) and add it to the map
            root = new DocumentNodeData(rootDocNodeTag);
            nodeIDsToDocNodes_map.put(root.nodeID, root);
        }
        
        this.rootDoc = root;
        
        // either way, we have a root node now, so set its children
        root.setDescendents(root, rootDocNodeTag, nodeIDsToDocNodes_map); 
                    // docNodeTag of root
        
        return root;
    }
    
    
    /** 
     * Recursive method.
     * Called by setDescendentsOfRootNode(). Given a docNodeTag (of the Root)
     * which was nested within a &lt;nodeStructure&gt; element, this method sets
     * all the descendents of that root. This means that each documentNodeData
     * object in the hierarchy of the root will have its childnodes[] variable
     * set, iff that object is not a nodeType==LEAF. With leaves, the  
     * childnodes array will remain null.
     * The nodeIDsToDocNodes_map is a mapping of nodeIDs to existing 
     * documentNodeData objects, so that the DocumentNodeData objects with the
     * same ID need not be instantiated where they already exist.
     * @param root - the root element of this documentNodeData
     * @param docNodeTag - the &lt;documentNode&gt; XML Element of the Root
     * nested within a &lt;nodeStructure&gt; element
     * @param nodeIDsToDocNodes_map is the Map of node IDs to DocumentNodeData
     * objects being maintained
     */
    protected void setDescendents(DocumentNodeData root, Element docNodeTag, 
        Map nodeIDsToDocNodes_map) 
    {
        if(this.nodeType.equals(GSXML.NODE_TYPE_LEAF))
                return; // no children
        
        Vector children = ParseUtil.getAllChildElementsCalled(
                docNodeTag, GSXML.DOC_NODE_ELEM);
        if(children == null) // shouldn't have to check this, as the check
                            // on nodeType==LEAF above would have been enough 
            return; // no children, hence no descendents
        
        // else, obtain and instantiate DocumentNodeData objects
        // on each of the children
        this.childnodes = new DocumentNodeData[children.size()];
        for(int i = 0; i < childnodes.length; i++) {
            Element childDocNodeTag = (Element)children.get(i);
            String ID = childDocNodeTag.hasAttribute(GSXML.NODE_ID_ATT) ?
                    childDocNodeTag.getAttribute(GSXML.NODE_ID_ATT) : "";
            
            if(nodeIDsToDocNodes_map.containsKey(ID))
                childnodes[i] 
                     = (DocumentNodeData)nodeIDsToDocNodes_map.get(ID);
            else { //not yet in the map of documentNodeData objects, so  
                // create a new DocumentNodeData and add it to the map 
                childnodes[i] = new DocumentNodeData(childDocNodeTag);
                nodeIDsToDocNodes_map.put(childnodes[i].nodeID, childnodes[i]);
            }
            // set the root for the descendent:
            childnodes[i].rootDoc = root; 
            // Now set its children and so on until all descendents indicated
            // in the <nodestructure><documentNode /></nodestructure> have
            // been set.
            childnodes[i].setDescendents(
                    root, childDocNodeTag, nodeIDsToDocNodes_map);
        }
    }
    
    /* Can call these methods later as well (after constructor). If the 
     * docNodeTag passed to the constructor did not have these attributes, 
     * can set them later with a docNodeTag of the same nodeID that does
     * have these attributes set. */
            
    /** Sets structureInfo member variable &lt;nodeStructureInfo&gt; element is  
     * present as child of &lt;documentNode&gt;, else value of structureInfo 
     * remains unchanged. A &lt;docNode&gt; has no more than one child   
     * &lt;nodeStructureInfo&gt; in a response to a DocumentStructureRetrieve.  
     * However, the response can contain many such &lt;docNodes&gt;. 
     * See manual p.49. 
     * @param docNodeTag is the &lt;documentNode&gt; XML element containing
     * the &lt;nodeStructureInfo&gt; Element that is to be processed */
    public void setNodeStructInfo(Element docNodeTag) {
        NodeList nl = docNodeTag.getElementsByTagName(
                GSXML.NODE_STRUCTURE_ELEM+GSXML.INFO_ATT);
        if(nl.getLength() > 0) {
            // get the first <nodeStructureInfo> (which will be the only
            // <nodeStructureInfo> for this <docNode>
            Element nodeStructInfoTag = (Element)nl.item(0);
            nl = null;
            // Get any children <info> tags and extract data-values from them
            nl = nodeStructInfoTag.getElementsByTagName("info");
            int size = nl.getLength(); 
            if(size > 0) {
                nodeStructureInfo_map = new HashMap(size);
                for(int i = 0; i < size; i++) {
                    Element infoTag = (Element)nl.item(i); 
                    String name = infoTag.hasAttribute(GSXML.NAME_ATT) ?
                            infoTag.getAttribute(GSXML.NAME_ATT) : "";
                    String value = infoTag.hasAttribute(GSXML.VALUE_ATT) ?
                            infoTag.getAttribute(GSXML.VALUE_ATT) : "";
                    nodeStructureInfo_map.put(name, value);     
                }
            }
        }
        // in all other cases, nodeStructureInfo_map remains null
    }   
    
    /** Sets member variable nodeContent with the text (if any) inside any 
     * &lt;nodeContent&gt;&lt;/nodeContent&gt; child element of 
     * &lt;documentNode&gt;, else the value of nodeContent is set to empty 
     * string (""). The empty string will prevent it from being retrieved again
     * and again (which would happen if nodeContent remained at null) if it had
     * already been retrieved once.
     * However, if the docNodeTag parameter is not the response from
     * a documentContentRetrieve (if it doesn't have the proper XML 
     * structure for that), nodeContent remains null and can be set
     * in future when given an appropriate docNodeTag. 
     * @param docNodeTag is the &lt;documentNode&gt; XML element containing
     * the content information for this DocumentNodeData object */
    public void setNodeContent(Element docNodeTag) {
        Element nodeContentTag = ParseUtil.getFirstChildElementCalled(
                docNodeTag, GSXML.NODE_CONTENT_ELEM);
        if(nodeContentTag != null) { //such a child tag exists
            //obtain its child textNode and the value thereof
            Node content = nodeContentTag.getFirstChild();
            // content will be null if <nodeContent /> instead of 
            // <nodeContent></nodeContent>
            this.nodeContent 
                =  (content == null) ? "" : content.getNodeValue();
            
            // Now to fix the html if it's not already proper:
            if(nodeContent.startsWith("<Sec>")) { // remove starting <Sec>
                        // it's not a recognised tag in html
                nodeContent = nodeContent.substring(5); 
                nodeContent = nodeContent.trim();
                if(nodeContent.startsWith("</")) {
                    // first closing bracket
                    int index = nodeContent.indexOf(">");
                    // remove any starting </B> or </I>
                    nodeContent =  nodeContent.substring(index+1);
                    nodeContent = nodeContent.trim();
                }
            }
            // Finally, make sure it has the proper starting (and ending tags)
            if((!nodeContent.startsWith("<html>")) 
                    || (!nodeContent.startsWith("<HTML>"))) {
                nodeContent = "<html><head></head><body>"
                    + nodeContent + "</body></html>";
            }
        } 
        // else leave nodeContent as null, docNodeTag was not returned 
        // as the result of a docContentRetrieve response
    }
    
    
    /** @return the data stored in this DocumentNodeData object, all except 
     * the document content which can be accessed by calling toString(). 
     * This method is useful for debugging purposes: to view what each
     * field's values are. */
    public String show() {
        StringBuffer buf = new StringBuffer("nodeID: " + this.nodeID);
        buf.append(" nodeType: " + this.nodeType);
        buf.append(" docType: " + this.docType);
        
        if(nodeStructureInfo_map != null) {
            buf.append("NodeStructureInfo:");
            Iterator i = nodeStructureInfo_map.entrySet().iterator();
            while(i.hasNext()) {
                Entry e = (Entry)i.next();
                buf.append("\nname: " + (String)e.getKey());
                buf.append(" value: " + (String)e.getValue());
            }
        }
        buf.append("\n");
        buf.append(showMeta());
        return buf.toString();
    }
    
    /** @return true if the (nodeType of) this DocumentNodeData is a leaf */
    public boolean isLeaf() { return nodeType.equals(GSXML.NODE_TYPE_LEAF); }
    
    /* Accessor methods */
    /** @return the nodeType of this DocumentNodeData */
    public String getNodeType() { return nodeType; }
    /** @return the docType of this DocumentNodeData */
    public String getDocType() { return docType; }
    
    /** @return the root of the structure of which this documentNodeData
     * is part (this docNodeData is either the root itself or its child
     * or descenedent). A null is returned if the Root docNode and its
     * descendents have not been set yet. */
    public DocumentNodeData getRoot() { return this.rootDoc; }
        
    /** @return this document's text content (which may be empty string 
     * if there was none). It will return null if the nodeContent has
     * not been set yet. */
    public String getContent() { return nodeContent; }
    
    /** @return an array of all this DocNode's children. Each childnode 
     * in turn, can further contain children, etc. Null is returned if
     * there are no childnodes or if setDescendentsOfRootNode() has not
     * been called (that is, if the root has not yet been set). */ 
    public DocumentNodeData[] getDescendents() { return childnodes; }
    
    /** @return gets the children (NodeData) of this DocumentNodeData
     * but does not guarantee that their children are set. That is,
     * it's possible that this DocumentNodeData's children may have 
     * children of their own but that these may not be set yet (and
     * are temporarily still null). */
    public NodeData[] getChildren() { return childnodes; }
    
    /** When called on a rootNode, returns an array of all the descendents' 
     * nodeIDs. If this object is not a rootNode, it returns null. 
     * Parameter onlyTheUntitled, if true, makes this method return only the   
     * nodeIDs of those documentNodeData descendents for whom the title has 
     * not yet been set.
     * If false, the nodeIDs of all dDcumentNodeData descendents will be
     * returned, regardless of whether their titles are already set. 
     * @param onlyTheUntitled - if true this method is only to return those 
     * descendants' IDs whose titles have not yet been set. If false,
     * all descendants' nodeIDs are returned.
     * @return an array of all the descendant DocumentNodeData's NodeIDs */
    public String[] getDescNodeIDsAsList(boolean onlyTheUntitled) {
        String[] nodeIDs = null;
        if(this.nodeType.equals(GSXML.NODE_TYPE_ROOT)) {
            Vector v = new Vector();
            if(!onlyTheUntitled || this.getTitle() == null)
                v.add(this.nodeID); // add root only if its title not yet set
            descNodeIDsAsList(v, this, onlyTheUntitled);
            if(v.size() > 0) {
                nodeIDs = new String[v.size()];
                v.toArray(nodeIDs);
            } // else if v.size() == 0, this method will return null
        }
        return nodeIDs;
    }
    
    /** Recursive method that adds all the nodeIDs of the descendents
     * of DocumentNodeData parent into the Vector v.
     * If parameter onlyTheUntitled=true, then only the nodeIDs of the
     * untitled DocumentNodeData descendents are added in. Otherwise,
     * all descendents' nodeIDs are.
     * @param v is the Vector being populated with descendant documentNodeData's
     * IDs.
     * @param parent is the parent DocumentNodeData node currently being
     * considered in this recursion step.
     * @param onlyTheUntitled should be true if only those descendant 
     * DocumentNodeData objects that don't yet have a title need to be returned. 
     * If false, it returns all descendants' nodeIDs in the Vector v. */
    protected static void descNodeIDsAsList(Vector v, 
            DocumentNodeData parent, boolean onlyTheUntitled) 
    {
        // Recursion
        // Base case:
        if(parent.childnodes == null)
            return; 
        for(int i = 0; i < parent.childnodes.length; i++) {
            // Now comes step that does actual processing:
            
            // if only asking for NodeIDs of descendents whose titles
            // aren't set yet, then: 
            if(!onlyTheUntitled || parent.childnodes[i].getTitle() == null)
                v.add(parent.childnodes[i].nodeID); 
                // above if-stmt should add the desc nodeID for either 
                // - all descendents (if onlyTheUntitled=true); or  
                // - otherwise, only for those whose title is not set yet
            
            // Recursion step:
            DocumentNodeData.descNodeIDsAsList(
                    v, parent.childnodes[i], onlyTheUntitled); 
        }
    }
    
    /** @return true if this documentNode's root is associated with the
     * ImagePlug or PagedImgPlug. 
     * @see <a href="http://wiki.greenstone.org/wiki/gsdoc/tutorial/en/scanned_image_collection.htm">The scanned image collection, for names of Plugin metadata values PagedImgPlug and ImagePlug</a> */
    public boolean canBeImage() {
        if(this.rootDoc == null) {
            return false;
        }
        // else 
        if(!this.rootDoc.nodeMetadata.containsKey("Plugin")) {
            return false; // this shouldn't happen: 
                    // I think every root has Plugin meta
        }
        // else
        Vector values = (Vector)this.rootDoc.nodeMetadata.get("Plugin");
        String plugin = (String)values.get(0);
        
        final String imagePlug = "PagedImgPlug";
        final String pagedImgPlug = "ImagePlug";
        if(plugin.equals(pagedImgPlug) || plugin.equals(imagePlug)) 
            return true;
        else 
            return false;
    }
    
    /** @return value of "notext" metadata field, if any. If true, this 
     * indicates that the document is purely an image. Otherwise it indicates
     * that there is both a text view and an image view associated with this
     * document. */
    public boolean hasNoText() {
        if(this.nodeMetadata == null)
            return false; // deal with any odd cases
        
        if(!this.nodeMetadata.containsKey("NoText"))
            return false; // no NoText metadata, so it probably has text
        Vector values = (Vector)this.nodeMetadata.get("NoText");
        String noText = (String)values.get(0);
        int val = Integer.parseInt(noText);
        return (val == 1); // 0 if it has text, 1 if indeed it has no text 
    }
        
    /** @return the image url stored in the "srcicon" metadata field, if any. */
    public String getImgURL() {
        if(this.nodeMetadata == null)
            return ""; // deal with any odd cases
        
        String imgMetaFound = "";
        String srclinkFile = nodeMetadata.containsKey("srclinkFile") ? (String)((Vector)nodeMetadata.get("srclinkFile")).get(0) : "";
        String w = nodeMetadata.containsKey("ImageWidth") ? (String)((Vector)nodeMetadata.get("ImageWidth")).get(0) : "";
        String h = nodeMetadata.containsKey("ImageHeight") ? (String)((Vector)nodeMetadata.get("ImageHeight")).get(0) : "";

        if(this.nodeMetadata.containsKey("srcicon")) {
            imgMetaFound = "srcicon";
        }
        else if(this.nodeMetadata.containsKey("srclink")) { // old Greenstone 3
            imgMetaFound = "srclink";
        } 
        else {
            return "";
        }
        Vector values = (Vector)this.nodeMetadata.get(imgMetaFound);
        String imgTag = (String)values.get(0);

        if(imgMetaFound.equals("srcicon")) {
            imgTag = imgTag.replace("[srclinkFile]", srclinkFile);
            imgTag = imgTag.replace("[ImageWidth]", w);
            imgTag = imgTag.replace("[ImageHeight]", h);
            return imgTag;
        }

        // else deal with srclink in the old Greenstone 3 way:

        // now we got <a href="somelink">; extract just the "somelink" portion
        int startindex = imgTag.indexOf('\"');
        int endindex = imgTag.lastIndexOf('\"');
        imgTag = imgTag.substring(startindex, endindex+1);
        
        // remove the macro - if present - and replace it with the 
        // assocFilePath mentioned in the document's root's metadata
        startindex = imgTag.indexOf('[');
        if(startindex != -1 && imgTag.contains("assocfilepath")) {
            if(this.rootDoc == null) // need root doc to get assocfilepath
                return "";
            // else
            endindex = imgTag.indexOf(']');
            imgTag = imgTag.substring(0, startindex) 
                + getAssocFilePath()
                + imgTag.substring(endindex+1, imgTag.length());
        }
        return imgTag;
    }
    
    /** @return the Source metadata value which represents the image file
     *  name. Returns "" if this DocumentNodeData is not a root or does not
     *  have Source meta. */
    public String getImgName() {
        if(this.rootDoc == null)
            return "";
        // else
        if(!this.nodeMetadata.containsKey("Source"))
            return "";
        // else
        Vector values = (Vector)this.nodeMetadata.get("Source");
        return (String)values.get(0);
    }
    
    /** @return the vector of values for metadata name "gsdlassocfile": a vector
     *  of MetaPairs(filename, mimetype).
     * An empty vector is returned for all docNodes other than the root. And the 
     * root too need not always have associated files listed in its metadata. */
    public Vector getAssociatedFileNames() {
        Vector v = new Vector();
        final char COLON = ':';
        if(this.nodeMetadata.containsKey("gsdlassocfile")) {
            Vector assocFileNames = (Vector)nodeMetadata.get("gsdlassocfile");
            for(int i = 0; i < assocFileNames.size(); i++) {
                // assocFileNames are stored in format "cover.jpg:image/jpeg:"
                // need to split these to separate the name from the mimetype
                String filename = (String)assocFileNames.get(i);
                int firstColon = filename.indexOf(COLON); 
                String mimetype = filename.substring(
                    firstColon+1, filename.lastIndexOf(COLON));
                filename = filename.substring(0, firstColon);
                Pair p = new Pair(filename, mimetype);
                // (we're not going to be sorting these pairs, so we make 
                // no use of each Pair's Comparable nature)
                v.add(p);
            }
        }
        return v; // returns empty vector if no gsdlassocfile metadata
    }
    
    /** @return the root document's assocfilepath metadata field, if any. 
     * This will indicate the directory path where the associated images
     * and other files are stored. */
    public String getAssocFilePath() {
        if(this.rootDoc == null)
            return "";
        // else, check for rootDoc having "assocfilepath" metadata:
        if(!rootDoc.nodeMetadata.containsKey("assocfilepath"))
            return "";
        Vector values = (Vector)rootDoc.nodeMetadata.get("assocfilepath");
        return (String)values.get(0);
    }
}