source: other-projects/gs3-webservices-java-client/trunk/src/GS3DemoClient/org/greenstone/gs3client/QueryForm.java@ 26174

/**
 *#########################################################################
 * QueryForm.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;

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

import org.greenstone.gs3client.data.QueryFormData;
import org.greenstone.gsdl3.util.GSXML;

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

import java.awt.Cursor;
import java.awt.BorderLayout;
import javax.swing.BoxLayout;
import javax.swing.BorderFactory;
import javax.swing.JButton;
import javax.swing.JPanel;
import javax.swing.JScrollPane;
import javax.swing.border.TitledBorder;

import java.awt.event.KeyListener;
import java.awt.event.KeyEvent;
import java.awt.event.ActionListener;
import java.awt.event.ActionEvent;

/**
 * Panel that represents a Query Form based on GS3 describe response XML 
 * messages sent by a Query Service. An inner panel will contain all the
 * actual form controls. The form can be reset to empty which will clear
 * its contents. Its contents can be reset to display controls appropriate
 * to new Query Service describe response XML messages.
 * @author ak19
*/
public class QueryForm extends JPanel 
    implements ActionListener, KeyListener, ColourCombo.ColourChangeable 
{
    /** Handle to the running instance of the GS3JavaClient in order to have
     * access to its methods */
    protected GS3JavaClient client;
    /** Panel to contain all the form controls specific to the chosen Query 
     * Service. */
    protected JPanel paramsPanel = null;
    /** Search button that will cause the search to be executed when pressed */
    protected JButton searchButton = null;
    /** Query parameters specified by the query services */
    protected QueryFormData[] paramTags = null; 
    
    /** Constructor that instantiates this Form's internal GUI items.
     * @param client - handle to the running instance of the GS3JavaClient */
    public QueryForm(GS3JavaClient client) {
        super(new BorderLayout());
        this.client = client;
        
        // Create the search button and register listeners for button pressed 
        // and Enter key pressed events on it.
        searchButton = new JButton();
        searchButton.addActionListener(this);
        searchButton.addKeyListener(this);
        
        paramsPanel = new JPanel();
        paramsPanel.setLayout(new BoxLayout(paramsPanel, BoxLayout.Y_AXIS));
    }
    
    /** Call this method to empty all the form controls. This Query Form
     * component can then be reused. */
    public void clear() {
        // empty all controls
        
        paramsPanel.removeAll();
        paramTags = null; //get rid of the Params data for the query
        
        this.removeAll();
        this.validate();
        this.setBorder(null);
        this.repaint();
    }
    
    /** Changes the colour of the query form and its controls to the
     *  current colours set in class ColourCombo. Specified by
     *  the ColourCombo.ColourChangeable interface. */
    public void changeUIColour() {
        ColourCombo.changeColor(this);
        ColourCombo.changeColor(this.paramsPanel);
    }
    
    /** Called when this QueryForm's search button is pressed: the data  
     * entered/controls settings specified by the user are passed to the
     * digital library's Query Service in order to perform the search. */
    public void actionPerformed(ActionEvent e) {
        this.searchButtonPressed();
    }
    
    /** Defined by KeyListener interface. Does nothing. */
    public void keyPressed(KeyEvent e) {}
    /** Defined by KeyListener interface. Does nothing. */
    public void keyTyped(KeyEvent e) {}
    
    /** Called when the searchButton was in focus and a key was pressed. If 
     * this key was the Enter button, then the search is performed: the data 
     * entered/controls settings specified by the user are passed to the
     * digital library's Query Service in order to perform the search. */
    public void keyReleased(KeyEvent e) {
        if(e.getKeyCode() == KeyEvent.VK_ENTER) {
            this.searchButtonPressed();
        }
    }
    
    /** Called when the searchButton was clicked or when it was in focus 
     * and the enter key was pressed. The search is performed by passing the 
     * data entered/controls settings specified by the user to the digital
     * library's Query Service in order to perform the search. */
    protected void searchButtonPressed() {
        // (1) Search button pressed: obtain all the user-input from the 
        // query form. Use these to create a HashMap of name-val pairs 
        // representing  the parameters for the query.
        HashMap nameValParamsMap = new HashMap();
        for(int i = 0; i < paramTags.length; i++) {
            QueryFormControl formControl = (QueryFormControl)paramTags[i];
            formControl.setSelectedValue(nameValParamsMap);
        }
        // (2) Let the main java-client class handle the rest:
        this.client.performSearch(nameValParamsMap);
    }
    
    /** 
     * Sets up the the query form for display (queryPanel) given the XML of   
     * the response-message returned by a "describe" request sent to a 
     * Query Service. That is, generates the query form as specified
     * by the given response XML for a Query describe.
     * @param el - a serviceResponseXML for a describe request that specifies
     * how the paramsPanel should look.
    */
    public void formFromQueryServiceDescribe(Element el) {
        this.clear();
        
        // Display the form controls associated with the Query Servie
        
        // Get the service element <service></service> embedded inside message: 
        // <message><response><service></service></message></response>
        // service = (Element)el.getElementsByTagName("service").item(0);
        Element service 
            = (Element)el.getElementsByTagName(GSXML.SERVICE_ELEM).item(0);
        if(service == null) // shouldn't be the case
            return; // do nothing
        Element paramList = null;
        
        // Some heading information for each Query service display form 
        String nameVal = "", description = "", submit ="";
        
        // Get all the children. For *services*, these can only be <paramList>
        // or <displayItemList> elements, as per the manual p.37:
        // "Subset options for the request [sent to a service] include 
        // paramList and displayItemList."
        NodeList serviceInfo = service.getChildNodes();
        for(int i = 0; i < serviceInfo.getLength(); i++){
            Node n = serviceInfo.item(i);
            // Skip non-element nodes
            if(n.getNodeType() != Node.ELEMENT_NODE)
                continue;
            
            Element e = (Element)n;
            
            // Process <displayItem> elements that are *direct* children 
            // of <service>
            if(e.getTagName().equals(GSXML.DISPLAY_TEXT_ELEM)) { 
                // Retrieve values for attributes where name="name", 
                // name="description", name="submit"
                if(e.hasAttributes()) {
                    // get value of attribute where name=name:
                    String attribute = e.getAttribute(GSXML.DISPLAY_TEXT_NAME);
                    // now based on the attribute value set the appropriate var:
                    if(attribute.equals(GSXML.DISPLAY_TEXT_NAME))
                        // get text node of element and get its text
                        nameVal = e.getFirstChild().getNodeValue();
                    // name=description
                    else if(attribute.equals(GSXML.DISPLAY_TEXT_DESCRIPTION))
                        description = e.getFirstChild().getNodeValue();
                    else if(attribute.equals(GSXML.DISPLAY_TEXT_SUBMIT))
                        submit = e.getFirstChild().getNodeValue();// text
                }
            }
            // <paramList> element which contains param elements as children
            else if(e.getTagName().equals(GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER))
            {
                paramList = e;
            } // else skip the element
        }
        
        if(paramList == null) // shouldn't be the case
            return;
        // Now process the parameters contained in the <paramList> element
        
        if(paramList != null && paramList.hasChildNodes()) {
            NodeList nl = paramList.getChildNodes();
            // NodeList nl = paramList.getElementsByTagName(GSXML.PARAM_ELEM);
            if(nl != null && nl.getLength() > 0) {
                Vector 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(GSXML.PARAM_ELEM)) {
                        v.add((Element)n);
                    }   
                }
                paramTags = new QueryFormData[v.size()];
                for(int i = 0; i < paramTags.length; i++) {
                    // we've obtained only elements of <param> type (no 
                    // <option>s among them), so:
                    paramTags[i] = 
                        new QueryFormControl((Element)v.get(i), paramsPanel);
                }
                v.clear();
                v = null;
            }
        }
        
        TitledBorder title = BorderFactory.createTitledBorder(
                nameVal + " - " + description);
        this.setBorder(title);
        // add scrollpane around query form just in case the screen
        // is too small to display all the form controls at once
        this.add(new JScrollPane(paramsPanel), BorderLayout.CENTER);
        this.add(searchButton, BorderLayout.SOUTH);
        searchButton.setText(submit);

        // Setting the search button as the default button so that it may respond
        // to Enter presses in textfields.
        // See http://java.sun.com/docs/books/tutorial/uiswing/components/button.html
        this.getRootPane().setDefaultButton(searchButton);
        
        this.validate(); 
    }
}