java.fedora.oai.OAIProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of fcrepo-client Show documentation
The Fedora Client is a Java Library that allows API access to a Fedora Repository. The client is typically one part of a full Fedora installation.
The newest version!
/*
 * -----------------------------------------------------------------------------
 *
 * License and Copyright: The contents of this file are subject to the
 * Apache License, Version 2.0 (the "License"); you may not use 
 * this file except in compliance with the License. You may obtain a copy of 
 * the License at 
 * http://www.fedora-commons.org/licenses.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The entire file consists of original code.
 * Copyright © 2008 Fedora Commons, Inc.

 * 
Copyright © 2002-2007 The Rector and Visitors of the University of 
 * Virginia and Cornell University
 
 * All rights reserved.
 *
 * -----------------------------------------------------------------------------
 */
package fedora.oai;

import java.util.Date;
import java.util.List;
import java.util.Set;

/**
 *
 * Title: OAIProvider.java
 * Description: 
 *
 * @author [email protected]
 * @version $Id: OAIProvider.java 3965 2005-04-21 12:52:40Z rlw $
 */
public interface OAIProvider {

    /**
     * Get a human readable name for the repository.
     *
     * @return the repository name.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract String getRepositoryName()
            throws RepositoryException;

    /**
     * Get the HTTP endpoint for the OAI-PMH interface.
     *
     * @return the base URL.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract String getBaseURL(String protocol, String port)
            throws RepositoryException;

    /**
     * Get the version of the OAI-PMH supported by the repository.
     *
     * @return the protocol version number.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract String getProtocolVersion()
            throws RepositoryException;

    /**
     * Get a Date (in UTC) that is the guaranteed lower limit of all datestamps
     * recording changes, modifications, or deletions in the repository.
     * A repository must not use datestamps lower than this.
     *
     * @return the earliest datetime stamp.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Date getEarliestDatestamp()
            throws RepositoryException;

    /**
     * Get the manner in which the repository supports the notion of deleted
     * records.
     *
     * @return manner in which repository supports the notion of deletion.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract DeletedRecordSupport getDeletedRecordSupport()
            throws RepositoryException;

    /**
     * Get the finest harvesting granularity supported by the repository.
     *
     * @return the finest harvesting granularity supported by the repository.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract DateGranularitySupport getDateGranularitySupport()
            throws RepositoryException;

    /**
     * Get the email addresses of administrators of the repository.
     *
     * This set must contain at least one item.
     *
     * @return the email addresses of administrators of the repository.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Set getAdminEmails()
            throws RepositoryException;

    /**
     * Get the compression encodings supported by the repository.
     *
     * This set may be empty. Recommended values are those in RFC 2616 Section
     * 14.11
     *
     * @return the compression encodings supported by the repository.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Set getSupportedCompressionEncodings()
            throws RepositoryException;

    /**
     * Get XML descriptions of the repository.
     *
     * Each Set element must be a String containing a description according
     * to some W3C schema, where the xsi:schemaLocation attribute is used
     * on the root element.
     *
     * See http://www.openarchives.org/OAI/2.0/guidelines.htm for guidelines
     * regarding these repository-level descriptions.
     *
     * @return XML descriptions of the repository.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Set getDescriptions()
            throws RepositoryException;

    /**
     * Get an individual metadata record from the repository.
     *
     * @param identifier the record identifier.
     * @param metadataPrefix the metadata prefix identifier.
     * @return an individual metadata record from the repository.
     * @throws CannotDisseminateFormatException
     * @throws IDDoesNotExistException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Record getRecord(String identifier, String metadataPrefix)
            throws CannotDisseminateFormatException, IDDoesNotExistException,
            RepositoryException;

    /**
     * Get the Records in the repository matching the given criteria.
     * Any of the arguments (except metadataPrefix) may be null, indicating
     * "any".
     *
     * If the size of the returned list is over getMaxRecords(), the last element
     * is a resumptionToken (a String) which can be used to get the rest of the
     * list.
     *
     * @param from the beginning date of the date range.
     * @param until the ending date of the date range.
     * @param metadataPrefix the metadata prefix.
     * @param set the set of criteria
     * @return the Records in the repository matching the given criteria.
     * @throws CannotDisseminateFormatException
     * @throws NoRecordsMatchException
     * @throws NoSetHierarchyException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getRecords(Date from, Date until, String metadataPrefix,
            String set)
            throws CannotDisseminateFormatException,
            NoRecordsMatchException, NoSetHierarchyException,
            RepositoryException;

    /**
     * Get the remaining portion of a set of Records.
     *
     * If the size of the returned list is over getMaxRecords(), the last element
     * is another resumptionToken (a String) which can be used to get the rest
     * of the list.
     *
     * @param resumptionToken a string that can be used to get the rest of the
     *                        list.
     * @return the remaining portion of a set of Records.
     * @throws CannotDisseminateFormatException
     * @throws NoRecordsMatchException
     * @throws NoSetHierarchyException
     * @throws BadResumptionTokenException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getRecords(String resumptionToken)
            throws CannotDisseminateFormatException,
            NoRecordsMatchException, NoSetHierarchyException,
            BadResumptionTokenException, RepositoryException;

    /**
     * Just like getRecords, but returns Header objects.
     *
     * If the size of the returned list is over getMaxHeaders(), the last element
     * is a resumptionToken (a String) which can be used to get the rest of the
     * list.
     *
     * @param from the beginning date range.
     * @param until the end of the date range.
     * @param metadataPrefix the metadata prefix.
     * @param set the set of criteria.
     * @return the remaining portion of a set of Header objects.
     * @throws CannotDisseminateFormatException
     * @throws NoRecordsMatchException
     * @throws NoSetHierarchyException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getHeaders(Date from, Date until, String metadataPrefix,
            String set)
            throws CannotDisseminateFormatException, NoRecordsMatchException,
            NoSetHierarchyException, RepositoryException;

    /**
     * Get the remaining portion of a set of Headers.
     *
     * If the size of the returned list is over getMaxHeaders() the last element
     * is another resumptionToken (a String) which can be used to get the rest
     * of the list.
     *
     * @param resumptionToken a string that can be used to get the rest of the
     *                        list.
     * @return the remaining portion of a set of Headers.
     * @throws CannotDisseminateFormatException
     * @throws NoRecordsMatchException
     * @throws NoSetHierarchyException
     * @throws BadResumptionTokenException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getHeaders(String resumptionToken)
            throws CannotDisseminateFormatException,
            NoRecordsMatchException, NoSetHierarchyException,
            BadResumptionTokenException, RepositoryException;

    /**
     * Get the setSpecs, setNames, and setDescriptions of sets in the
     * repository.  Each set has a setSpec, a name, and zero or more
     * descriptions, held by a SetInfo object.
     *
     * If the size of the returned list is over getMaxSets(), the last element
     * is a resumptionToken (a String) which can be used to get the rest
     * of the list.
     *
     * @return the setSpecs, setNames, and setDescriptions of sets in the
     *         repository.
     * @throws NoSetHierarchyException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getSets()
            throws NoSetHierarchyException, RepositoryException;

    /**
     * Get the remaining portion of a set of Sets.
     *
     * If the size of the returned list is over getMaxSets(), the last element
     * is another resumptionToken (a String) which can be used to get the rest
     * of the list.
     *
     * @param resumptionToken a string that can be used to get the rest of the
     *                        list.
     * @return the remaining portion of a set of Sets.
     * @throws BadResumptionTokenException
     * @throws NoSetHierarchyException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract List getSets(String resumptionToken)
            throws BadResumptionTokenException,
            NoSetHierarchyException, RepositoryException;

    /**
     * Get the MetadataFormats supported across the repository or for an
     * individual item in the repository.
     *
     * @param id The item identifier, or null, meaning "the entire repository"
     * @return the set of metadata formats supported by the repository.
     * @throws IDDoesNotExistException
     * @throws NoMetadataFormatsException
     * @throws RepositoryException if an error has occurred.
     */
    public abstract Set getMetadataFormats(String id)
            throws IDDoesNotExistException, NoMetadataFormatsException,
            RepositoryException;

    /**
     * Get the maximum number of sets that are returned at a time.
     *
     * A negative value signifies no maximum.
     *
     * @return the maximum number of sets that are returned at a time.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract long getMaxSets()
            throws RepositoryException;

    /**
     * Get the maximum number of records that are returned at a time.
     *
     * A negative value signifies no maximum.
     *
     * @return the maximum number of records that are returned at a time.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract long getMaxRecords()
            throws RepositoryException;

    /**
     * Get the maximum number of headers that are returned at a time.
     *
     * A negative value signifies no maximum.
     *
     * @return the maximum number of headers that are returned at a time.
     * @throws RepositoryException if an error has occurred.
     */
    public abstract long getMaxHeaders()
            throws RepositoryException;
}