source: trunk/gsdl3/src/java/org/greenstone/gsdl3/service/ServiceModule.java@ 3471

/*
 *    ServiceModule.java
 *    Copyright (C) 2002 New Zealand Digital Library, http://www.nzdl.org
 *
 *    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.
 *
 *    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.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
package org.greenstone.gsdl3.service;

// greenstone classes
import org.greenstone.gsdl3.util.*;
import org.greenstone.gsdl3.core.*;

// xml classes
import org.w3c.dom.Node; 
import org.w3c.dom.Element; 
import org.w3c.dom.Document; 
import org.xml.sax.InputSource;
import javax.xml.parsers.*;
import org.apache.xpath.XPathAPI;

// general java classes
import java.io.Reader;
import java.io.StringReader;
import java.io.File;
import java.util.HashMap;

/**
 * ServiceModule - abstract base class 
 *
 * A ServiceModule provides Services to a collection/cluster/site. 
 * It may provide more than one Service. for eg
 * MGGDBMServiceModule may support "DocRetrieve", "TextQuery", "MetadataRetrieve" services
 *
 * @author <a href="mailto:[email protected]">Katherine Don</a>
 * @version $Revision: 3471 $
 */
public abstract class ServiceModule 
    implements ModuleInterface
{


    /** the absolute address of the site home */
    protected String site_home_ =null;
    /** the name of the cluster that this service belongs to -
    if any */ 
    protected String cluster_name_ = null;

    /** some services can talk back to the message router */
    protected ModuleInterface router_ = null;

    /** a converter class to create Documents etc */
    protected XMLConverter converter_ = null;

    /** XML element for describe requests - the container doc */
    protected Document doc_ = null;

    /** XML element for describe requests - list of supported services */
    protected Element short_service_info_ = null;

    /** XML element for describe requests - map of service name to full 
    description */
    protected HashMap service_info_map_ = null;

    /** sets the cluster name */
    public void setClusterName(String cluster_name) {
    cluster_name_ = cluster_name;
    }
    /** sets the collect name */
    public void setCollectionName(String coll_name) {
    setClusterName(coll_name);
    }
    
    /** sets the site home */
    public void setSiteHome(String site_home) {
    site_home_ = site_home;
    }

    /** sets the message router */
    public void setMessageRouter(ModuleInterface m) {
       router_ = m;
    }

    /** the no-args constructor */
    public ServiceModule() {
    converter_ = new XMLConverter();
    doc_ = converter_.newDOM();
    short_service_info_ = doc_.createElement("serviceList");
    service_info_map_ = new HashMap();
    }
    

    /** configure the service module
     *
     * @param info the XML node <serviceModule name="XXX"/> with name equal
     * to the class name (of the subclass)
     *
     * must initialise short_service_info_ and service_info_map_
     * @return true if configured ok
     * must be implemented in subclasses
     */
    abstract public boolean configure(Element info); 

    /**
     * Process an XML document - convenience method that uses Strings rather than Nodes. just calls process(Node).
     *
     * @param xml_in the Document to process - a string
     * @return the resultant document as a string - contains any error messages
     * @see String
     */
    public String process(String xml_in) {
    
    Document doc = converter_.getDOM(xml_in);
    
    Node res = process(doc);
    return converter_.getString(res);
    
    }

    /** process an XML request in DOM form
     *
     * @param xml_in the Element node containing the request
     * should be <request> or maybe <multipleRequest>?? if more than one 
     * request coming at once
     * @return an Element with the result XML
     * @see Element
     */
    public Node process(Node xml_in) {

    // check if request is Element or Document - we want to work 
    // with an Element
    Element request=null;

    short node_type = xml_in.getNodeType();
    if (node_type == Node.DOCUMENT_NODE) {
        request = ((Document)xml_in).getDocumentElement();
    } else if (node_type == Node.ELEMENT_NODE) {
        request = (Element)xml_in;
    } else {
        System.err.println("ServiceModule:process error: input should be an Element or Document!");
    }

    String req = request.getNodeName();
    if (!req.equals("request")) {
        System.err.println("ServiceModule:process - should have been passed a request element, instead was given a "+req+" element!");
        return null;
    }

    String type = request.getAttribute("type");
    String to = GSPath.getFirstLink(request.getAttribute("to"));
    String info = request.getAttribute("info");
    if (type.equals("describe")) { // process here, not by subclass
        Element response = doc_.createElement("response");
        response.setAttribute("type", "describe");
        if (to.equals("")) { // to="", look at info
        if (info.equals("serviceList")) {
            response.appendChild(short_service_info_);
            return response;
        } 
        // else error in info field
        System.err.println("ServiceModule describe request: error in 'info' field, info='"+info+"'.");
        return null;
        } else { // describe a particular service
        if (service_info_map_.containsKey(to)) {
            response.appendChild((Element)service_info_map_.get(to));
            return response;
        }
        // else error in to field
        System.err.println("ServiceModule describe request: error in 'to' field, to='"+to+"'.");
        return null;
        }
    } else { // other type of request, must be processed by the subclass - 
        // send to the service method
        if (service_info_map_.containsKey(to)) { 
        return processService(to, request);
        }
        else {
        // else error in to field
        System.err.println("ServiceModule describe request: error in 'to' field, to='"+to+"'.");
        return null;
        }
    }
    
    }

    /** process method for specific services - must be implemented by all
     * subclasses
     * should implement all services supported by the serviceModule except
     * for describe, which is implemented by this base class
     *
     */
    abstract protected Element processService(String service, Element request);


}