source: main/trunk/greenstone3/resources/java/QBRSOAPServer.java.in@ 31978

Last change on this file since 31978 was 31978, checked in by kjdon, 3 years ago

fixed this up so that it compiles, and got rid of this.doc

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