root/greenstone3/trunk/resources/java/QBRSOAPServer.java.in @ 16760

Revision 16760, 35.8 KB (checked in by ak19, 12 years ago)

Added import statement for Node as a correction to previous commit: Since greenstone3 core ModuleInterface?.process() now takes a Node and RETURNS a Node, have copied the XMLConverter.nodeToElement() into here to convert the Node back into the Element version of the response.

Line 
1/**
2 *#########################################################################
3 * QBRSOAPServer.java.in: a template for a SOAPServer providing
4 * basic Query, Browse, Retrieve web services for Greenstone 3.
5 * Part of the Greenstone digital library suite from the New Zealand
6 * Digital Library Project at the University of Waikato, New Zealand.
7 * <BR><BR>
8 * Copyright (C) 2008 New Zealand Digital Library Project
9 * <BR><BR>
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
14 * <BR><BR>
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU General Public License for more details.
19 * <BR><BR>
20 * @author ak19
21 * based on Katherine Don's SOAPServer@sitename@ template file.
22 *########################################################################
23 */
24
25package org.greenstone.gsdl3;
26
27import java.io.File;
28import java.io.InputStream;
29
30import java.util.Properties;
31import java.util.Enumeration;
32import java.util.Map;
33import java.util.Map.Entry;
34import java.util.HashMap;
35import java.util.Set;
36import java.util.Iterator;
37
38import org.w3c.dom.Document;
39import org.w3c.dom.Element;
40import org.w3c.dom.NodeList;
41import org.w3c.dom.Node;
42
43import org.greenstone.gsdl3.core.MessageRouter;
44import org.greenstone.gsdl3.util.GlobalProperties;
45import org.greenstone.gsdl3.util.GSFile;
46import org.greenstone.gsdl3.util.GSXML;
47import org.greenstone.gsdl3.util.XMLConverter;
48
49import org.apache.log4j.Logger; // Import log4j classes
50
51/*
52 * Add to $GSDLHOME/web/WEB-INF/server-config.wsdd:
53 * <service name="GS3WebServices" provider="java:RPC">
54 * <parameter name="allowedMethods" value="*"/>
55 * <parameter name="className" value="org.greenstone.gs3services.GS3WebServices"/>
56 * </service>
57*/
58
59/** Class that provides the basic Query, Browse and Retrieve (QBR) web service
60 * operations for Greenstone 3.
61 * It contains a MessageRouter that carries out all the tasks by calling the
62 * appropriate Greenstone functionality for each request message passed to it,
63 * and returning a response message.
64 * 
65 * All response messages are returned from the MessageRouter to clients invoking   
66 * the web services. All return values are strings that represent XML messages.
67 *
68 * Method help() reads from the file QBRWebServicesHelp.properties to list the web
69 * service operations available. Method helpWithMethod(String methodName)
70 * reads from the same file to display a description of the requested operation.
71 * (These method descriptions are mostly the same as those in the Javadoc
72 * comments.)
73 *
74 * NOTE: The folder containing this web service class' properties helpFile
75 * should be on the classpath. (QBRWebServicesHelp.properties)
76 * @author ak19
77*/
78public class QBRSOAPServer@sitename@ {
79    /** site_name the MessageRouter works with, here set to "localsite" */
80    protected String site_name = "@sitename@";
81
82    /** Message Router object to pass requests messages to and which
83     * will process them.*/
84    protected MessageRouter mr = null;
85   
86    /** Container Document to create XML Nodes */
87    protected Document doc=null;
88    /** A converter class to parse XML and create Docs */
89    protected XMLConverter converter=null;
90
91    /** The Logger for this class */
92    private static Logger LOG = Logger.getLogger(QBRSOAPServer@sitename@.class);
93   
94    /** Error message loading helpFile. Remains at "" if everything is fine */
95    protected static String helpErrormessage = "";
96    /** Properties map with mappings from methodname to help
97     * description string. */
98    protected static Properties properties;
99    /** The help properties file describing the web service operations */
100    protected static String helpFile = "QBRWebServicesHelp.properties";
101   
102    // static code block to initialise the help Properties from the helpFile
103    static {
104        properties = new Properties();
105        // load the properties file from a location with respect to the
106        // the Web Service .class file
107        InputStream input = null;
108        try {   
109            // load the properties file from a location with respect to the
110            // the Web Service .class file
111            input
112            = QBRSOAPServer@sitename@.class.getClassLoader().getResourceAsStream(
113                    helpFile);
114            if(input == null) {
115                helpErrormessage = "Cannot find file " + helpFile + " to load.";
116                LOG.warn(helpErrormessage);
117            } else {
118                properties.load(input);
119                input.close();
120            }
121        } catch(Exception e) {
122            helpErrormessage = "Exception loading properties from help file "
123                + helpFile + "\n" + e.getMessage();
124            LOG.warn("Exception loading properties from help file "
125                + helpFile + "\n" + e.getMessage());
126        }
127    }
128   
129   
130    /* Describe subset options for the various Greenstone3 modules */
131    protected static final String mrSubsetOptions = // messageRouter
132        "collectionList serviceClusterList serviceList siteList";
133    protected static final String csSubsetOptions = // collections and serviceClusters
134        "metadataList serviceList displayItemList";
135    protected static final String serviceSubsetOptions = // services
136        "paramList displayItemList";
137    protected static final String docStructureOptions =
138        "entire ancestors parent siblings children descendants"; // note the spelling
139    protected static final String docStructureInfo =
140        "numSiblings siblingPosition numChildren";
141    protected static final String browseStructureOptions =
142        "ancestors parent siblings children descendants"; // note the spelling
143   
144       
145    /** Constructor that initializes the web services' MessageRouter object
146     * Reads from GlobalProperties to get gsdl3_home and set the sitename. */
147    public QBRSOAPServer@sitename@() {
148        String gsdl3_home = GlobalProperties.getGSDL3Home();
149        if (gsdl3_home == null || gsdl3_home.equals("")) {
150            LOG.error(
151                "Couldn't access GSDL3Home from GlobalProperties.getGSDL3HOME,"
152                + "can't initialize the SOAP Server.");
153            return;
154        }
155       
156        String site_home = GSFile.siteHome(gsdl3_home, this.site_name);
157       
158        File site_file = new File(site_home);
159        if (!site_file.isDirectory()) {
160            LOG.error("The site directory "+site_file.getPath()
161                +" doesn't exist. Can't initialize the SOAP Server.");
162            return;
163        }
164        this.converter = new XMLConverter();
165        this.doc = this.converter.newDOM();
166       
167        mr = new MessageRouter();
168        mr.setSiteName(this.site_name);
169        mr.configure();
170    }
171   
172    /* (1) DESCRIBE MESSAGES, manual pages 35-41 */
173    /** Sends a describe message to the MessageRouter.
174     * @param lang is the language of the display content in the response.
175     * @param subsetOption are the requested list of items to return in the
176     * response. For the Message Router this can be collectionList,
177     * serviceClusterList, serviceList, siteList
178     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
179    */
180    public String describe(String lang, String subsetOption)
181    {
182        return describe("", lang, subsetOption, mrSubsetOptions);
183    }
184   
185    /** For sending Describe messages to ServiceClusters.
186     * @param serviceCluster is the name of the Service Cluster that this describe
187     * request is sent to.
188     * @param lang is the language of the display content in the response
189     * @param subsetOption is the requested list of items to return in the response
190     * For Service Clusters this can be metadataList, serviceList, displayItemList.
191     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
192     */
193    public String describeServiceCluster(
194            String serviceCluster, String lang, String subsetOption)
195    {
196        return describe(serviceCluster, lang, subsetOption, csSubsetOptions);
197    }
198   
199    /** For sending Describe messages to Collections.
200     * @param collection is the name of the Collection that this describe request
201     * is sent to.
202     * @param lang is the language of the display content in the response
203     * @param subsetOption is the requested list of items to return in the response
204     * For Collections this can be metadataList, serviceList and displayItemList.
205     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
206     */
207    public String describeCollection(
208            String collection, String lang, String subsetOption)
209    {
210        return describe(collection, lang, subsetOption, csSubsetOptions);
211    }
212   
213    /**
214     * For sending a describe message to a Collection's Service.
215     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
216     * @param collection is the name of the Collection whose service
217     * this describe request is sent to.
218     * @param service is the name of the Service (of that collection) to
219     * which this describe request is sent.
220     * @param lang is the language of the display content in the response
221     * @param subsetOption is the requested list of items to return in the response
222     * For Services this can be paramList, displayItemList */
223    public String describeCollectionService(String collection, String service,
224            String lang, String subsetOption)
225    {
226        return describe(collection + "/" + service,
227                lang, subsetOption, serviceSubsetOptions);
228    }
229   
230    /**
231     * For sending a describe message to a Service hosted by the Message Router
232     * (no collection).
233     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
234     * @param service is the name of the MessageRouter's Service to which this
235     * describe request is sent.
236     * @param lang is the language of the display content in the response
237     * @param subsetOption is the requested list of items to return in the response
238     * For Services this can be paramList, displayItemList
239    */
240    public String describeService(
241            String service, String lang, String subsetOption)
242    {
243        return describe(service, lang, subsetOption, serviceSubsetOptions);
244    }
245   
246    /** For sending a describe message.
247     * If public, this method would give full access: a describe message that
248     * lets the user specify all the details of who the receiver is, and what
249     * details are requested.
250     * @param to - the Greenstone module (MessageRouter, Collection,
251     * ServiceCluster or (Collection-)Service to send this describe message to.
252     * (The module asked to describe itself.)
253     * @param lang - the language of the display content in the response.
254     * @param subsetOption - the set of elements of the describe response that
255     * are requested. These vary depending on the GS3 module asked to describe
256     * itself.
257     * @param validSubsetOptions - the list of subsetOptions that are allowed
258     * for the module this describe message is sent to. Parameter subsetOption
259     * has to be among the list of validSubsetOptions.
260     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 35-41</a>
261    */
262    protected String describe(String to, String lang,
263            String subsetOption, String validSubsetOptions)
264    {
265        // Create message element: <message></message>
266        Element message = this.doc.createElement(GSXML.MESSAGE_ELEM);
267        // <message><request lang="en" to="" type="describe" uid="" /></message>
268        Element request = GSXML.createBasicRequest(
269                this.doc, GSXML.REQUEST_TYPE_DESCRIBE, to, lang, "");
270       
271        // Check if only a subset of this Module Interface's data is asked
272        // to be described
273        if(!subsetOption.equals("")) {
274            // Now deal with the value for subset param:
275            // only deal with valid params for subset of to-ModuleInterface
276            if(validSubsetOptions.indexOf(subsetOption) == -1)
277                return error("Invalid List to be described. Choose one of:\n"
278                    + validSubsetOptions);
279           
280            // else, append <paramList>
281            // <param name="subset" value="subsetOption" /></paramList>
282            Element paramList = this.doc.createElement(
283                    GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
284            // append <param name="subset" value=paramValue />
285            // createParam(Document, name, value);
286            // Name needs to be "subset", but this can be either GSXML.SUBSET_PARAM
287            // or GSXML.SYSTEM_SUBSET_ATT. It's the first one probably.
288            paramList.appendChild(GSXML.createParameter(
289                            this.doc, GSXML.SUBSET_PARAM, subsetOption));
290            request.appendChild(paramList);
291        }
292        message.appendChild(request);
293       
294        // Send it off to the Message Router and return the response
295        return this.processInternal(message);
296    }
297
298    /* (2) Process-type message, QUERY-TYPE SERVICES - p.45 */
299    /** For executing a (process-type message) query-type service.
300     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 45</a>
301     * @param collection is the name of the Collection whose query service this 
302     * query-process request is sent to. If "", then the Message Router is assumed.
303     * @param service is the name of the Query Service (of that collection) to 
304     * which  this request is sent.
305     * @param lang is the language of the display content in the response
306     * @param nameToValsMap is a Map of the (fieldname, value) pairs for the
307     * parameters of the query. The field names should be those recognised by
308     * Greenstone 3. That is, the names must exist for the (Collection-)Service Query that this
309     * message is sent To (as given in 'to' argument).
310     * For names of Greenstone-accepted arguments,
311     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Actions_and_Arguments">Greenstone wiki - Actions and Arguments</a>
312    */
313    public String query(String collection, String service,
314            String lang, Map nameToValsMap)
315    {   
316        // <paramList></paramList>
317        Element paramList = this.doc.createElement(
318                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
319        // <param>s: creating parameters of (name, value) pairs
320        Set entrySet = nameToValsMap.entrySet();
321        Iterator i = entrySet.iterator();
322        while(i.hasNext()) {
323            Entry entry = (Entry)i.next();
324            String name = (String)entry.getKey();
325            String value = (String)entry.getValue();
326            paramList.appendChild(GSXML.createParameter(
327                    this.doc, name, value));
328        }
329
330        Element message = this.doc.createElement(GSXML.MESSAGE_ELEM);
331        Element request = GSXML.createBasicRequest(
332                this.doc, GSXML.REQUEST_TYPE_PROCESS,
333                collection+"/"+service, lang, "");
334       
335        request.appendChild(paramList);
336        message.appendChild(request);
337       
338        // Send it off to the Message Router and return the response
339        return this.processInternal(message);   
340    }
341
342        /**
343     * This method is used to perform the most basic query:
344     * it assumes defaults for all other parameters and provides only
345     * the query string. It is built on top of a TextQuery.
346     * @param collection is the Greenstone collection to be searched
347     * @param lang is the preferred language of the display content in
348     * the response to be returned.
349     * @param query is the string to be sought in the Greenstone collection
350     * @return a Greenstone 3 XML response message for the query specifying
351     * the search results.
352     */
353    public String basicQuery(String collection, String lang, String query) {
354        // The basicQuery is built on top of the TextQuery service
355        final String queryService = "TextQuery";
356       
357        // (1) describe request on the TextQuery
358        String queryDescription = describeCollectionService(
359                collection, queryService, "en", "paramList"); // just get paramList
360        //System.out.println(queryDescription);
361       
362        Document doc = this.converter.getDOM(queryDescription);
363        NodeList nl = doc.getElementsByTagName(
364                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
365       
366        Element paramList = null;
367        if(nl.getLength() <= 0) { // no paramList in textQuery description means
368                // no query field either: that means we can't continue
369            return this.error("BasicQuery is not available for this collection"
370                + " as it provides no TextQuery service.");
371        } //else
372       
373        paramList = (Element)nl.item(0);
374        nl = paramList.getElementsByTagName(GSXML.PARAM_ELEM);
375        if(nl.getLength() <= 0) { // no params, means no query field, so return
376            return this.error("BasicQuery is not available for this collection.");
377        }
378       
379        // (2) get the defaults for each parameter and use that to set
380        // the defaults
381        Map params = new HashMap(nl.getLength()); // field name to value map
382        for(int i = 0; i < nl.getLength(); i++) {
383            Element param = (Element)nl.item(i);
384            String paramName = param.getAttribute(GSXML.NAME_ATT);
385            String def = param.getAttribute(GSXML.DEFAULT_ATT);
386            if(def.equals("")) {
387                // if there's no default, the field must want the query String
388                params.put(paramName, query);
389            } else { // there is a default, use the default for this param
390                params.put(paramName, def);
391            }
392        }
393       
394        // (3) Perform the query using defaults and return the response
395        return this.query(collection, queryService, lang, params);
396    }
397
398       
399    /* (3) RETRIEVE PROCESS METHODS - Manual, pp.47-49 */
400    /** DocumentContentRetrieve request sent to a collection's
401     * DocumentContentRetrieve service (see manual, p.48)
402     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 48</a>
403     * @param collection is the name of the Collection whose
404     * DocumentContentRetrieve is requested
405     * @param lang is the language of the display content in the response
406     * @param docNodeIDs is the list of documentNodeIDs for which the
407     * content ought to be retrieved. */
408    public String retrieveDocumentContent(
409            String collection, String lang, String[] docNodeIDs)
410    {
411        // creating <documentNodeList></documentNodeList>
412        Element docNodeList = this.doc.createElement(
413                GSXML.DOC_NODE_ELEM+GSXML.LIST_MODIFIER);
414       
415        // creating subelements: <documentNode nodeID="..." />
416        for(int i = 0; i < docNodeIDs.length; i++) {
417            Element docNode = this.doc.createElement(GSXML.DOC_NODE_ELEM);
418            docNode.setAttribute(GSXML.NODE_ID_ATT, docNodeIDs[i]);
419            docNodeList.appendChild(docNode);
420        }
421
422        Element message = doc.createElement(GSXML.MESSAGE_ELEM);
423        Element request = GSXML.createBasicRequest(
424                doc, GSXML.REQUEST_TYPE_PROCESS,
425                collection+"/DocumentContentRetrieve", lang, "");
426       
427        // create an empty <paramlist /> element (as example in manual)
428        Element paramlist = doc.createElement(
429                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
430       
431        request.appendChild(paramlist);
432        request.appendChild(docNodeList);
433        message.appendChild(request);
434
435        // Send it off to the Message Router and return the response
436        return this.processInternal(message);
437    }
438   
439    /** DocumentStructureRetrieve request sent to a collection's
440     * DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
441     * the entire document structure.
442     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 48, 49</a>
443     * @param collection is the name of the Collection whose
444     * DocumentStructureRetrieve is requested
445     * @param lang is the language of the display content in the response
446     * @param docNodeIDs is the list of documentNodeIDs for which the
447     * entire structure ought to be retrieved. */
448    public String retrieveEntireDocumentStructure(String collection,
449            String lang, String[] docNodeIDs)
450    {
451        return retrieveDocumentStructure(collection, lang, docNodeIDs,
452                new String[] { "entire" }, null);
453    }
454   
455    /** DocumentStructureRetrieve request sent to a collection's
456     * DocumentStructureRetrieve service (manual pp.48, 49) to retrieve
457     * the specified part of the document's structure.
458     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 48, 49</a>
459     * @param collection is the name of the Collection whose
460     * DocumentStructureRetrieve is requested
461     * @param lang is the language of the display content in the response
462     * @param docNodeIDs is the list of documentNodeIDs for which the
463     * structure ought to be retrieved.
464     * @param structure specifies what structure information needs to
465     * be retrieved. The values can be one or more of ancestors, parent,
466     * siblings, children, descendants (<b>note spelling</b>), entire.
467     * @param info - for specifying extra information to be retrieved.
468     * Possible values for info parameters are numSiblings, siblingPosition,
469     * numChildren */
470    public String retrieveDocumentStructure(String collection, String lang,
471            String[] docNodeIDs, String[] structure, String[] info)
472    {
473        // creating subelements: <documentNode nodeID="..." />
474        Element docNodeList = this.doc.createElement(
475                GSXML.DOC_NODE_ELEM+GSXML.LIST_MODIFIER);
476        for(int i = 0; i < docNodeIDs.length; i++) {
477            Element docNode = this.doc.createElement(GSXML.DOC_NODE_ELEM);
478            docNode.setAttribute(GSXML.NODE_ID_ATT, docNodeIDs[i]);
479            docNodeList.appendChild(docNode);
480        }
481       
482        Element message = doc.createElement(GSXML.MESSAGE_ELEM);
483        Element request = GSXML.createBasicRequest(
484                doc, GSXML.REQUEST_TYPE_PROCESS,
485                collection+"/DocumentStructureRetrieve", lang, "");
486       
487        // Create the <paramlist></paramlist> element of param elements,
488        // if any; and only if values are legal (that is, if they occur in 
489        // static Strings docStructureOptions and docStructureInfo):
490        // <param name="structure" value = "structure[i]">
491        // <param name="info" value = "info[i]">
492        Element paramList = doc.createElement(
493                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
494       
495        if(structure != null) {
496            for(int i = 0; i < structure.length; i++) {
497                if(docStructureOptions.indexOf(structure[i]) != -1) {
498                    paramList.appendChild(GSXML.createParameter(
499                            this.doc, "structure", structure[i]));                 
500                }
501            }
502        }
503        if(info != null) {
504            for(int i = 0; i < info.length; i++) {
505                if(docStructureInfo.indexOf(info[i]) != -1) {
506                    paramList.appendChild(GSXML.createParameter(
507                            this.doc, "info", info[i]));
508                }
509            }
510        }
511       
512        // paramList is allowed to be empty and may indeed be empty:
513        request.appendChild(paramList);
514        request.appendChild(docNodeList);
515        message.appendChild(request);
516       
517        // Send it off to the Message Router and return the response
518        return this.processInternal(message);
519    }
520   
521    /* Retrieve for Doc Metadata: explained in the manual on page 47 */
522    /** DocumentMetadataRetrieve request sent to a collection's
523     * DocumentMetadataRetrieve service to retrieve all of a document's metadata.
524     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 47</a>
525     * @param collection is the name of the Collection whose
526     * DocumentMetadataRetrieve is requested
527     * @param lang is the language of the display content in the response
528     * @param docNodeIDs is the list of documentNodeIDs for which the
529     * structure ought to be retrieved.
530    */
531    public String retrieveAllDocumentMetadata(String collection, String lang,
532            String[] docNodeIDs)
533    {
534        // See bottom of manual p.44 for the fact that "all" is used
535        // as the metaName value when retrieving all metadata for a doc
536        return retrieveDocumentMetadata(collection, lang, docNodeIDs,
537                new String[]{ "all" });
538    }
539   
540    /** DocumentMetadataRetrieve service to retrieve some specific
541     * metadata values of a document. (Manual on page 47.)
542     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 47</a>
543     * @param collection is the name of the Collection whose
544     * DocumentContentRetrieve is requested
545     * @param lang is the language of the display content in the response
546     * @param docNodeIDs is the list of documentNodeIDs for which the
547     * structure ought to be retrieved.
548     * @param metaNames is a list of metadata names which are requested 
549     * to be fetched for the specified documents */
550    public String retrieveDocumentMetadata(String collection, String lang,
551            String[] docNodeIDs, String[] metaNames)
552    {
553        return metadataRetrieve(collection+"/DocumentMetadataRetrieve",
554                lang, docNodeIDs, metaNames, GSXML.DOC_NODE_ELEM);
555    }
556
557    /** Retrieve all classification Metadata for browsing (sent to the
558     * ClassifierBrowseMetadataRetrieve service).
559     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 47, 48</a>
560     * @param collection is the name of the Collection whose
561     * ClassifierBrowseMetadataRetrieve service is called
562     * @param categoryName - name of the browsing category, usually
563     * ClassifierBrowse. (If left as "", then it defaults to ClassifierBrowse)
564     * @param lang is the language of the display content in the response
565     * @param nodeIDs is the list of document or classifier NodeIDs
566     * for which the metadata ought to be retrieved.*/
567    public String retrieveAllBrowseMetadata(String collection,
568            String categoryName, String lang, String[] nodeIDs)
569    {
570        if(categoryName.equals(""))
571            categoryName = "ClassifierBrowse";
572        // See bottom of manual p.47 for the fact that "all" is used as
573        // the metaName value when retrieving all metadata for a classifier
574        return metadataRetrieve(collection+"/"+categoryName+"MetadataRetrieve",
575                lang, nodeIDs, new String[]{ "all" }, GSXML.CLASS_NODE_ELEM);
576    }
577   
578    /** ClassifierBrowseMetadataRetrieve service to retrieve some specific
579     * metadata values of a document.
580     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - pages 47, 48</a>
581     * @param collection is the name of the Collection whose
582     * ClassifierBrowseMetadataRetrieve service is called
583     * @param categoryName - name of the browsing category, usually
584     * ClassifierBrowse. (If left as "", then it defaults to ClassifierBrowse)
585     * @param lang is the language of the display content in the response
586     * @param nodeIDs is the list of document or classifier NodeIDs
587     * for which the metadata ought to be retrieved.
588     * @param metaNames is a list of metadata names which are requested 
589     * to be fetched for the specified documents or classifiers */
590    public String retrieveBrowseMetadata(String collection, String categoryName, 
591            String lang, String[] nodeIDs, String[] metaNames)
592    {
593        if(categoryName.equals(""))
594            categoryName = "ClassifierBrowse";
595        return metadataRetrieve(collection+"/"+categoryName+"MetadataRetrieve",
596                lang, nodeIDs, metaNames, GSXML.CLASS_NODE_ELEM);
597    }
598   
599    /** Performs a metadata retrieve for documents and (browse) classification
600     * hierarchies. Sends a Document- or ClassifierBrowse- MetadataRetrieve message
601     * to the Document- or ClassifierBrowse- MetadataRetrieve service.
602     * @param to - the Document- or ClassifierBrowse- MetadataRetrieve service to
603     * send this metadata retrieve message to.
604     * @param lang - the language of the display content in the response
605     * @param nodeIDs - the list of (document or classifier) nodeIDs for which
606     * to retrieve the metadata for
607     * @param metaNames - a list specifiying the names of the metadata items
608     * to be retrieved for each nodeID. E.g. "Title", but a list is allowed.
609     * @param NODE_ELEM - either of GSXML's names for the &lt;documentNode&gt; or
610     * &lt;classifierNode&gt; elements.
611    */
612    protected String metadataRetrieve(String to, String lang,
613            String[] nodeIDs, String[] metaNames, final String NODE_ELEM)
614    {
615        // create the <paramlist></paramlist> element of param elements: 
616        // <param name="metadata" value = "metaName[i]">
617        Element metadataParamList = this.doc.createElement(
618                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
619        for(int i = 0; i < metaNames.length; i++) {
620            metadataParamList.appendChild(GSXML.createParameter(
621                    this.doc, GSXML.METADATA_ELEM, metaNames[i]));
622        }
623       
624        // creating subelements: <documentNode nodeID="..." />
625        // or <classifierNode nodeID="..." />
626        Element nodeList = this.doc.createElement(
627                NODE_ELEM+GSXML.LIST_MODIFIER);
628        for(int i = 0; i < nodeIDs.length; i++) {
629            Element docNode = this.doc.createElement(NODE_ELEM);
630            docNode.setAttribute(GSXML.NODE_ID_ATT, nodeIDs[i]);
631            nodeList.appendChild(docNode);
632        }
633       
634        Element message = doc.createElement(GSXML.MESSAGE_ELEM);
635        Element request = GSXML.createBasicRequest(doc,
636                GSXML.REQUEST_TYPE_PROCESS, to, lang, "");
637       
638        request.appendChild(metadataParamList);
639        request.appendChild(nodeList);
640        message.appendChild(request);
641       
642        // Send it off to the Message Router and return the response
643        return this.processInternal(message);
644    }
645   
646    /* (4) Classifier BROWSE PROCESS METHODS - p.46 */
647    /** To send a browse request for all the descendants of a classifier node.
648     * Useful for getting the entire structure of a top-level &lt;classificationNode&gt;
649     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 46</a>
650     * @param collection is the name of the Collection whose browse Classifier
651     * Browse Service is called
652     * @param browseService is the name of the (Classifier) Browse Service (of
653     * the given collection) to which this request message is sent.
654     * @param lang is the language of the display content in the response
655     * @param classifierNodeIDs is an array of classifierNodeIDs for which the
656     * structures ought to be retrieved.
657    */
658    public String browseDescendants(String collection, String browseService,
659            String lang, String[] classifierNodeIDs)
660    {
661        // We are at the top level, we want all the descendants:
662        // <param name="structure" value = "descendants">
663        // <classifierNodeList><classifier nodeID="CLx" /></classifierNodeList>
664        return browse(collection, browseService, lang,   
665                classifierNodeIDs,
666                new String[] {"descendants"}); // note the spelling
667    }
668   
669    /** To send a browse request for specific parts of a classifier node
670     * (children, ancestors, descendants). Useful for getting specific parts
671     * of the structure of a top-level &lt;classificationNode&gt;.
672     * @see <a href="http://wiki.greenstone.org/wiki/index.php/Greenstone3">The Greenstone 3 Developer's Manual - page 46</a>
673     * @param collection is the name of the Collection whose browse Classifier
674     * Browse Service is called
675     * @param browseService is the name of the (Classifier) Browse Service (of
676     * the given collection) to which this request message is sent.
677     * @param lang is the language of the display content in the response
678     * @param classifierNodeIDs is the list of classifierNodeIDs for which the
679     * structure ought to be retrieved.
680     * @param structureParams the list of parameters indicating what structure
681     * information is requested. Accepted values are ancestors, parent, siblings,
682     * children, descendants.
683    */
684    public String browse(String collection, String browseService, String lang,
685            String[] classifierNodeIDs, String[] structureParams)
686    {
687        if(browseService.equals(""))
688            browseService = "ClassifierBrowse";
689       
690        // Create message element: <message></message>
691        Element message = this.doc.createElement(GSXML.MESSAGE_ELEM);
692        // <message><request lang="en" to="" type="process" uid="" /></message>
693        Element request = GSXML.createBasicRequest(this.doc,
694            GSXML.REQUEST_TYPE_PROCESS, collection+"/"+browseService, lang, "");
695       
696        // <param name="structure" value = "structureParams[i]">
697        Element paramList = this.doc.createElement(
698                GSXML.PARAM_ELEM+GSXML.LIST_MODIFIER);
699        for(int i = 0; i < structureParams.length; i++) {
700            // check it is a valid structure parameter
701            if(browseStructureOptions.indexOf(structureParams[i]) != -1) {
702                paramList.appendChild(GSXML.createParameter(
703                        this.doc, "structure", structureParams[i]));
704            }
705        }
706       
707        // <classifierNodeList><classifier nodeID="CLx" />
708        //      <classifier nodeID="CLy" /></classifierNodeList>
709        // where CLx and CLy are given in the parameter classifierNodeIDs
710        Element classifierNodeList = this.doc.createElement(
711                GSXML.CLASS_NODE_ELEM+GSXML.LIST_MODIFIER);
712        for(int i = 0; i < classifierNodeIDs.length; i++) {
713            Element classifier = this.doc.createElement(GSXML.CLASS_NODE_ELEM);
714            classifier.setAttribute(GSXML.NODE_ID_ATT, classifierNodeIDs[i]);
715            classifierNodeList.appendChild(classifier);
716        }
717       
718        // now finish constructing the request message:
719        request.appendChild(paramList);
720        request.appendChild(classifierNodeList);
721        message.appendChild(request);
722       
723        // Send it off to the Message Router and return the response
724        return this.processInternal(message);
725    }
726   
727    /** Called by most other methods in order to send the constructed message
728     * to the Greenstone's MessageRouter, intercept the response and return it.
729     * @param message is the XML message Element to send to GS3's MessageRouter.
730     * @return the XML response in String format. */
731    protected String processInternal(Element message) {
732            if(LOG.isDebugEnabled()) { // or LOG.isEnabledFor(Level.DEBUG).
733                                   // Testing for this improves efficiency
734            LOG.debug(this.converter.getPrettyString(message));
735        }
736       
737        // Let the messagerouter process the request message and get the response
738        Element response = converter.nodeToElement(mr.process(message));
739              // won't be null except when Node returned is not an element
740              // otherwise, MR always returns some response
741
742        // Return it as a String formatted for display
743        String responseMsg = this.converter.getPrettyString(response);
744                          // this.converter.getString(response);
745
746        // In order to avoid "Content is not allowed in prolog" exception on the
747        // web services' client end (problem encountered in GS mailing list), need
748        // to make sure no characters (incl spaces) preceed the  XML sent back
749        // from here. It may also require the <?xml?> tag at the very start.
750        if(responseMsg.charAt(0) == ' ') {
751            responseMsg = responseMsg.trim();
752        }
753       
754        return "<?xml version=\"1.0\" encoding=\"utf-8\"?>"+responseMsg;
755    }
756   
757    /** Creates a String response message to represent an XML error response 
758     * message using the error specified in the message parameter. A String is
759     * created because this method ensures that a response message is reliably
760     * constructed (no exceptions are thrown) that can be sent to clients.
761     * @param errorMessage - the errormessage to be conveyed
762     * @return an XML response message containing an GS3 error element. */
763    protected String error(String errorMessage) {
764        StringBuffer buf = new StringBuffer("<" + GSXML.MESSAGE_ELEM + ">");
765        buf.append("<" + GSXML.RESPONSE_ELEM + " "
766                + GSXML.FROM_ATT + "=\"" + "Greenstone 3 Web Services\"" + ">");
767        buf.append("<" + GSXML.ERROR_ELEM + " "
768            + GSXML.ERROR_TYPE_ATT + "=\""+ GSXML.ERROR_TYPE_OTHER + "\"" + ">");
769        buf.append(errorMessage+"\n");
770        buf.append("</" + GSXML.ERROR_ELEM + ">");
771        buf.append("</" + GSXML.RESPONSE_ELEM + ">");
772        buf.append("</" + GSXML.MESSAGE_ELEM + ">");
773        return buf.toString();
774    }
775
776    /*
777    Look in file QBRWebServicesHelp.properties
778    - Have a properties file that maps methodname to help string specific
779    to the method.
780    - Read it all in statically at the start of the class, into a Properties Map.
781    - When this method is called, display the usage: "help methodname"
782    and list all the available methods by going over the keys in the Map.
783    - When the helpWithMethod(String methodname) method is called, return the
784    value of the Map for the methodname key. This value would be the help
785    description for that method.       
786    */
787    /** @return a help string for listing all the web service methods. */
788    public static String help() {
789        if(!helpErrormessage.equals("")) {
790            return helpErrormessage;
791        }
792       
793        StringBuffer helpString = new StringBuffer(
794                "USAGE: helpWithMethod(String <method name>)\n");
795        helpString.append(
796                "\nNearly all the web service operations return a String\n");
797        helpString.append(
798                "representing a Greenstone 3 XML response message.\n");
799        helpString.append("\nA list of all the method names: \n");
800       
801        Enumeration props = properties.keys();
802        while(props.hasMoreElements()){
803            String methodName = (String)props.nextElement();
804            helpString.append("\t");
805            helpString.append(methodName);
806            helpString.append("\n");
807        }
808       
809        return helpString.toString();
810    }
811   
812    /** @param methodname is the name of the method to be described. 
813     * @return a help string for the given method, explaining what the method
814     * does, what parameters it expects and their types and what it returns.
815    */
816    public static String helpWithMethod(String methodname) {
817        if(!helpErrormessage.equals("")) {
818            return helpErrormessage;
819        }
820        // else we can get the method's description from the properties
821        // map loaded from the QBRWebServicesHelp.properties file:
822        String helpString = properties.getProperty(methodname,
823            "No description for " + methodname); // if the method does not exist
824       
825        return helpString;
826    }
827} // end web service class
Note: See TracBrowser for help on using the browser.