browse.java

dspace 用j2ee架构的一个数字图书馆.开源程序

/*
 * Browse.java
 *
 * Version: $Revision: 1.40 $
 *
 * Date: $Date: 2006/02/21 22:06:36 $
 *
 * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
 * Institute of Technology.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * - Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * - Neither the name of the Hewlett-Packard Company nor the name of the
 * Massachusetts Institute of Technology nor the names of their
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */
package org.dspace.browse;

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.text.MessageFormat;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.SortedMap;
import java.util.StringTokenizer;
import java.util.TreeMap;
import java.util.WeakHashMap;

import org.apache.log4j.Logger;
import org.dspace.content.Collection;
import org.dspace.content.Community;
import org.dspace.content.DCValue;
import org.dspace.content.Item;
import org.dspace.content.ItemComparator;
import org.dspace.content.ItemIterator;
import org.dspace.core.ConfigurationManager;
import org.dspace.core.Context;
import org.dspace.storage.rdbms.DatabaseManager;
import org.dspace.storage.rdbms.TableRow;

/**
 * API for Browsing Items in DSpace by title, author, or date. Browses only
 * return archived Items.
 * 
 * @author Peter Breton
 * @version $Revision: 1.40 $
 */
public class Browse
{
    // Browse types
    static final int AUTHORS_BROWSE = 0;

    static final int ITEMS_BY_TITLE_BROWSE = 1;

    static final int ITEMS_BY_AUTHOR_BROWSE = 2;

    static final int ITEMS_BY_DATE_BROWSE = 3;

    static final int SUBJECTS_BROWSE = 4;

    static final int ITEMS_BY_SUBJECT_BROWSE = 5;

    
    /** Log4j log */
    private static Logger log = Logger.getLogger(Browse.class);

    /**
     * Constructor
     */
    private Browse()
    {
    }

