resultfilter.java

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

    /**
     * Sets a 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 modified 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 modifiedDateRangeMin Date representing the filter lowest value of
     *      the modified date to be selected.
     */
    public void setModifiedDateRangeMin(Date modifiedDateRangeMin) {
        this.modifiedDateRangeMin = modifiedDateRangeMin;
    }

    /**
     * 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 modified date selected.
     *
     * @return a Date representing the filter highest value of the modified date to be
     * selected.
     */
    public Date getModifiedDateRangeMax() {
        return modifiedDateRangeMax;
    }

    /**
     * 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 modified 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 modifiedDateRangeMax Date representing the filter lowest value of
     * the modified date range.
     */
    public void setModifiedDateRangeMax(Date modifiedDateRangeMax) {
        this.modifiedDateRangeMax = modifiedDateRangeMax;
    }

    /*
     * Returns the currently selected sort field. Default is
     * JiveGlobals.MODIFIED_DATE.
     *
     * @return current sort field.
     */
    public int getSortField() {
        return sortField;
    }

    /**
     * Sets the sort field to use. Default is JiveGlobals.MODIFIED_DATE .
     * If the sortField is set to JiveGlobals.EXTENDED_PROPERTY, the name of
     * the property must be set by a subsequent call to
     * setSortPropertyName(String).
     *
     * @param sortField the field that will be used for sorting.
     */
    public void setSortField(int sortField) {
        this.sortField = sortField;
    }

    /**
     * Returns the name of the extended property that will be sorted on.
     * Returns null if sorting will not be done on a property.
     *
     * @return the extended property that will be sorted on.
     */
    public String getSortPropertyName() {
        return this.sortPropertyName;
    }

    /**
     * Sets the property name to sort on. You must also call the setSortField(int)
     * method with JiveGlobals.EXTENDED_PROPERTY as an argument.
     *
     * @param sortPropertyName the name of the extended property to sort on.
     */
    public void setSortPropertyName(String sortPropertyName) {
        this.sortPropertyName = sortPropertyName;
    }

    /**
     * Returns the sort order, which will be ResultFilter.ASCENDING for
     * ascending sorting, or ResultFilter.DESCENDING for descending sorting.
     * Descending sorting is: 3, 2, 1, etc. Ascending sorting is 1, 2, 3, etc.
     *
     * @return the sort order.
     */
    public int getSortOrder() {
        return this.sortOrder;
    }

    /**
     * Sets the sort type. Valid arguments are ResultFilter.ASCENDING for
     * ascending sorting or ResultFilter.DESCENDING for descending sorting.
     * Descending sorting is: 3, 2, 1, etc. Ascending sorting is 1, 2, 3, etc.
     *
     * @param sortOrder the order that results will be sorted in.
     */
    public void setSortOrder(int sortOrder) {
        if (! (sortOrder == ResultFilter.ASCENDING ||
               sortOrder == ResultFilter.DESCENDING)
            )
        {
            throw new IllegalArgumentException();
        }
        this.sortOrder = sortOrder;
    }

    /**
     * Returns the max number of results that should be returned.
     * The default value for is NULL_INT, which means there will be no limit
     * on the number of results. This method can be used in combination with
     * setStartIndex(int) to perform pagination of results.
     *
     * @return the max number of results to return.
     * @see #setStartIndex(int)
     */
    public int getNumResults() {
        return numResults;
    }

    /**
     * Sets the limit on the number of results to be returned.
     *
     * @param numResults the number of results to return.
     */
    public void setNumResults(int numResults) {
        if (numResults < 0) {
            throw new IllegalArgumentException("numResults cannot be less than 0.");
        }
        this.numResults = numResults;
    }

    /**
     * Returns the index of the first result to return.
     *
     * @return the index of the first result which should be returned.
     */
    public int getStartIndex() {
        return startIndex;
    }

    /**
     * Sets the index of the first result to return. For example, if the start
     * index is set to 20, the Iterator returned will start at the 20th result
     * in the query. This method can be used in combination with
     * setNumResults(int) to perform pagination of results.
     *
     * @param startIndex the index of the first result to return.
     */
    public void setStartIndex(int startIndex) {
        if (startIndex < 0) {
            throw new IllegalArgumentException("A start index less than 0 is not valid.");
        }
        this.startIndex = startIndex;
    }

    /**
     * Returns the moderation value that represents the lower boundry for
     * messages or threads to be selected by the result filter. If this value
     * is not set it will return the lowest moderation value allowed and the
     * results filter will be unbounded for the lowest moderation value selected.
     *
     * For example if boolean moderation is being used, the possible values that
     * can be expected of a message are -1 for rejected messages, 0 unapproved
     * messages, and 1 for approved messages.  To show messages available
     * for the general public, you would pass this accessor a minimum value
     * of 1 and a maximum value of 1 or higher.  To show messages in need of
     * moderation you would pass this accessor a minimum value of 0 and a
     * maximum value of 0.  To show messages in need of moderation in the
     * context of threads that are already approved, you would pass this accessor
     * a minumum value of 0 and a maximum value of 1.
     *
     * @return an int representing the lowest value of the moderation value to be
     * selected by the filter.
     */
    public int getModerationRangeMin() {
        return moderationRangeMin;
    }

    /**
     * Sets the moderation value that represents the lower bound for messages
     * or threads to be selected by the result filter. If this value is not
     * set, the lower bound will default to minimum set for the forum. If you
     * would like the moderation range to have now lower bound, simply pass in
     * a sufficiently small number such as
     *
     * @param moderationRangeMin int representing the lowest value of
     *      the moderation value range to be selected by the result filter.
     */
    public void setModerationRangeMin(int moderationRangeMin) {
        this.moderationRangeMin = moderationRangeMin;
    }

    /**
     * Returns the moderation value that represents the upper bound for
     * messages or threads to be selected by the result filter. If an upper
     * bound has not been set, this method will return ResultFilter.NULL_INT.
     *
     * @return the upper bound for moderation values to filter on.
     */
    public int getModerationRangeMax() {
        return moderationRangeMax;
    }

    /**
     * Sets the upper bound for the moderation value that will pass the
     * result filter. If this value is not set, or is set to
     * ResultFilter.NULL_INT there will be no upper bound on moderation values.
     *
     * @param moderationRangeMax the max value of the moderation value range.
     */
    public void setModerationRangeMax(int moderationRangeMax) {
        this.moderationRangeMax = moderationRangeMax;
    }

    /**
     * Rounds the given date down to the nearest specfied second. The following
     * table shows sample input and expected output values: (Note, only
     * the time portion of the date is shown for brevity) <p>
     *
     * <table border="1">
     * <tr>
     *     <th>Date</th><th>Seconds</th><th>Result</th>
     * </tr>
     * <tr>
     *     <td>1:37.48</td><td>5</td><td>1:37.45</td>
     * </tr>
     * <tr>
     *     <td>1:37.48</td><td>10</td><td>1:37.40</td>
     * </tr>
     * <tr>
     *     <td>1:37.48</td><td>30</td><td>1:37.30</td>
     * </tr>
     * <tr>
     *     <td>1:37.48</td><td>60</td><td>1:37.00</td>
     * </tr>
     * <tr>
     *     <td>1:37.48</td><td>120</td><td>1:36.00</td>
     * </tr>
     * </table><p>
     *
     * This method is useful when calculating the last post in
     * a forum or the number of new messages from a given date. Using a rounded
     * date allows Jive to internally cache the results of the date query.
     * Here's an example that shows the last posted message in a forum accurate
     * to the last 60 seconds: <p>
     *
     * <code>
     * ResultFilter filter = new ResultFilter(); <br>
     * filter.setSortOrder(ResultFilter.DESCENDING); <br>
     * filter.setSortField(JiveGlobals.CREATION_DATE); <br>
     * <b>filter.setCreationDateRangeMin(ResultFilter.roundDate(forum.getModifiedDate(), 60));</b> <br>
     * filter.setNumResults(1); <br>
     * Iterator messages = forum.messages(filter); <br>
     * ForumMessage lastPost = (ForumMessage)messages.next(); <br>
     * </code><p>
     *
     * @param date the <tt>Date</tt> we want to round.
     * @param seconds the number of seconds we want to round the date to.
     * @return the given date, rounded down to the nearest specified seconds.
     */
    public static Date roundDate(Date date, int seconds) {
        // Current time
        long time = date.getTime();
        // Do the rounding:
        long rounded = time - (time%(1000*seconds));
        // return the new date
        return new Date(rounded);
    }
}