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

Last change on this file since 22298 was 22298, checked in by ak19, 14 years ago

Changes to get Fedora to work with Greenstone3: to let the Greenstone3 Reader Interface work with a Fedora Repository behind the scenes.
File size: 14.1 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 * @param metadata is the list of metadata elements to be retrieved for each doc */
129 public String retrieveDocumentMetadata(String collection, String[] docIDs, String[] metadata);
130
131 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
132 * containing all the metadata of the document denoted by docID
133 * @param collection is the name of the collection
134 * @param docID is the document identifier of the document whose metadata is
135 * requested
136 * @param metadata is the list of metadata elements to be retrieved for each doc */
137 public String retrieveDocumentMetadata(String collection, String docID, String[] metadata);
138
139 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
140 * containing only the title metadata of the documents denoted by docIDs
141 * @param collection is the name of the collection
142 * @param docIDs is an array of document identifiers of documents whose titles
143 * are requested */
144
145 public String retrieveTitleMetadata(String collection, String[] docIDs);
146 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
147 * containing only the title metadata of the document denoted by docID
148 * @param collection is the name of the collection
149 * @param docID is the document identifier of the document whose titles is
150 * requested */
151 public String retrieveTitleMetadata(String collection, String docID);
152
153 /** @return a String representing Greenstone3 DocumentContentRetrieve XML
154 * containing the document contents of the documents indicated by docIDs
155 * @param collection is the name of the collection
156 * @param docIDs is an array of document identifiers of documents whose (text)
157 * contents are requested */
158 public String retrieveDocumentContent(String collection, String[] docIDs);
159
160 /** @return a String representing Greenstone3 DocumentContentRetrieve XML
161 * containing the document contents of the document indicated by docID
162 * @param collection is the name of the collection
163 * @param docID is the document identifier of the document whose (text)
164 * content is requested */
165 public String retrieveDocumentContent(String collection, String docID);
166
167 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
168 * containing the document structure of the documents indicated by docIDs:
169 * this means all their descendents
170 * @param collection is the name of the collection
171 * @param docIDs is an array of document identifiers of documents whose
172 * hierarchical structures are requested */
173 public String retrieveDocumentStructure(String collection, String[] docIDs);
174
175 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
176 * containing the document structure of the document indicated by docID:
177 * this means all its descendents
178 * @param collection is the name of the collection
179 * @param docID is the document identifier of the document whose hierarchical
180 * structure is requested */
181 public String retrieveDocumentStructure(String collection, String docID);
182
183
184 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
185 * containing the requested portion of the document structure of the documents
186 * indicated by docIDs:
187 * @param collection is the name of the collection
188 * @param docIDs is an array of document identifiers of documents whose
189 * hierarchical structures are requested
190 * @param structure - strings specifying the required structure of each document.
191 * It can be a combination of: ancestors, parent, siblings, children, descendants, entire.
192 * @param info - strings specifying the required structural info of each document.
193 * It can be any combination of: siblingPosition, numSiblings, numChildren.
194 */
195 public String retrieveDocumentStructure(String collection, String[] docIDs, String[] structure, String[] info);
196
197
198 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
199 * containing the requested portion of the document structure of the documents
200 * indicated by docIDs:
201 * @param collection is the name of the collection
202 * @param docID is the document identifier of the document whose hierarchical
203 * structure is requested
204 * @param structure - strings specifying the required structure of the document.
205 * It can be a combination of: ancestors, parent, siblings, children, descendants, entire.
206 * @param info - strings specifying the required structural info of the document.
207 * It can be any combination of: siblingPosition, numSiblings, numChildren.
208 */
209 public String retrieveDocumentStructure(String collection, String docID, String[] structure, String[] info);
210
211
212 // UNUSED by the client, but still a very useful method:
213 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
214 * containing a view of the document structure of the documents denoted by
215 * docs where only the requested documents and their direct children are
216 * returned.
217 * @param collection is the name of the collection
218 * @param docIDs is an array of document identifiers of documents whose
219 * hierarchical structures are requested */
220 public String retrieveDocumentChildren(String collection, String[] docIDs);
221
222 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
223 * containing a view of the document structure of the document denoted by
224 * docID where only the document and its direct children are returned.
225 * @param collection is the name of the collection
226 * @param docID is an document identifier of the document whose hierarchical
227 * structure is requested */
228 public String retrieveDocumentChildren(String collection, String docID);
229
230 /** @return a String representing Greenstone3 ClassifierBrowse XML
231 * giving the entire *structure* of the classification denoted by
232 * classifierID (including the structures of document descendents of
233 * the classifier).
234 * @param classifierIDs - each ID is of the form CL# where the number (#)
235 * marks out structured sections like CL1.1.3 or CL2
236 * @param collection is the name of the collection
237 * @param service is the name of the browse service (=ClassifierBrowse usually)
238 * @param structure - the requested browse substructure. Can be any combination
239 * of ancestors, parent, siblings, children, descendants.
240 * @param info - the requested structural info. Can be numSiblings, siblingPosition,
241 * numChildren
242 */
243 public String retrieveBrowseStructure(String collection, String service,
244 String[] classifierIDs, String[] structure, String[] info);
245
246 /** @return a String representing Greenstone3
247 * ClassifierBrowseMetadataRetrieve XML giving all the metadata for
248 * all the subclassifiers denoted by nodeIDs.
249 * @param nodeIDs is of the form CL#.# where the number (#) marks
250 * out structured sections like CL2.1.3. NodeIDs are generally subsections
251 * of top-level classifierNodes (CL#, e.g. CL3).
252 * @param metafields are the classifier metadata fields that are to be returned.
253 * @param collection is the name of the collection
254 * @param service is the name of the Browse's MetadataRetrieve service
255 * (usually the browse service is ClassifierBrowse, in which case it always
256 * has a retrieve service called ClassifierBrowseMetadataRetrieve) */
257 public String retrieveBrowseMetadata(String collection, String service,
258 String[] nodeIDs, String[] metafields);
259
260 /** @return a String representing Greenstone3 XML for a query process
261 * response returning the results for the query denoted by parameter
262 * nameValParamsMap.
263 * @param nameValParamsMap is a Map of name and value pairs for all the
264 * query field data values. The names match the field names that
265 * describeCollectionService() would have returned for the query service.
266 * @param collection is the name of the collection
267 * @param service is the name of the query service
268 * This method is only ever called when any of the services in the digital
269 * library described themselves as type=query. Therefore any digital
270 * libraries that have no query services, can just return emtpy message
271 * strings (or even "") since this method will never be called on them
272 * anyway. */
273 public String query(String collection, String service,
274 Map nameValParamsMap);
275}
Note: See TracBrowser for help on using the repository browser.