    /**
     * Return distinct Authors in the given scope. Author refers to a Dublin
     * Core field with element <em>contributor</em> and qualifier
     * <em>author</em>.
     * 
     * <p>
     * Results are returned in alphabetical order.
     * </p>
     * 
     * @param scope
     *            The BrowseScope
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getAuthors(BrowseScope scope) throws SQLException
    {
        scope.setBrowseType(AUTHORS_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(null);

        return doBrowse(scope);
    }
    /**
     * Return distinct Subjects in the given scope. Subjects refers to a Dublin
     * Core field with element <em>subject</em> and qualifier
     * <em>*</em>.
     *
     * <p>
     * Results are returned in alphabetical order.
     * </p>
     *
     * @param scope
     *            The BrowseScope
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getSubjects(BrowseScope scope) throws SQLException
    {
        scope.setBrowseType(SUBJECTS_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(null);

        return doBrowse(scope);
    }

    /**
     * Return Items indexed by title in the given scope. Title refers to a
     * Dublin Core field with element <em>title</em> and no qualifier.
     * 
     * <p>
     * Results are returned in alphabetical order; that is, the Item with the
     * title which is first in alphabetical order will be returned first.
     * </p>
     * 
     * @param scope
     *            The BrowseScope
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getItemsByTitle(BrowseScope scope)
            throws SQLException
    {
        scope.setBrowseType(ITEMS_BY_TITLE_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(null);

        return doBrowse(scope);
    }

    /**
     * Return Items indexed by date in the given scope. Date refers to a Dublin
     * Core field with element <em>date</em> and qualifier <em>issued</em>.
     * 
     * <p>
     * If oldestfirst is true, the dates returned are the ones after the focus,
     * ordered from earliest to latest. Otherwise the dates are the ones before
     * the focus, and ordered from latest to earliest. For example:
     * </p>
     * 
     * <p>
     * For example, if the focus is <em>1995</em>, and oldestfirst is true,
     * the results might look like this:
     * </p>
     * 
     * <code>1993, 1994, 1995 (the focus), 1996, 1997.....</code>
     * 
     * <p>
     * While if the focus is <em>1995</em>, and oldestfirst is false, the
     * results would be:
     * </p>
     * 
     * <code>1997, 1996, 1995 (the focus), 1994, 1993 .....</code>
     * 
     * @param scope
     *            The BrowseScope
     * @param oldestfirst
     *            If true, the dates returned are the ones after focus, ordered
     *            from earliest to latest; otherwise the dates are the ones
     *            before focus, ordered from latest to earliest.
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getItemsByDate(BrowseScope scope,
            boolean oldestfirst) throws SQLException
    {
        scope.setBrowseType(ITEMS_BY_DATE_BROWSE);
        scope.setAscending(oldestfirst);
        scope.setSortByTitle(null);

        return doBrowse(scope);
    }

    /**
     * <p>
     * Return Items in the given scope by the author (exact match). The focus of
     * the BrowseScope is the author to use; using a BrowseScope without a focus
     * causes an IllegalArgumentException to be thrown.
     * </p>
     * 
     * <p>
     * Author refers to a Dublin Core field with element <em>contributor</em>
     * and qualifier <em>author</em>.
     * </p>
     * 
     * @param scope
     *            The BrowseScope
     * @param sortByTitle
     *            If true, the returned items are sorted by title; otherwise
     *            they are sorted by date issued.
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getItemsByAuthor(BrowseScope scope,
            boolean sortByTitle) throws SQLException
    {
        if (!scope.hasFocus())
        {
            throw new IllegalArgumentException(
                    "Must specify an author for getItemsByAuthor");
        }

        if (!(scope.getFocus() instanceof String))
        {
            throw new IllegalArgumentException(
                    "The focus for getItemsByAuthor must be a String");
        }

        scope.setBrowseType(ITEMS_BY_AUTHOR_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(sortByTitle ? Boolean.TRUE : Boolean.FALSE);
        scope.setTotalAll();

        return doBrowse(scope);
    }

	/**
     * <p>
     * Return Items in the given scope by the subject (exact match). The focus of
     * the BrowseScope is the subject to use; using a BrowseScope without a focus
     * causes an IllegalArgumentException to be thrown.
     * </p>
     *
     * <p>
     * Subject refers to a Dublin Core field with element <em>subject</em>
     * and qualifier <em>*</em>.
     * </p>
     *
     * @param scope
     *            The BrowseScope
     * @param sortByTitle
     *            If true, the returned items are sorted by title; otherwise
     *            they are sorted by date issued.
     * @return A BrowseInfo object, the results of the browse
     * @exception SQLException
     *                If a database error occurs
     */
    public static BrowseInfo getItemsBySubject(BrowseScope scope,
            boolean sortByTitle) throws SQLException
    {
        if (!scope.hasFocus())
        {
            throw new IllegalArgumentException(
                    "Must specify a subject for getItemsBySubject");
        }

        if (!(scope.getFocus() instanceof String))
        {
            throw new IllegalArgumentException(
                    "The focus for getItemsBySubject must be a String");
        }

        scope.setBrowseType(ITEMS_BY_SUBJECT_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(sortByTitle ? Boolean.TRUE : Boolean.FALSE);
        scope.setTotalAll();

        return doBrowse(scope);
    }

    /**
     * Returns the last items submitted to DSpace in the given scope.
     * 
     * @param scope
     *            The Browse Scope
     * @return A List of Items submitted
     * @exception SQLException
     *                If a database error occurs
     */
    public static List getLastSubmitted(BrowseScope scope) throws SQLException
    {
        Context context = scope.getContext();
        String sql = getLastSubmittedQuery(scope);

        if (log.isDebugEnabled())
        {
            log.debug("SQL for last submitted is \"" + sql + "\"");
        }

        List results = DatabaseManager.query(context, sql).toList();

        return getLastSubmittedResults(context, results);
    }

    /**
     * Return the SQL used to determine the last submitted Items for scope.
     * 
     * @param scope
     * @return String query string
     */
    private static String getLastSubmittedQuery(BrowseScope scope)
    {
        String table = getLastSubmittedTable(scope);

        String query = "SELECT * FROM " + table
                + getScopeClause(scope, "where")
                + " ORDER BY date_accessioned DESC";

        if (!scope.hasNoLimit())
        {
            if ("oracle".equals(ConfigurationManager.getProperty("db.name")))
            {
                // Oracle version of LIMIT...OFFSET - must use a sub-query and
                // ROWNUM
                query = "SELECT * FROM (" + query + ") WHERE ROWNUM <="
                        + scope.getTotal();
            }
            else
            {
                // postgres, use LIMIT
                query = query + " LIMIT " + scope.getTotal();
            }
        }

        return query;
    }

    /**
     * Return the name of the Browse index table to query for last submitted
     * items in the given scope.
     * 
     * @param scope
     * @return name of table
     */
    private static String getLastSubmittedTable(BrowseScope scope)
    {
        if (scope.isCommunityScope())
        {
            return "CommunityItemsByDateAccession";
        }
        else if (scope.isCollectionScope())
        {
            return "CollectionItemsByDateAccession";
        }

        return "ItemsByDateAccessioned";
    }

    /**
     * Transform the query results into a List of Items.
     * 
     * @param context
     * @param results
     * @return list of items
     * @throws SQLException
     */
    private static List getLastSubmittedResults(Context context, List results)
            throws SQLException
    {
        if ((results == null) || (results.isEmpty()))
        {
            return Collections.EMPTY_LIST;
        }

        List items = new ArrayList();

        //  FIXME This seems like a very common need, so might
        //  be factored out at some point.
        for (Iterator iterator = results.iterator(); iterator.hasNext();)
        {
            TableRow row = (TableRow) iterator.next();
            Item item = Item.find(context, row.getIntColumn("item_id"));
            items.add(item);
        }

        return items;
    }

    ////////////////////////////////////////
    // Index maintainence methods
    ////////////////////////////////////////

    /**
     * This method should be called whenever an item is removed.
     * 
     * @param context
     *            The current DSpace context
     * @param id
     *            The id of the item which has been removed
     * @exception SQLException
     *                If a database error occurs
     */
    public static void itemRemoved(Context context, int id) throws SQLException
    {
        String sql = "delete from {0} where item_id = " + id;

        String[] browseTables = BrowseTables.tables();

        for (int i = 0; i < browseTables.length; i++)
        {
            String query = MessageFormat.format(sql,
                    new String[] { browseTables[i] });
            DatabaseManager.updateQuery(context, query);
        }
    }

    /**
     * This method should be called whenever an item has changed. Changes
     * include:
     * 
     * <ul>