/**
 * The contents of this file are subject to the license and copyright
 * detailed in the LICENSE and NOTICE files at the root of the source
 * tree and available online at
 *
 * http://www.dspace.org/license/
 */
package org.dspace.app.util.service;

import org.dspace.content.DSpaceObject;
import org.dspace.core.Context;
import org.w3c.dom.Document;

import java.io.IOException;
import java.sql.SQLException;
import java.util.List;
import java.util.Map;

/**
 * Utility Class with static methods for producing OpenSearch-compliant search results,
 * and the OpenSearch description document.
 * <p>
 * OpenSearch is a specification for describing and advertising search-engines
 * and their result formats. Commonly, RSS and Atom formats are used, which
 * the current implementation supports, as is HTML (used directly in browsers).
 * NB: this is baseline OpenSearch, no extensions currently supported.
 * </p>
 * <p>
 * The value of the "scope" parameter should either be absent (which means no
 * scope restriction), or the handle of a community or collection.
 * </p>
 *
 * @author Richard Rodgers
 *
 */
public interface OpenSearchService {

    /**
     * Returns list of supported formats
     *
     * @return list of format names - 'rss', 'atom' or 'html'
     */
    public List<String> getFormats();

    /**
     * Returns a mime-type associated with passed format
     *
     * @param format the results document format (rss, atom, html)
     * @return content-type mime-type
     */
    public String getContentType(String format);

    /**
     * Returns the OpenSearch service document appropriate for given scope
     *
     * @param scope - null for entire repository, or handle or community or collection
     * @return document the service document
     * @throws IOException if IO error
     */
    public Document getDescriptionDoc(String scope) throws IOException;


    /**
     * Returns OpenSearch Servic Document as a string
     *
     * @param scope - null for entire repository, or handle or community or collection
     * @return service document as a string
     */
    public String getDescription(String scope);

    /**
     * Returns a formatted set of search results as a string
     *
     * @param context DSpace Context
     * @param format results format - html, rss or atom
     * @param query - the search query
     * @param totalResults - the hit count
     * @param start - start result index
     * @param pageSize - page size
     * @param scope - search scope, null or community/collection handle
     * @param results the retreived DSpace objects satisfying search
     * @param labels labels to apply - format specific
     * @return formatted search results
     * @throws IOException if IO error
     */
    public String getResultsString(Context context, String format, String query, int totalResults, int start, int pageSize,
                                          DSpaceObject scope, List<DSpaceObject> results,
                                          Map<String, String> labels) throws IOException;
    /**
     * Returns a formatted set of search results as a document
     *
     * @param context DSpace Context
     * @param format results format - html, rss or atom
     * @param query - the search query
     * @param totalResults - the hit count
     * @param start - start result index
     * @param pageSize - page size
     * @param scope - search scope, null or community/collection handle
     * @param results the retreived DSpace objects satisfying search
     * @param labels labels to apply - format specific
     * @return formatted search results
     * @throws IOException if IO error
     */
    public Document getResultsDoc(Context context, String format, String query, int totalResults, int start, int pageSize,
                                         DSpaceObject scope, List<DSpaceObject> results, Map<String, String> labels)
            throws IOException;

    public DSpaceObject resolveScope(Context context, String scope) throws SQLException;

}