resultfilter.java

来自「Jive是基于JSP/JAVA技术构架的一个大型BBS论坛系统,这是Jive论坛」· Java 代码 · 共 567 行 · 第 1/2 页

/**
 * $RCSfile: ResultFilter.java,v $
 * $Revision: 1.5 $
 * $Date: 2002/07/03 00:46:28 $
 *
 * Copyright (C) 1999-2001 CoolServlets, Inc. All rights reserved.
 *
 * This software is the proprietary information of CoolServlets, Inc.
 * Use is subject to license terms.
 */

package com.jivesoftware.forum;

import java.util.*;

/**
 * Filters and sorts lists of threads and messages. This allows for a very
 * rich set of possible queries that can be run on forum data. Some examples
 * are: "Show all messages posted in the forum during the last year by a
 * certain user" or "Show all threads in the forum, sorted by their modification
 * date".<p>
 *
 * The class also supports pagination of results with the setStartIndex(int)
 * and setNumResults(int) methods. If the start index is not set, it will
 * begin at index 0 (the start of results). If the number of results is not set,
 * it will be unbounded and return as many results as available.<p>
 *
 * By default, result filters will obey the moderation rules as they are set
 * for each forum. You can override this behavior by setting a moderation range.
 * <p>
 *
 * Factory methods to create common queries are provided for convenience.
 *
 * @see Forum#threads(ResultFilter)
 * @see Forum#messages(ResultFilter)
 * @see ForumThread#messages(ResultFilter)
 * @see JiveGlobals
 */
public class ResultFilter {

    /**
     * Descending sort (ie 3, 2, 1...).
     */
    public static final int DESCENDING = 0;

    /**
     * Ascending sort (ie 3, 4, 5...).
     */
    public static final int ASCENDING = 1;

    /**
     * An integer value that represents NULL. The actual value is
     * Integer.MAX_VALUE - 123 (an arbitrary number that has a very low
     * probability of actually being selected by a user as a valid value).
     */
    public static final int NULL_INT = Integer.MAX_VALUE - 123;

    /**
     * Creates a default forum ResultFilter: no filtering with results sorted
     * on the category index value.
     */
    public static ResultFilter createDefaultForumFilter() {
        ResultFilter resultFilter = new ResultFilter();
        resultFilter.setSortField(JiveGlobals.FORUM_CATEGORY_INDEX);
        resultFilter.setSortOrder(ASCENDING);
        return resultFilter;
    }

    /**
     * Creates a default thread ResultFilter: no filtering with results sorted
     * on the thread modification date.
     */
    public static ResultFilter createDefaultThreadFilter() {
        ResultFilter resultFilter = new ResultFilter();
        return resultFilter;
    }

    /**
     * Creates a default message ResultFilter: no filtering with results sorted
     * on the message creation date.
     */
    public static ResultFilter createDefaultMessageFilter() {
        ResultFilter resultFilter = new ResultFilter();
        resultFilter.setSortField(JiveGlobals.CREATION_DATE);
        resultFilter.setSortOrder(ASCENDING);
        return resultFilter;
    }

    private int sortField = JiveGlobals.MODIFIED_DATE;
    private int sortOrder = DESCENDING;
    private String sortPropertyName = null;

    /**
     * The starting index for results. Default is 0.
     */
    private int startIndex = 0;

    /**
     * Number of results to return. Default is NULL_INT which means an unlimited
     * number of results.
     */
    private int numResults = NULL_INT;

    private long userID = NULL_INT;
    private List propertyNames = new ArrayList();
    private List propertyValues = new ArrayList();
    private Date creationDateRangeMin = null;
    private Date creationDateRangeMax = null;
    private Date modifiedDateRangeMin = null;
    private Date modifiedDateRangeMax = null;

    private int moderationRangeMin = NULL_INT;
    private int moderationRangeMax = NULL_INT;

    /**
     * Returns the userID that results will be filtered on. The method will
     * return NULL_INT if no user to filter on has been specified. The method
     * will return -1 if filtering is to take place on all "anonymous" users.
     *
     * @return the userID that results will be filtered on.
     */
    public long getUserID() {
        return userID;
    }

    /**
     * Sets the userID that results will be filtered on. If you'd like to filter
     * on "anonymous" users, pass in an id of -1. By default, no filtering on
     * userID's will take place. If you'd like to change so that no filtering
     * is performed, pass in ResultFilter.NULL_INT.
     *
     * @param userID the user ID to filter on.
     */
    public void setUserID(long userID) {
        this.userID = userID;
    }

