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

/**
 *#########################################################################
 * QueryFormData.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 org.greenstone.gsdl3.util.GSXML;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

// Currently in this file: 
// Two struct-like classes - QueryFormData and QueryFormParam (subclass of 
// QueryFormData) which is a static inner class of QueryFormData.

/** 
 *  Class QueryFormData represents the &lt;param&gt; and &lt;option&gt; elements 
 *  that can appear in a &lt;paramList&gt; tag in the xml response returned by 
 *  a describe request sent to *Query* Service (e.g. FieldQuery, TextQuery).Its 
 *  subclass QueryFormParam more fully represents the &lt;param&gt; elements, but
 *  this class covers the data shared by &lt;param&gt; and &lt;option&gt; elements.
 *  @author ak19
 */
public class QueryFormData {
    /** Constant for the "occurs" attribute name */
    public static final String OCCURS_ATT = "occurs";
    /** Name of the parameter or option this QueryFormData represents */
    public final String name;
    /** DisplayItem text content of the parameter or option this 
     * QueryFormData represents */
    public final String displayItem;
        
    /** 
     * Contructor to create a QueryFormData object from &lt;param&gt; 
     * or &lt;option&gt; elements of a Query response XML message.
     * @param param the &lt;param&gt; or &lt;option&gt; tag for which a
     * QueryFormData object is constructed, from the data the element contains.
     * */
    public QueryFormData(Element param) {
        this.name = param.getAttribute(GSXML.NAME_ATT);
        displayItem = extractDisplayItem(param);
    }
    
    /** 
     * Given an element, extracts the text value from the first direct child 
     * element that is a &lt;displayItem&gt; element and returns this.
     * @param param the &lt;param&gt; or &lt;option&gt; tag from which the data 
     * is extracted.
     * @return the text content of the displayItem in the &lt;param&gt; tag
    */
    protected String extractDisplayItem(Element param) {
        // Now find the displayItem value for this Param element
        // by cycling through childnodes of this element
        NodeList nl = param.getChildNodes();
        boolean found = false;
        for(int i = 0; !found && i < nl.getLength(); i++){
            Node n = nl.item(i);
            if(n.getNodeType() != Node.ELEMENT_NODE) 
                continue;
            // else
            Element e = (Element)n;
            if(e.getTagName().equals(GSXML.DISPLAY_TEXT_ELEM)) {
                // get the value in the body of this <displayItem> element
                if(e.hasChildNodes()) // some <displayItem> contain no text
                    return e.getFirstChild().getNodeValue().trim(); // text node
                else return "";
            }
        }
        return "";
    }
    
    /**
     * @return this object's displayItem string. This is also what is 
     * displayed when this object is added as a list items into a 
     * JComboBoxes or JList. 
    */
    public String toString() { return displayItem; }
    
    /** @return a display String of the member values of this QueryFormData 
     * object for debugging purposes */
    public String show() { 
        return "name: " + name + " displayItem: " + displayItem;
    }
    
    /** 
     *  Static inner class QueryFormParam is a subclass of QueryFormData and 
     *  uniquely represents the data that can be contained in any &lt;param&gt; 
     *  tag of the xml response that's returned when a describe request is sent to 
     *  a Query Service. As such, a QueryFormParam can contain further 
     *  QueryFormData (&lt;param&gt; or &lt;option&gt; elements) which are stored 
     *  as subElements of this QueryFormParam.
    */
    public static class QueryFormParam extends QueryFormData {
        /* Members to store data specific to a &lt;param&gt; tag */
        /** type attribute of &lt;param&gt; tag */
        public final String type;
        /** default attribute of &lt;param&gt; tag */
        public final String def; // any default value
        
        // Following fields set only for type=multi (else they're set to ""):
        /** occurs attribute of &lt;param&gt; tag specifies how often the 
         * widget occurs */
        public final String occurs; 
        /** ignore attribute of &lt;param&gt; tag specifies whether this param 
         * will be ignored at ignore=pos */
        public final String ignore;  
                
        /** A &lt;param&gt; element in a Query response XML message can contain  
         * children that are &lt;param&gt; or &lt;option&gt;. 
         * subElements therefore stores an array of QueryFormData to represent
         * these. 
         * &lt;param&gt; CAN (need not) contain &lt;options&gt;s and/or more 
         * &lt;param&gt;s. If subElements is null, it obviously has no child 
         * &lt;param&gt;s. */
        protected QueryFormData[] subElements = null; 
        
        /**
         * Constructor that creates a QueryFormParam object from the data 
         * contained in a &lt;param&gt;element of a Query response XML message.
         * @param param is an entire &lt;param&gt;element - the one currently being 
         * processed.
        */
        public QueryFormParam(Element param) {
            super(param);
            this.type = param.getAttribute(GSXML.TYPE_ATT);
            
            if(param.hasAttribute(GSXML.DEFAULT_ATT))
                def = param.getAttribute(GSXML.DEFAULT_ATT);
            else def = "";
                    
            if(param.hasAttribute(OCCURS_ATT)) // no GSXML constant defined for this
                occurs = param.getAttribute(OCCURS_ATT);
            else occurs = "";
            
            if(param.hasAttribute(GSXML.PARAM_IGNORE_POS_ATT))
                ignore = param.getAttribute(GSXML.PARAM_IGNORE_POS_ATT);
            else ignore = "";
        }
        
        /** Read-only accessor for this QueryFormParam object's subElements 
         * @return an array of this QueryFormParam's children QueryFormData objects  
         * (representing options or params). Null is returned if there are none. */
        public QueryFormData[] getSubElements() { return subElements; }
        
        /** @return a display String of the member values of this QueryFormParam 
         * for debugging purposes */
        public String show() { 
            StringBuffer buf = new StringBuffer(super.show());
            buf.append(" type: ");
            buf.append(type);
            buf.append(" def: ");
            buf.append(def.equals("") ? "-" : def);
            buf.append(" occurs: ");
            buf.append(occurs.equals("")? "-" : occurs);
            
            if(subElements == null) {
                buf.append("\n");
                return buf.toString();
            }
            // else 
            for(int i = 0; i < subElements.length; i++) {
                buf.append("\n     ");
                buf.append(subElements[i].show());
            }
            buf.append("\n");
            return buf.toString();
        }
    }
}