source: other-projects/gs3-webservices-java-client/trunk/src/GS3Fedora/org/greenstone/fedora/services/FedoraToGS3Interface.java

Last change on this file was 26171, checked in by ak19, 12 years ago

Uncommitted changes from ages back to fedoraGS3 classes to get greenstone to work as an interface to fedora repository backend.
File size: 16.2 KB
Line 
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
21package org.greenstone.fedora.services;
22
23import 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*/
32public 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:&lt;collectionName&gt;-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:&lt;collectionName&gt;-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:&lt;collectionName&gt;-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:&lt;collectionName&gt;-&lt;docPID&gt;-&lt;sectionNumber&gt;" or
144 * "greenstone:&lt;collectionName&gt;-&lt;docPID&gt;"
145 * If it is "greenstone:&lt;collectionName&gt;-&lt;docPID&gt;", then the content for
146 * "greenstone:&lt;collectionName&gt;-1" ("greenstone:&lt;collectionName&gt;-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:&lt;collectionName&gt;-&lt;docPID&gt;-&lt;sectionNumber&gt;"
154 * or "greenstone:&lt;collectionName&gt;-&lt;docPID&gt;"
155 * If it is "greenstone:&lt;collectionName&gt;-&lt;docPID&gt;", then the content for
156 * "greenstone:&lt;collectionName&gt;-1" ("greenstone:&lt;collectionName&gt;-Section1")
157 * is returned. */
158 public String getContent(String[] docIDs);
159
160 /* RETRIEVE SERVICE: DOCUMENT STRUCTURE RETRIEVE */
161
162 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
163 * containing the requested portion of the document structure of the documents
164 * indicated by docIDs:
165 * @param collection is the name of the collection. It's already included in the
166 * docID for a Fedora DL.
167 * @param docID is the document identifier of the document whose hierarchical
168 * structure is requested. The collection name is already included in the
169 * docID for a Fedora DL.
170 * @param structure - strings specifying the required structure of the document.
171 * Any combination of: ancestors, parent, siblings, children, descendants, entire.
172 * @param info - strings specifying the required structural info of the document.
173 * It can be any combination of: siblingPosition, numSiblings, numChildren.
174 */
175 public String getDocumentStructure(String docID, String[] structure, String[] info);
176
177 /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
178 * containing the requested portion of the document structure of the documents
179 * indicated by docIDs:
180 * @param docIDs is an array of document identifiers of documents whose
181 * hierarchical structures are requested. The collection name is already included
182 * in the docID for a Fedora DL.
183 * @param structure - strings specifying the required structure of each document.
184 * Any combination of: ancestors, parent, siblings, children, descendants, entire.
185 * @param info - strings specifying the required structural info of each document.
186 * It can be any combination of: siblingPosition, numSiblings, numChildren.
187 */
188 public String getDocumentStructure(String[] docIDs, String[] structure, String[] info);
189
190
191 /* RETRIEVE SERVICE: DOCUMENT METADATA RETRIEVE */
192
193 /** Given a list of collectionIDs, returns a GS3 DocumentMetadataRetrieve
194 * response message that gives the metadata for each collection identified
195 * @param collIDs is an array of fedora pids identifying collections in the
196 * fedora repository
197 * @return a GS3 DocumentMetadataRetrieve response message containing the
198 * EX metadata for all the requested collections */
199 public String getCollectionMetadata(String[] collIDs);
200
201 /** Given a list of document identifiers, a GS3 DocumentMetadataRetrieve
202 * response message is returned containing the metadata for each document.
203 * @param docIDs is an array of document identifiers (docID can either be &lt;pid&gt;s
204 * items (documents) in the fedora repository, or "&lt;pid&gt;-sectionNumber".
205 * @return a GS3 DocumentMetadataRetrieve response message containing the
206 * EX, DC, DLS metadata for all the requested documents */
207 public String getDocumentMetadata(String[] docIDs, String[] metadata);
208
209 /** Given a collectionID, returns a GS3 DocumentMetadataRetrieve
210 * response message that gives the metadata for the collection identified
211 * @param collID is a fedora pid identifying a collection in its repository
212 * @return a GS3 DocumentMetadataRetrieve response message containing the
213 * EX metadata for the requested collection */
214 public String getCollectionMetadata(String collID);
215
216 /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
217 * response message containing the metadata for the document.
218 * @param docID is a document identifier (docID can either be a &lt;pid&gt;
219 * of an item (document) in the fedora repository, or it can be
220 * "&lt;pid&gt;-sectionNumber".
221 * @return a GS3 DocumentMetadataRetrieve response message containing the
222 * EX, DC, DLS metadata for all the requested document */
223 public String getDocumentMetadata(String docID, String[] metadata);
224
225 /** @return a greenstone DocumentMetadataRetrieve response for the
226 * documents or collections indicated by the docIDsOrCollIDs.
227 * @param docIDsOrCollIDs is an array of identifiers which may be either the
228 * fedora pids for collections, or otherwise may be a document identifier.
229 * In the last case, the document ID may consist of either
230 * "documentPID-sectionNumber" or may just be just fedora documentPID */
231 public String getMetadata(String[] docIDsOrCollIDs, String[] metadata);
232
233 /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
234 * response message containing ONLY the Title metadata for the document.
235 * @param docID is a document identifier (docID can either be a &lt;pid&gt;
236 * of an item (document) in the fedora repository, or it can be
237 * "&lt;pid&gt;-sectionNumber".
238 * @return a GS3 DocumentMetadataRetrieve response message containing the
239 * Title metadata for the requested document */
240 public String getTitleMetadata(String docID);
241
242 /** Given a document identifier, returns a GS3 DocumentMetadataRetrieve
243 * response message containing ONLY the Title metadata for the documents.
244 * @param docIDs is a list of document identifiers (where docID can either be
245 * a &lt;pid&gt; of an item (document) in the fedora repository, or it can be
246 * "&lt;pid&gt;-sectionNumber".
247 * @return a GS3 DocumentMetadataRetrieve response message containing the
248 * Title metadata for all the requested documents */
249 public String getTitleMetadata(String[] docIDs);
250
251 /* BROWSE AND QUERY SERVICES */
252
253 /** This method performs something equivalent to a greenstone3
254 * ClassifierBrowseMetadataRetrieve on the classifierNodeIDs
255 * @param classNodeIDs are the IDs of the classifierNode for which the metadata
256 * needs to be returned
257 * @param metafields are the classifier metadata fields that are to be returned.
258 * @return a GS3 ClassifierBrowseMetadataRetrieve response message which
259 * lists the metadata for all the classifierNodes passed as parameter.*/
260 public String browseMetadataRetrieve(String[] classNodeIDs, String[] metafields);
261
262 /** This method performs the implemented browse operation: allowing the
263 * user to browse the titles of documents in the given collection by letter
264 * and returning the results.
265 * @param classifierIDs are the ids of the classifiers on which to browse. In
266 * this case, the classifier indicates whether we browse titles by letter, or
267 * browse (documents) by collection; and it is of the form &lt;CL(letter)&gt;.
268 * @param collectionName is the name of the collection whose documents
269 * starting with the given letter will be returned.
270 * @param structure - the requested browse substructure. Can be any combination
271 * of ancestors, parent, siblings, children, descendants.
272 * @param info - the requested structural info. Can be numSiblings, siblingPosition,
273 * numChildren
274 * @return a GS3 DocumentStructureRetrieve response message which lists all
275 * the documents that start with the letter indicated by parameter classifier.
276 */
277 public String browse(String collectionName, String[] classifierIDs, String[] structures, String[] infos);
278
279 /* @returns the document identifiers returned for a search on the titles of
280 * documents that contain the given term in their title */
281 //public String queryTitle(String termInTitle) throws Exception;
282
283 /** @return a String representing Greenstone3 XML for a query process
284 * response returning the results for the query denoted by parameter
285 * nameValParamsMap.
286 * @param nameValParamsMap is a Map of name and value pairs for all the
287 * query field data values. The names match the field names that
288 * describeCollectionService() would have returned for the query service.
289 * @param collection is the name of the collection
290 * @param service is the name of the query service
291 * This method is only ever called when any of the services in the digital
292 * library described themselves as type=query. Therefore any digital
293 * libraries that have no query services, can just return emtpy message
294 * strings (or even "") since this method will never be called on them
295 * anyway. */
296 public String query(String collection, String service,
297 Map nameValParamsMap);
298
299
300 /** Given a URL that represents a fedoraPID, will look up the object.
301 * If it exists, it will return the contents of the DC:Title of its datastream.
302 * If it doesn't exist, it will return the URL as-is.
303 * @param URL: the URL that (after modification) represents a fedoraPID to look up.
304 * @param collection: the name of collection in which to search for the URL
305 * representing a fedoraPID.
306 * @return the string (representing a fedoraPID) stored in the DC:Title of the
307 * URL-fedoraPID. If the URL-fedoraPID is not an object in the given collection,
308 * then the parameter URL is returned.
309 */
310 public String getPIDforURL(String url, String collection);
311}
Note: See TracBrowser for help on using the repository browser.