    /**
     * Adds a property to the list of properties that will be filtered on.
     * For a message or thread to pass the property filter:<ul>
     *      <li> The message or thread must have a property with the same name
     *              as the filter.
     *      <li> The property value in the thread or message must exactly match
     *              the property value of the filter.
     * </ul>
     *
     * For example, say that we have a message with extended properties "color"
     * and "size" with the values "green" and "big". If we create a result
     * filter and specify that we should filter on "color=green" and
     * "size=small", the hypothetical message will be filtered out since the
     * size property values don't match.
     *
     * @param name the name of the property to filter on.
     * @param value the value of the property that results must match.
     */
    public void addProperty(String name, String value) {
        // Overwrite any existing entry in the property list with the same name.
        if (propertyNames.contains(name)) {
            int index = propertyNames.indexOf(name);
            propertyNames.remove(index);
            propertyValues.remove(index);
        }
        propertyNames.add(name);
        propertyValues.add(value);
    }

    /**
     * Returns the number of properties that results will be filtered on.
     *
     * @return the number of properties that results will be filtered on.
     */
    public int getPropertyCount() {
        return propertyNames.size();
    }

    /**
     * Returns the name of the property at the specified index in the list of
     * properties to be filtered on. If the index is invalid, null will be
     * returned.
     *
     * @return the name of the property at the specified index in the property
     *      filter list.
     */
    public String getPropertyName(int index) {
        if (index >= 0 && index < propertyNames.size()) {
            return (String)propertyNames.get(index);
        }
        else {
            return null;
        }
    }

    /**
     * Returns the value of the property at the specified index in the list of
     * properties to be filtered on. If the index is invalid, null will be
     * returned.
     *
     * @return the value of the property at the specified index in the property
     *      filter list.
     */
    public String getPropertyValue(int index) {
        if (index >= 0 && index < propertyValues.size()) {
            return (String)propertyValues.get(index);
        }
        else {
            return null;
        }
    }

    /**
     * Returns the creation date that represents the lower boundary for messages
     * or threads to be filtered on. If this value has not been set, the method
     * will return null.
     *
     * @return a Date representing the lower bound for creation dates to filter
     *      on.
     */
    public Date getCreationDateRangeMin() {
        return creationDateRangeMin;
    }

    /**
     * Sets the date that represents the lower boundary for messages or threads to
     * be selected by the result filter. If this value is not set the results filter will
     * be unbounded for the earliest creation date selected.<p>
     *
     * Setting a date range for a ResultFilter is a potential performance
     * bottleneck. For example, if the argument for the date range is "new Date()"
     * then the corresponding database query will map to an accuracy of
     * a particular millesecond in time. This means that the results can't be
     * cached. A better solution is to round dates to the nearest minute, hour,
     * etc (whatever accuracy you need).
     *
     * @param creationDateRangeMin Date representing the filter lowest value of
     *      the creation date to be selected.
     */
    public void setCreationDateRangeMin(Date creationDateRangeMin) {
        this.creationDateRangeMin = creationDateRangeMin;
    }

    /**
     * Returns a date that represents the upper boundry for messages or threads to
     * be selected by the result filter. If this value is not set it will return null
     * and the results filter will be unbounded for the latest creation date selected.
     *
     * @return a Date representing the filter highest value of the creation date to be
     * selected.
     */
    public Date getCreationDateRangeMax() {
        return creationDateRangeMax;
    }

    /**
     * Sets a date that represents the upper boundry for messages or threads to
     * be selected by the result filter. If this value is not set the results
     * filter will be unbounded for the latest creation date selected.
     *
     * Setting a date range for a ResultFilter is a potential performance
     * bottleneck. For example, if the argument for the date range is "new Date()"
     * then the corresponding database query will map to an accuracy of
     * a particular millesecond in time. This means that the results can't be
     * cached. A better solution is to round dates to the nearest minute, hour,
     * etc (whatever accuracy you need).
     *
     * @param creationDateRangeMax Date representing the filter lowest value of
     * the creation date range.
     */
    public void setCreationDateRangeMax(Date creationDateRangeMax) {
        this.creationDateRangeMax = creationDateRangeMax;
    }

    /**
     * Returns a date that represents the lower boundary for messages or threads
     * to be selected by the result filter. If this value is not set it will
     * return null and the results filter will be unbounded for the earliest
     * modified date selected.
     *
     * @return a Date representing the filter lowest value of the modified date
     *      range.
     */
    public Date getModifiedDateRangeMin() {
        return modifiedDateRangeMin;
    }