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

Last change on this file since 15222 was 15222, checked in by ak19, 16 years ago

Greenstone3 web services demo-clientadded to GS3's other-projects
File size: 11.9 KB
Line 
1/**
2 *#########################################################################
3 * DigitalLibraryServicesAPIA.java - part of the demo-client for
4 * Greenstone 3, of the Greenstone digital library suite from the New
5 * Zealand Digital Library Project at the * University of Waikato,
6 * 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 *########################################################################
20 */
21
22package org.greenstone.gs3client.dlservices;
23
24import java.util.Map;
25import org.greenstone.gs3client.data.DocumentNodeData;
26
27/** Interface that defines the digital library methods that need to be
28 * provided by a digital library that's going to be incorporated into the
29 * Greenstone Java-Client, so that the client may be able to use/access
30 * its functionality.
31 *
32 * Note that the Strings returned by all defined methods -- with the exception
33 * of getLanguage() -- represent Greenstone3 XML response messages, as defined
34 * in the Greenstone3 manual.
35 * These methods do not throw exceptions, but rather embed any error information
36 * in the XML Strings returned, as is done in Greenstone3 XML response
37 * messages.
38 *
39 * The final 'A' of DigitalLibraryServicesAPIA stands for Access, as the
40 * methods defined here are to give access to a digital library's repository.
41 * @author ak19
42*/
43public interface DigitalLibraryServicesAPIA {
44 /** The properties file containing the initial digital library connection
45 * settings which get displayed in the connection dialog fields */
46 public static final java.io.File propertiesFile
47 = new java.io.File("gs3democlient.properties");
48
49 /** If there's a dialog, then the CancelException can be used to indicate
50 * that the user cancelled out of it rather than having seen it through.
51 */
52 public class CancelException extends Exception {
53 public CancelException() { super(); }
54 public CancelException(String message) { super(message); }
55 public CancelException(Throwable cause) { super(cause); }
56 public CancelException(String message, Throwable cause) {
57 super(message, cause);
58 }
59 }
60
61 //public static String displayName = "<insert DL name>";
62
63 /** @return the name of this digital library for displaying in the client */
64 public String getDisplayName();
65
66 /*@return the URL of the server - this would generally form the basis of the
67 * overall url location of where associated files are stored. */
68 //public String getBaseURL();
69
70 /** @return the overall directory path for associated files (not including
71 * the document's nodeID/pid). This can be used to formulate the base url of
72 * JEditorPane's HTML documents. If the documents from any digital library
73 * do not contain relative paths, or otherwise deal with the resolution of
74 * relative urls themselves, then return "" from here. */
75 public String getAssocFileBaseURL();
76
77 /* @return any string prefixed to associated files like images. This will
78 * generally be "", but in Fedora's case, associated images of the
79 * Greenstone documents stored in there start with "FG". */
80 //public String getAssocFilePrefix();
81
82 /** @return the directory path to the associated files of the given document
83 * node. For instance, the base url of a JEditorPane's HTML documents can be
84 * set to this. */
85 public String getAssocFileBaseURL(DocumentNodeData docNode);
86
87 /** Sets the preferred language (code) for metadata and other content to be
88 * returned on request messages. If the preferred language is not available,
89 * the implementation may choose to send English back instead, or failing
90 * that, send the data in any other available language.
91 * @param language has to be a language code as recognised by Greenstone3
92 * (the language codes used by W3C probably). E.g. "en" for English. */
93 public void setLanguage(String language);
94
95 /** Gets the language that's set as the preferred language.
96 * @return the language code as recognised by Greenstone3 (which are the
97 * language codes used by W3C probably). E.g. "en" for English. */
98 public String getLanguage();
99
100 /** @return Greenstone3 XML describe response message with information
101 * about collections contained and services (and any serviceRacks) supported
102 * by the Digital library. */
103 public String describe();
104
105 /** @return Greenstone3 XML describe response message originating from a
106 * collection, describing the collection (display items) as well as
107 * listing any services supported specifically by the collection.
108 * @param collection is the name of the collection to be described */
109 public String describeCollection(String collection);
110
111 /** @return Greenstone3 XML describe response message originating from a
112 * collection's service, describing the service (display items).
113 * @param collection is the name of the collection to be described
114 * @param service is the name of the collection's service to be described */
115 public String describeCollectionService(String collection, String service);
116
117 /** @return Greenstone3 XML describe response message originating from a
118 * general (non-collection specific) service, describing the requested
119 * service (for example with GS3 display items).
120 * @param service is the name of the collection's service to be described */
121 public String describeService(String service);
122
123 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
124 * containing all the metadata of all the documents indicated by docIDs
125 * @param collection is the name of the collection
126 * @param docIDs is an array of document identifiers of documents whose
127 * metadata is requested */
128 public String retrieveDocumentMetadata(String collection, String[] docIDs);
129
130 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
131 * containing all the metadata of the document denoted by docID
132 * @param collection is the name of the collection
133 * @param docID is the document identifier of the document whose metadata is
134 * requested */
135 public String retrieveDocumentMetadata(String collection, String docID);
136
137 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
138 * containing only the title metadata of the documents denoted by docIDs
139 * @param collection is the name of the collection
140 * @param docIDs is an array of document identifiers of documents whose titles
141 * are requested */
142
143 public String retrieveTitleMetadata(String collection, String[] docIDs);
144 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
145 * containing only the title metadata of the document denoted by docID
146 * @param collection is the name of the collection
147 * @param docID is the document identifier of the document whose titles is
148 * requested */
149 public String retrieveTitleMetadata(String collection, String docID);
150
151 /** @return a String representing Greenstone3 DocumentContentRetrieve XML
152 * containing the document contents of the documents indicated by docIDs
153 * @param collection is the name of the collection
154 * @param docIDs is an array of document identifiers of documents whose (text)
155 * contents are requested */
156 public String retrieveDocumentContent(String collection, String[] docIDs);
157
158 /** @return a String representing Greenstone3 DocumentContentRetrieve XML
159 * containing the document contents of the document indicated by docID
160 * @param collection is the name of the collection
161 * @param docID is the document identifier of the document whose (text)
162 * content is requested */
163 public String retrieveDocumentContent(String collection, String docID);
164
165 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
166 * containing the document structure of the documents indicated by docIDs:
167 * this means all their descendents
168 * @param collection is the name of the collection
169 * @param docIDs is an array of document identifiers of documents whose
170 * hierarchical structures are requested */
171 public String retrieveDocumentStructure(String collection, String[] docIDs);
172
173 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
174 * containing the document structure of the document indicated by docID:
175 * this means all its descendents
176 * @param collection is the name of the collection
177 * @param docID is the document identifier of the document whose hierarchical
178 * structure is requested*/
179 public String retrieveDocumentStructure(String collection, String docID);
180
181 // UNUSED by the client, but still a very useful method:
182 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
183 * containing a view of the document structure of the documents denoted by
184 * docs where only the requested documents and their direct children are
185 * returned.
186 * @param collection is the name of the collection
187 * @param docIDs is an array of document identifiers of documents whose
188 * hierarchical structures are requested */
189 public String retrieveDocumentChildren(String collection, String[] docIDs);
190
191 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
192 * containing a view of the document structure of the document denoted by
193 * docID where only the document and its direct children are returned.
194 * @param collection is the name of the collection
195 * @param docID is an document identifier of the document whose hierarchical
196 * structure is requested */
197 public String retrieveDocumentChildren(String collection, String docID);
198
199 /** @return a String representing Greenstone3 ClassifierBrowse XML
200 * giving the entire *structure* of the classification denoted by
201 * classifierID (including the structures of document descendents of
202 * the classifier).
203 * @param classifierID is of the form CL# where the number (#) marks
204 * out structured sections like CL1.1.3 or CL2
205 * @param collection is the name of the collection
206 * @param service is the name of the browse service (=ClassifierBrowse usually)
207 */
208 public String retrieveBrowseStructure(
209 String collection, String service, String classifierID);
210
211 /** @return a String representing Greenstone3
212 * ClassifierBrowseMetadataRetrieve XML giving all the metadata for
213 * all the subclassifiers denoted by nodeIDs.
214 * @param nodeIDs is of the form CL#.# where the number (#) marks
215 * out structured sections like CL2.1.3. NodeIDs are generally subsections
216 * of top-level classifierNodes (CL#, e.g. CL3).
217 * @param collection is the name of the collection
218 * @param service is the name of the Browse's MetadataRetrieve service
219 * (usually the browse service is ClassifierBrowse, in which case it always
220 * has a retrieve service called ClassifierBrowseMetadataRetrieve) */
221 public String retrieveBrowseMetadata(
222 String collection, String service, String[] nodeIDs);
223
224 /** @return a String representing Greenstone3 XML for a query process
225 * response returning the results for the query denoted by parameter
226 * nameValParamsMap.
227 * @param nameValParamsMap is a Map of name and value pairs for all the
228 * query field data values. The names match the field names that
229 * describeCollectionService() would have returned for the query service.
230 * @param collection is the name of the collection
231 * @param service is the name of the query service
232 * This method is only ever called when any of the services in the digital
233 * library described themselves as type=query. Therefore any digital
234 * libraries that have no query services, can just return emtpy message
235 * strings (or even "") since this method will never be called on them
236 * anyway. */
237 public String query(String collection, String service,
238 Map nameValParamsMap);
239}
Note: See TracBrowser for help on using the repository browser.