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

/**
 *#########################################################################
 * FedoraServicesAPIA.java - part of the demo-client for Greenstone 3, 
 * of the Greenstone digital library suite from the New Zealand Digital 
 * Library Project at the  * University of Waikato, New Zealand.
 * <BR><BR>
 * Copyright (C) 2008 New Zealand Digital Library Project
 * <BR><BR>
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * <BR><BR>
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *########################################################################
 */

package org.greenstone.gs3client.dlservices;

import java.util.Map;
import java.io.File;
import org.greenstone.gs3client.data.DocumentNodeData;
import org.greenstone.fedora.services.*;

/** 
 * FedoraServicesAPIA implements DigitalLibraryServicesAPIA for enabling the 
 * Java-client to access a Fedora repository of Greenstone digital objects. 
 * This is made possible by its use of the FedoraGS3.jar file's functionality, 
 * as made available through the FedoraGS3Connection class. 
 * @author ak19 
*/
public class FedoraServicesAPIA extends FedoraGS3Connection 
    implements DigitalLibraryServicesAPIA
{
    /** Default constructor */
    public FedoraServicesAPIA() throws Exception {
        super(DigitalLibraryServicesAPIA.propertiesFile);
    }

    /** Unused constructor for clients: takes a different properties file */
    public FedoraServicesAPIA(File propertiesFile) throws Exception {
        super(propertiesFile);
    }

    /** @return the name of this digital library for displaying in the client */
    public String getDisplayName() {
        return "Fedora";
    }

    /** @return the directory path to the associated files of the given document 
     * node.  For instance, the base url of a JEditorPane's HTML documents can be 
     * set to this. */
    public String getAssocFileBaseURL(DocumentNodeData docNode) {
        return super.getAssocFileBaseURL() 
            + super.getDocPIDFromDocID(docNode.nodeID) + "/";
    }
    
    /** @return Greenstone3 XML describe response message with information
     * about collections contained and services (and any serviceRacks) supported
     * by the Digital library. */
    public String describe() {
        return this.getCollectionList();
    }
    
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing all the metadata of all the documents indicated by docIDs 
     * @param collection is the name of the collection 
     * @param docIDs is an array of document identifiers of documents whose  
     * metadata is requested */
    public String retrieveDocumentMetadata(String collection, String[] docIDs) {
        return this.getDocumentMetadata(docIDs);
    }
    
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing all the metadata of the document denoted by docID 
     * @param collection is the name of the collection 
     * @param docID is the document identifier of the document whose metadata is 
     * requested */
    public String retrieveDocumentMetadata(String collection, String docID) {
        return this.getDocumentMetadata(docID);
    }

    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing only the title metadata of the documents denoted by docIDs 
     * @param collection is the name of the collection 
     * @param docIDs is an array of document identifiers of documents whose titles 
     * are requested */
    public String retrieveTitleMetadata(String collection, String[] docIDs) {
        return this.getTitleMetadata(docIDs);
    }
    
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing only the title metadata of the document denoted by docID 
     * @param collection is the name of the collection 
     * @param docID is the document identifier of the document whose titles is 
     * requested */
    public String retrieveTitleMetadata(String collection, String docID) {
        return this.getTitleMetadata(docID);
    }

    
    /** @return a String representing Greenstone3 DocumentContentRetrieve XML 
     * containing the document contents of the documents indicated by docIDs 
     * @param collection is the name of the collection 
     * @param docIDs is an array of document identifiers of documents whose (text)
     * contents are requested */
    public String retrieveDocumentContent(String collection, String[] docIDs) {
        return this.getContent(docIDs);
    }
    
    /** @return a String representing Greenstone3 DocumentContentRetrieve XML 
     * containing the document contents of the document indicated by docID 
     * @param collection is the name of the collection 
     * @param docID is the document identifier of the document whose (text)
     * content is requested */
    public String retrieveDocumentContent(String collection, String docID) {
        return this.getContent(docID);
    }

    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML
     * containing the document structure of the documents indicated by docIDs: 
     * this means all their descendents 
     * @param collection is the name of the collection 
     * @param docIDs is an array of document identifiers of documents whose
     * hierarchical structures are requested */
    public String retrieveDocumentStructure(String collection, String[] docIDs) {
        return this.getDocumentStructure(docIDs);
    }
    
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing the document structure of the document indicated by docID: 
     * this means all its descendents 
     * @param collection is the name of the collection 
     * @param docID is the document identifier of the document whose hierarchical
     * structure is requested*/
    public String retrieveDocumentStructure(String collection, String docID) {
        return this.getDocumentStructure(docID);
    }

    // UNUSED by the client, but still a very useful method:
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing a view of the document structure of the documents denoted by 
     * docs where only the requested documents and their direct children are  
     * returned. 
     * @param collection is the name of the collection 
     * @param docIDs is an array of document identifiers of documents whose
     * hierarchical structures are requested */
    public String retrieveDocumentChildren(String collection, String[] docIDs) {
        return this.getChildren(docIDs);
    }
    
    /** @return a String representing Greenstone3 DocumentMetadataRetrieve XML 
     * containing a view of the document structure of the document denoted by 
     * docID where only the document and its direct children are returned. 
     * @param collection is the name of the collection 
     * @param docID is the document identifier of the document whose hierarchical
     * structure is requested */
    public String retrieveDocumentChildren(String collection, String docID) {
        return this.getChildren(docID);
    }
    
    /** @return a String representing Greenstone3 ClassifierBrowse XML 
     * giving the entire *structure* of the classification denoted by 
     * classifierID (including the structures of document descendents of 
     * the classifier). 
     * @param classifierID is of the form CL# where the number (#) marks
     * out structured sections like CL1.1.3 or CL2 
     * @param collection is the name of the collection 
     * @param service is the name of the browse service (=ClassifierBrowse usually)
    */
    public String retrieveBrowseStructure(
            String collection, String service, String classifierID) 
    {
        return this.browse(collection, classifierID);
    }

    /** @return a String representing Greenstone3 
     * ClassifierBrowseMetadataRetrieve XML giving all the metadata for
     * all the subclassifiers denoted by nodeIDs. 
     * @param nodeIDs is of the form CL#.# where the number (#) marks
     * out structured sections like CL2.1.3. NodeIDs are generally subsections
     * of top-level classifierNodes (CL#, e.g. CL3). 
     * @param collection is the name of the collection 
     * @param service is the name of the Browse's MetadataRetrieve service 
     * (usually the browse service is ClassifierBrowse, in which case it always
     * has a retrieve service called ClassifierBrowseMetadataRetrieve) */
    public String retrieveBrowseMetadata(
            String collection, String service, String[] nodeIDs) 
    {
        return this.browseMetadataRetrieve(nodeIDs);
    }
    
    /** @return a String representing Greenstone3 XML for a query process
     * response returning the results for the query denoted by parameter
     * nameValParamsMap.
     * @param nameValParamsMap is a Map of name and value pairs for all the
     * query field data values. The names match the field names that
     * describeCollectionService() would have returned for the query service. 
     * @param collection is the name of the collection 
     * @param service is the name of the query service
     * This method is only ever called when any of the services in the digital 
     * library described themselves as type=query. Therefore any digital
     * libraries that have no query services, can just return emtpy message 
     * strings (or even "") since this method will never be called on them 
     * anyway. */
    public String query(String collection, String service, 
            Map nameValParamsMap) 
    {   
        return super.query(collection, service, nameValParamsMap);
    }
}