1 | /**
|
---|
2 | *#########################################################################
|
---|
3 | * FedoraToGS3Interface.java - works with the demo-client for Greenstone 3,
|
---|
4 | * of the Greenstone digital library suite from the New Zealand Digital
|
---|
5 | * Library Project at the * University of Waikato, New Zealand.
|
---|
6 | * <BR><BR>
|
---|
7 | * Copyright (C) 2008 New Zealand Digital Library Project
|
---|
8 | * <BR><BR>
|
---|
9 | * This program is free software; you can redistribute it and/or modify
|
---|
10 | * it under the terms of the GNU General Public License as published by
|
---|
11 | * the Free Software Foundation; either version 2 of the License, or
|
---|
12 | * (at your option) any later version.
|
---|
13 | * <BR><BR>
|
---|
14 | * This program is distributed in the hope that it will be useful,
|
---|
15 | * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
---|
17 | * GNU General Public License for more details.
|
---|
18 | *########################################################################
|
---|
19 | */
|
---|
20 |
|
---|
21 | package org.greenstone.fedora.services;
|
---|
22 |
|
---|
23 | import java.util.Map;
|
---|
24 |
|
---|
25 | /**
|
---|
26 | * Most of the following methods return the same data as FedoraGS3DL, but
|
---|
27 | * formatted as Greenstone Response-Message XML. This way our java-client can
|
---|
28 | * parse the returned XML in the same way and store them in the same data
|
---|
29 | * structures.
|
---|
30 | * @author ak19
|
---|
31 | */
|
---|
32 | public interface FedoraToGS3Interface // extends FedoraGS3DL
|
---|
33 | {
|
---|
34 | /** Interface declaring some string constants of literals to look for */
|
---|
35 | public interface Constants {
|
---|
36 | public static final String GS3FilePathMacro = "_httpdocimg_";
|
---|
37 | /** Prefix of the (img) files associated with Greenstone documents
|
---|
38 | * in the Fedora repository */
|
---|
39 | public static final String ASSOCFILEPREFIX = "FG";
|
---|
40 |
|
---|
41 | /** names of query form controls */
|
---|
42 | public static final String MAXDOCS = "maxDocs";
|
---|
43 | public static final String QUERY = "query";
|
---|
44 | public static final String SIMPLEFIELD_ATT = "simpleField";
|
---|
45 | public static final String OCCURS_ATT = "occurs";
|
---|
46 | public static final String FIELDNAME_ATT = "fieldName";
|
---|
47 | public static final String NUM_DOCS_MATCHED = "numDocsMatched";
|
---|
48 |
|
---|
49 | /** Field search names and separator used externally */
|
---|
50 | public static final String ALL_FIELDS = "allFields";
|
---|
51 | public static final String DOC_TITLES = "docTitles"; // doc titles only
|
---|
52 | public static final String ALL_TITLES = "allTitles"; // all titles, section & doc
|
---|
53 | public static final String FULLTEXT = "fullText";
|
---|
54 | public static final String COMMA = ",";
|
---|
55 | }
|
---|
56 |
|
---|
57 | /* FEDORA GENERIC SEARCH RELATED */
|
---|
58 | /** @return the gSearchWSDLURL, the url of the WSDL for the
|
---|
59 | * FedoraGSearch web services */
|
---|
60 | public String getGSearchWSDLURL();
|
---|
61 |
|
---|
62 | /** Sets the member variable gSearchWSDLURL that specify the location of
|
---|
63 | * the WSDL file of FedoraGSearch's web services. Then it attempts
|
---|
64 | * to instantiate a connection to those web services.
|
---|
65 | * @param url is the new url of the GSearch web services WSDL file */
|
---|
66 | public void setGSearchWSDLURL(String url);
|
---|
67 |
|
---|
68 | /** @return the gSearchIndexName, the name of the index Fedora Generic
|
---|
69 | * Search will search in (where GS3 docs have been indexed into). */
|
---|
70 | public String getGSearchIndexName();
|
---|
71 |
|
---|
72 | /** Sets the member variable gSearchIndexName that specifies the name
|
---|
73 | * of the index containing indexed GS3 documents. Then it attempts
|
---|
74 | * to instantiate a connection to the Fedora GSearch web services using
|
---|
75 | * this changed value for indexName.
|
---|
76 | * @param indexName is the new name of the index containing indexed GS3
|
---|
77 | * docs that GSearch should search in. */
|
---|
78 | public void setGSearchIndexName(String indexName);
|
---|
79 |
|
---|
80 | /* DESCRIBE SERVICES */
|
---|
81 | /** @return a GS3 response message for a describe services request:
|
---|
82 | * indicating the list of services supported by the Fedora-Greenstone
|
---|
83 | * interface. These are DocumentContentRetrieve, DocumentMetadataRetrieve,
|
---|
84 | * DocumentStructureRetrieve, BrowseByLetter - as indicated by member
|
---|
85 | * variable serviceNames. */
|
---|
86 | public String getServiceList();
|
---|
87 |
|
---|
88 | /** @return a GS3 describe response message listing the collections and
|
---|
89 | * collection-specific metadata stored in the Fedora-Greenstone repository. */
|
---|
90 | public String getCollectionList();
|
---|
91 |
|
---|
92 | /** @return a GS3 describe response message for a collection in the
|
---|
93 | * Fedora-Greenstone repository.
|
---|
94 | * @param collectionName - the name of the collection that is to be described.
|
---|
95 | * It will be converted to a fedora collection pid, which is of the form
|
---|
96 | * "greenstone:<collectionName>-collection". */
|
---|
97 | public String describeCollection(String collectionName);
|
---|
98 |
|
---|
99 | /** @return a GS3 describe response message for the services of a collection
|
---|
100 | * in the Fedora-Greenstone repository. So far, these services are the same for
|
---|
101 | * all fedora collections: they are the services given in member variable
|
---|
102 | * serviceNames: DocumentContent/Metadata/StructureRetrieve, browse.
|
---|
103 | * @param collectionName - the name of the collection whose services are to
|
---|
104 | * be described. It will be converted to a fedora collection pid, which is of
|
---|
105 | * the form "greenstone:<collectionName>-collection". */
|
---|
106 | public String describeCollectionServices(String collectionName);
|
---|
107 |
|
---|
108 | /**
|
---|
109 | * All collections in this Digital Library (Fedora Repository) share
|
---|
110 | * the same services, so this method returns the same as
|
---|
111 | * describeService(serviceName).
|
---|
112 | * @return a GS3 describe response message for the requested service
|
---|
113 | * of the given collection. DocumentContent/Metadata/StructureRetrieve
|
---|
114 | * return nothing special except their names; browse (and any query)
|
---|
115 | * return more complex XML responses.
|
---|
116 | * @param collectionName - the name of the collection whose service is to
|
---|
117 | * be described. It will be converted to a fedora collection pid, which is of
|
---|
118 | * the form "greenstone:<collectionName>-collection".
|
---|
119 | * @param serviceName - the name of the service in the collection which is to
|
---|
120 | * be described. */
|
---|
121 | public String describeCollectionService(String collectionName,
|
---|
122 | String serviceName);
|
---|
123 |
|
---|
124 | /** All collections in this Digital Library (Fedora Repository) share
|
---|
125 | * the same services, so this method returns the same as
|
---|
126 | * describeCollectionService(collName, serviceName).
|
---|
127 | * @return a GS3 describe response message for the requested service
|
---|
128 | * of the given collection. DocumentContent/Metadata/StructureRetrieve
|
---|
129 | * return nothing special except their names; browse (and any query)
|
---|
130 | * return more complex XML responses.
|
---|
131 | * All collections in this Digital Library (Fedora Repository) share
|
---|
132 | * the same services, so this method returns the same as
|
---|
133 | * describeService(serviceName).
|
---|
134 | * @param serviceName - the name of the service in the collection which is to
|
---|
135 | * be described.*/
|
---|
136 | public String describeService(String serviceName);
|
---|
137 |
|
---|
138 | /* RETRIEVE SERVICE: DOCUMENT CONTENT RETRIEVE */
|
---|
139 |
|
---|
140 | /** Given a list of document identifiers that are either docPIDs or
|
---|
141 | * concatenations of docPID+sectionID, this method retrieves their contents.
|
---|
142 | * @param docID is expected to be of the form
|
---|
143 | * "greenstone:<collectionName>-<docPID>-<sectionNumber>" or
|
---|
144 | * "greenstone:<collectionName>-<docPID>"
|
---|
145 | * If it is "greenstone:<collectionName>-<docPID>", then the content for
|
---|
146 | * "greenstone:<collectionName>-1" ("greenstone:<collectionName>-Section1")
|
---|
147 | * is returned. */
|
---|
148 | public String getContent(String docID);
|
---|
149 |
|
---|
150 | /** Given a document identifier that is either a docPID or a concatenation
|
---|
151 | * of docPID+sectionID, this method retrieves the content for it.
|
---|
152 | * @param docIDs an array of document IDs where each is expected to be of the
|
---|
153 | * form "greenstone:<collectionName>-<docPID>-<sectionNumber>"
|
---|
154 | * or "greenstone:<collectionName>-<docPID>"
|
---|
155 | * If it is "greenstone:<collectionName>-<docPID>", then the content for
|
---|
156 | * "greenstone:<collectionName>-1" ("greenstone:<collectionName>-Section1")
|
---|
157 | * is returned. */
|
---|
158 | public String getContent(String[] docIDs);
|
---|
159 |
|
---|
160 | /* RETRIEVE SERVICE: DOCUMENT STRUCTURE RETRIEVE */
|
---|
161 |
|
---|
162 | /** @return the documentStructure of the document or section given by docID.
|
---|
163 | * The structure is returned in the XML format of a Greenstone3
|
---|
164 | * DocumentStructureRetrieve response message. This method returns the entire
|
---|
165 | * subSection of the docID (that is, all descendents included).
|
---|
166 | * @param docID the identifier for the document whose structure is required.
|
---|
167 | * This is either of the format "greenstone:<collectionName>-<docPID>"
|
---|
168 | * OR "greenstone:<collectionName>-<docPID>-"
|
---|
169 | * where "greenstone:<collectionName>-<docPID>-1" is the same as
|
---|
170 | * "greenstone:<collectionName>-<docPID>" and will return the same response */
|
---|
171 | public String getDocumentStructure(String docID);
|
---|
172 |
|
---|
173 | /** @return a view of the structure of the document or section given by docID
|
---|
174 | * which contains only the section and its direct children. This structure is
|
---|
175 | * returned in the XML format of a Greenstone3 DocumentStructureRetrieve
|
---|
176 | * response message.
|
---|
177 | * @param docID the identifier for the document whose structure is required.
|
---|
178 | * This is of the format "greenstone:<collectionName>-<docPID>"
|
---|
179 | * OR "greenstone:<collectionName>-<docPID>-"
|
---|
180 | * where "greenstone:<collectionName>-<docPID>-1" is the same as
|
---|
181 | * "greenstone:<collectionName>-<docPID>" and will return the same response */
|
---|
182 | public String getChildren(String docID);
|
---|
183 |
|
---|
184 | /** @return the documentStructure of the documents or sections given by docIDs.
|
---|
185 | * The structure is returned in the XML format of a Greenstone3
|
---|
186 | * DocumentStructureRetrieve response message. This method returns the entire
|
---|
187 | * subSection of each docID (that is, all descendents included).
|
---|
188 | * @param docIDs an array of document identifiers whose structures are requested
|
---|
189 | * These are of the format "greenstone:<collectionName>-<docPID>"
|
---|
190 | * OR "greenstone:<collectionName>-<docPID>-<sectionNumber>"
|
---|
191 | * where "greenstone:<collectionName>-<docPID>-1" is the same as
|
---|
192 | * "greenstone:<collectionName>-<docPID>" and will return the same response */
|
---|
193 | public String getDocumentStructure(String[] docIDs);
|
---|
194 |
|
---|
195 | /** @return the documentStructure of the documents or sections given by docIDs
|
---|
196 | * but only the sections and their children (not any further descendents).
|
---|
197 | * The structure is returned in the XML format of a Greenstone3
|
---|
198 | * DocumentStructureRetrieve response message.
|
---|
199 | * @param docIDs an array of document identifiers whose structures are requested
|
---|
200 | * These are of the format "greenstone:<collectionName>-<docPID>"
|
---|
201 | * OR "greenstone:<collectionName>-<docPID>-<sectionNumber>"
|
---|
202 | * where "greenstone:<collectionName>-<docPID>-1" is the same as
|
---|
203 | * "greenstone:<collectionName>-<docPID>" and will return the same response */
|
---|
204 | public String getChildren(String[] docIDs);
|
---|
205 |
|
---|
206 |
|
---|
207 | /* RETRIEVE SERVICE: DOCUMENT METADATA RETRIEVE */
|
---|
208 |
|
---|
209 | /** Given a list of collectionIDs, returns a GS3 DocumentMetadataRetrieve
|
---|
210 | * response message that gives the metadata for each collection identified
|
---|
211 | * @param collIDs is an array of fedora pids identifying collections in the
|
---|
212 | * fedora repository
|
---|
213 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
214 | * EX metadata for all the requested collections */
|
---|
215 | public String getCollectionMetadata(String[] collIDs);
|
---|
216 |
|
---|
217 | /** Given a list of document identifiers, a GS3 DocumentMetadataRetrieve
|
---|
218 | * response message is returned containing the metadata for each document.
|
---|
219 | * @param docIDs is an array of document identifiers (docID can either be <pid>s
|
---|
220 | * items (documents) in the fedora repository, or "<pid>-sectionNumber".
|
---|
221 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
222 | * EX, DC, DLS metadata for all the requested documents */
|
---|
223 | public String getDocumentMetadata(String[] docIDs);
|
---|
224 |
|
---|
225 | /** Given a collectionID, returns a GS3 DocumentMetadataRetrieve
|
---|
226 | * response message that gives the metadata for the collection identified
|
---|
227 | * @param collID is a fedora pid identifying a collection in its repository
|
---|
228 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
229 | * EX metadata for the requested collection */
|
---|
230 | public String getCollectionMetadata(String collID);
|
---|
231 |
|
---|
232 | /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
|
---|
233 | * response message containing the metadata for the document.
|
---|
234 | * @param docID is a document identifier (docID can either be a <pid>
|
---|
235 | * of an item (document) in the fedora repository, or it can be
|
---|
236 | * "<pid>-sectionNumber".
|
---|
237 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
238 | * EX, DC, DLS metadata for all the requested document */
|
---|
239 | public String getDocumentMetadata(String docID);
|
---|
240 |
|
---|
241 | /** @return a greenstone DocumentMetadataRetrieve response for the
|
---|
242 | * documents or collections indicated by the docIDsOrCollIDs.
|
---|
243 | * @param docIDsOrCollIDs is an array of identifiers which may be either the
|
---|
244 | * fedora pids for collections, or otherwise may be a document identifier.
|
---|
245 | * In the last case, the document ID may consist of either
|
---|
246 | * "documentPID-sectionNumber" or may just be just fedora documentPID */
|
---|
247 | public String getMetadata(String[] docIDsOrCollIDs);
|
---|
248 |
|
---|
249 | /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
|
---|
250 | * response message containing ONLY the Title metadata for the document.
|
---|
251 | * @param docID is a document identifier (docID can either be a <pid>
|
---|
252 | * of an item (document) in the fedora repository, or it can be
|
---|
253 | * "<pid>-sectionNumber".
|
---|
254 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
255 | * Title metadata for the requested document */
|
---|
256 | public String getTitleMetadata(String docID);
|
---|
257 |
|
---|
258 | /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
|
---|
259 | * response message containing ONLY the Title metadata for the documents.
|
---|
260 | * @param docIDs is a list of document identifiers (where docID can either be
|
---|
261 | * a <pid> of an item (document) in the fedora repository, or it can be
|
---|
262 | * "<pid>-sectionNumber".
|
---|
263 | * @return a GS3 DocumentMetadataRetrieve response message containing the
|
---|
264 | * Title metadata for all the requested documents */
|
---|
265 | public String getTitleMetadata(String[] docIDs);
|
---|
266 |
|
---|
267 | /* BROWSE AND QUERY SERVICES */
|
---|
268 |
|
---|
269 | /** This method performs something equivalent to a greenstone3
|
---|
270 | * ClassifierBrowseMetadataRetrieve on the classifierNodeIDs
|
---|
271 | * @param classNodeIDs are the IDs of the classifierNode for which the metadata
|
---|
272 | * needs to be returned
|
---|
273 | * @return a GS3 ClassifierBrowseMetadataRetrieve response message which
|
---|
274 | * lists the metadata for all the classifierNodes passed as parameter.*/
|
---|
275 | public String browseMetadataRetrieve(String[] classNodeIDs);
|
---|
276 |
|
---|
277 | /** This method performs the implemented browse operation: allowing the
|
---|
278 | * user to browse the titles of documents in the given collection by letter
|
---|
279 | * and returning the results.
|
---|
280 | * @param classifierID is the id of the classifier on which to browse. In
|
---|
281 | * this case, the classifier indicates whether we browse titles by letter, or
|
---|
282 | * browse (documents) by collection; and it is of the form <CL(letter)>.
|
---|
283 | * @param collectionName is the name of the collection whose documents
|
---|
284 | * starting with the given letter will be returned.
|
---|
285 | * @return a GS3 DocumentStructureRetrieve response message which lists all
|
---|
286 | * the documents that start with the letter indicated by parameter classifier.
|
---|
287 | */
|
---|
288 | public String browse(String collectionName, String classifierID);
|
---|
289 |
|
---|
290 | /* @returns the document identifiers returned for a search on the titles of
|
---|
291 | * documents that contain the given term in their title */
|
---|
292 | //public String queryTitle(String termInTitle) throws Exception;
|
---|
293 |
|
---|
294 | /** @return a String representing Greenstone3 XML for a query process
|
---|
295 | * response returning the results for the query denoted by parameter
|
---|
296 | * nameValParamsMap.
|
---|
297 | * @param nameValParamsMap is a Map of name and value pairs for all the
|
---|
298 | * query field data values. The names match the field names that
|
---|
299 | * describeCollectionService() would have returned for the query service.
|
---|
300 | * @param collection is the name of the collection
|
---|
301 | * @param service is the name of the query service
|
---|
302 | * This method is only ever called when any of the services in the digital
|
---|
303 | * library described themselves as type=query. Therefore any digital
|
---|
304 | * libraries that have no query services, can just return emtpy message
|
---|
305 | * strings (or even "") since this method will never be called on them
|
---|
306 | * anyway. */
|
---|
307 | public String query(String collection, String service,
|
---|
308 | Map nameValParamsMap);
|
---|
309 | } |
---|