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

/**
 *#########################################################################
 * ResponseData.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.Vector;
import java.util.LinkedHashMap;
import java.util.Map;

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

/** 
 * Represents the data in a response XML message that is returned as
 * either a Browse or Query (Search) request.
 * Subclasses therefore are BrowseResponseData and QueryResponseData. 
 * This class maintains a Map of (nodeID, NodeData ref) pairs
 * representing the resulting &lt;classifierNode&gt;s and &lt;documentNode&gt;s
 * that can be returned when executing a SINGLE browse or query request. 
 * @author ak19
*/
public abstract class ResponseData {
    /** map of (nodeIDs, references to associated NodeData) pairs, 
     * stored in the order they are contained in the response XML messages 
     * (the order in which data objects are parsed and created for them) */
    protected Map nodeIDsToNodes;
    
    /** Subclasses must implement this method to parse the 
     * &lt;message&gt;&lt;response&gt;&lt;/response&gt;&lt;/message&gt;
     * that is returned upon executing a browse or query request.
     * At the end of this method, the Map nodeIDsToNodes will contain
     * any DocumentNodeData or ClassifierNodeData objects described
     * in the responseMsgTag. 
     * @param responseMsgTag the XMl response message Element whose data will
     * be parsed and stored in the ResponseData subclass */
    public abstract void setResponseData(Element responseMsgTag);
    
    /** Default constructor, creates the nodeIDsToNodes map */
    public ResponseData() {
        // A LinkedHashMap maintains documents in the order they were inserted
        // This is what we want for the docIdsToDocNodes mapping, because the
        // documents are returned in ranked order.
        // TreeMap does not work, as it compares based on keys=docNodIDs here.
        // And creating a Comparator for a TreeMap does not work either,
        // because the compare() method of Comparator is given two keys and so
        // needs to access the docIdsToDocNodes map to retrieve the 
        // documentNodeData obj for the parameter keys (nodeIDs) to access the 
        // rank member var of the documentNodeData objects in order to do the
        // comparison. However, that is a problem when ordering!
        nodeIDsToNodes = new LinkedHashMap();
    }
    
    /** Clears/resets this ResponseData object of all data, so that it can be  
     * reused to process future Browse and Query requests. In this case, it 
     * merely clears the internal Map nodeIDsToNodes. Subclasses may need to 
     * clear other variables. */
    public void clear() { this.nodeIDsToNodes.clear(); }
    
    
    /** @return the Map of mappings from nodeIDs to NodeData object references */
    public Map getIDToNodeMapping() { return nodeIDsToNodes; }
    
    /** Given an nodeID, returns the NodeData object with that nodeID,
     * if any. Otherwise, null is returned. Subclass might want to add
     * a different method that converts this to DocumentNodeData type.
     * @param ID is the nodeID whose NodeData object is requested */
    public NodeData getNodeForID(String ID) {
        return (NodeData)nodeIDsToNodes.get(ID);
    }

    /** After a DocumentContentRetrieve request for one or more documents 
     * has returned a response, this method - when given the response XML - 
     * will set the nodeContents of each document in the response (as long
     * as those documents already have an associated DocumentNodeData
     * object instantiated, which should/would always be the case).
     * @param messageTag is the DocumentContentRetrieve XML response message 
     * containing the document contents for one or more documentNodes */
    public void setContentForDocs(Element messageTag) {
        NodeList docNodeTags = messageTag.getElementsByTagName(
                GSXML.DOC_NODE_ELEM);
        int size = docNodeTags.getLength();
        if(size == 0) // no <documentNode> in <message> to set the content for
            return; 
        
        for(int i = 0; i < size; i++) {
            Element docNodeTag = (Element)docNodeTags.item(i);
            String id = (String)docNodeTag.getAttribute(GSXML.NODE_ID_ATT);
            
            // Find the associated DocumentNodeData object 
            // in the map of documentNodeData objects
            DocumentNodeData doc 
                = (DocumentNodeData)this.nodeIDsToNodes.get(id);
            if(doc == null) //no such document: shouldn't happen
                continue; // skip to look at next docNode
            
            doc.setNodeContent(docNodeTag);
        }
    }   
    
    /** This method can be called after a DocumentMetadataRetrieve request 
     * has returned a response. Given the response message (XML) element,
     * this method attempts to set the metadata for all the documentNodeData
     * objects it has, using the metadata tags in the response-message-XML. 
     * This method returns false if the responseMessage XMl does not contain
     * any &lt;documentNodeList&gt; elements. 
     * @param NODE_ELEM can be either GSXML defined constant for 
     * &lt;ClassifierNode&gt; or &lt;DocumentNode&gt;
     * @param messageTag is the DocumentMetadataRetrieve XML response message 
     * containing the metadata for one or more documentNodes/classifierNodes
     * as specified by NODE_ELEM */
    protected boolean setMetadataForNodes(Element messageTag, 
            final String NODE_ELEM) 
    {
        // get the <documentNodeList> 
        Element docList = ParseUtil.getFirstDescElementCalled(
                messageTag, NODE_ELEM+GSXML.LIST_MODIFIER);
        if(docList == null)
            return false; // if no <documentNodeList>, then we can't process
                        // (shouldn't have got here)
        
        // for each <documentNode>'s nodeID attribute's value, get the 
        // documentNodeData reference, and set its metadataList using
        // its <docNode> tag
        Vector docNodesWithMetaInfo = ParseUtil.getAllChildElementsCalled(
                docList, NODE_ELEM);
        if(docNodesWithMetaInfo == null)
            return false; // no <documentNode> children, so no metadata to set
        for(int i = 0; i < docNodesWithMetaInfo.size(); i++) {
            Element docNodeTag = (Element)docNodesWithMetaInfo.get(i);
            if(!docNodeTag.hasAttribute(GSXML.NODE_ID_ATT))
                continue; // shouldn't be the case
            String nodeID = docNodeTag.getAttribute(GSXML.NODE_ID_ATT);
            NodeData docNode 
                = (NodeData)nodeIDsToNodes.get(nodeID);
            if(docNode != null) // can only set the meta if there is a
                    // docNode with this nodeID in our docIDsToDocNodes
                docNode.setMetadataList(docNodeTag);
        }
        return true;
    }
    
    /** This method sets the metadata for one or even all &lt;documentNode&gt; 
     * data objects contained in the Map nodeIDsToNodes, using the &lt;message&gt; 
     * element parameter (which is returned upon a documentMetadataRetrieve 
     * request. Metadata for &lt;classifierNodes&gt; are not set with this method. 
     * It merely calls the setMetadataForDocuments(messageTag, tagName) 
     * method to parse out data for the tagName=&lt;documentNode&gt;.
     * @param messageTag is the DocumentMetadataRetrieve XML response message 
     * containing the metadata for one or more documentNodes */
    public boolean setMetadataForDocuments(Element messageTag) {
        return setMetadataForNodes(messageTag, GSXML.DOC_NODE_ELEM);
    }
}