forumcategory.java

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

/**
 * $RCSfile: ForumCategory.java,v $
 * $Revision: 1.7 $
 * $Date: 2002/04/02 21:16:56 $
 *
 * Copyright (C) 1999-2002 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.Iterator;
import java.util.Date;

/**
 * A container for forums and a hierarchy of other forum categories. In other
 * words, the category structure is a tree, with lists of forums for every
 * category node. There is always a "root" forum category (ID of 1), of which
 * all other categories are children.
 *
 * Category names are not unique, therefore it is not possible to load a
 * category by name.
 *
 * @see ForumFactory#getRootForumCategory
 * @see ForumFactory#getForumCategory(long)
 * @author Matt Tucker
 */
public interface ForumCategory {

    /**
     * Returns the ID of the category.
     *
     * @return the ID of the category.
     */
    public long getID();

    /**
     * Returns the name of the category.
     *
     * @return the name of the category.
     */
    public String getName();

    /**
     * Sets the name of the forum category.
     *
     * @param name the name of the forum category.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void setName(String name) throws UnauthorizedException;

    /**
     * Returns the description of the forum category.
     *
     * @return the description of the forum category.
     */
    public String getDescription();

    /**
     * Sets the description of the forum category.
     *
     * @param description the description of the forum category.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void setDescription(String description) throws UnauthorizedException;

    /**
     * Returns the Date that the category was created.
     *
     * @return the Date the forum category was created.
     */
    public Date getCreationDate();

    /**
     * Sets the creation date of the category. In most cases, the creation date
     * will default to when the category was entered into the system. However,
     * the creation date needs to be set manually when importing data.
     * In other words, skin authors should ignore this method since it only
     * intended for system maintenance.
     *
     * @param creationDate the date the forum category was created.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void setCreationDate(Date creationDate) throws UnauthorizedException;

    /**
     * Returns the Date that the category was last modified. In other words, the
     * date of the most recent forum update in the category.
     *
     * @return the Date the forum was last modified.
     */
    public Date getModifiedDate();

    /**
     * Sets the date the category was last modified. In most cases, last modifed
     * will default to when the category data was last changed. However,
     * the last modified date needs to be set manually when importing data.
     * In other words, skin authors should ignore this method since it only
     * intended for system maintenance.
     *
     * @param modifiedDate the date the forum was modified.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void setModifiedDate(Date modifiedDate) throws UnauthorizedException;

    /**
     * Returns an extended property of the category. Each category can have an
     * arbitrary number of extended properties. This allows for enhanced
     * functionality that is not part of the base interface.
     *
     * @param name the name of the property to get.
     * @return the value of the property specified by <tt>name</tt>.
     */
    public String getProperty(String name);

    /**
     * Sets an extended property of the category. Each category can have an
     * arbitrary number of extended properties. This allows for enhanced
     * functionality that is not part of the base interface.<p>
     *
     * If the property referenced by <code>name</code> already exists, its
     * value will be updated.
     *
     * @param name the name of the property to set.
     * @param value the new value for the property.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void setProperty(String name, String value)
            throws UnauthorizedException;

    /**
     * Deletes an extended property. If the property specified by
     * <tt>name</tt> does not exist, this method will do nothing.
     *
     * @param name the name of the property to delete.
     * @throws UnauthorizedException if does not have admin permissions.
     */
    public void deleteProperty(String name) throws UnauthorizedException;

    /**
     * Returns an Iterator for the names of the forum category properties.
     *
     * @return an Iterator for the names of the forum category properties.
     */
    public Iterator propertyNames();

    /**
     * Returns the number of forums in the category.
     *
     * @return the number of forums in the category.
     */
    public int getForumCount();

    /**
     * Returns the number of forums in the category based on the specified
     * ResultFilter. This is useful for determining such things as the number
     * of forums in a date range, etc.
     *
     * @param resultFilter a resultFilter to limit the query on.
     * @return the number of forums in the category based on the filter.
     */
    public int getForumCount(ResultFilter resultFilter);

    /**
     * Returns the number of forums in the category and all sub-categories.
     *
     * @return the number of forums in the category and sub-categories.
     */
    public int getRecursiveForumCount();

    /**
     * Returns the number of forums in the category and all sub-categories
     * based on the specified ResultFilter. This is useful for determining such
     * things as the number of forums in a date range, etc.
     *
     * @param resultFilter a resultFilter to limit the query on.
     * @return the number of forums in the category and sub-categories based on
     *      the filter.
     */
    public int getRecursiveForumCount(ResultFilter resultFilter);

    /**
     * Returns an Iterator for all the forums in the category. Forums will be
     * sorted based on their category index.
     *
     * @return an Iterator for all the forums in the category.
     */
    public Iterator forums();

    /**
     * Returns a Iterator for all the forums in the category that match the
     * criteria specified by the ResultFilter.
     *
     * @param resultFilter a ResultFilter object to perform filtering and
     *      sorting with.
     * @return an Iterator for the forums in the category that match the
     *      ResultFilter.
     */
    public Iterator forums(ResultFilter resultFilter);

    /**
     * Returns an Iterator for all the forums in the category and all
     * sub-categories. The ordering of forums in unspecified.
     *
     * @return an Iterator for all the forums in the category and sub-categories.
     */
    public Iterator recursiveForums();

    /**
     * Returns a Iterator for all the forums in the category and sub-categories
     * that match the criteria specified by the ResultFilter. Note that attempting
     * to sort the forums on their category index will have strange results.
     *
     * @param resultFilter a ResultFilter object to perform filtering and
     *      sorting with.
     * @return an Iterator for the forums in the category and sub-categories
     *      that match the ResultFilter.
     */
    public Iterator recursiveForums(ResultFilter resultFilter);

    /**
     * Sets the index of the forum in the category. The index value can be used
     * to display the forums in a category in an arbitrary order. Index values
     * are from 0 to getForumCount() - 1.
     *
     * @param forum the forum to adjust the index of.
     * @param newIndex the new index value for the forum.
     */
    public void setForumIndex(Forum forum, int newIndex)
            throws UnauthorizedException;

    /**
     * Moves a forum from this category to another.
     *
     * @param forum the forum to move.
     * @param destinationCategory the category to move the forum to.
     * @throws UnauthorizedException if not an admin for this category and
     *      the destination category.
     */
    public void moveForum(Forum forum, ForumCategory destinationCategory)
            throws UnauthorizedException;

    /**
     * Returns the parent category of this category. This method will return
     * <tt>null</tt> if the current category is the root category.
     *
     * @return the parent category of this category.
     */
    public ForumCategory getParentCategory();

    /**
     * Returns the number of sub-categories of this category.
     *
     * @return the number of sub-categories in this category.
     */
    public int getCategoryCount();

    /**
     * Returns an Iterator for the child categories of this category.
     *
     * @return the child categories of this category.
     */
    public Iterator categories();

    /**
     * Returns the total count of all sub-categories of this category, including
     * sub-categories of sub-categories, etc.
     *
     * @return the recursive sub-category count of this category.
     */
    public int getRecursiveCategoryCount();

    /**
     * Returns an Iterator for all sub-categories of this category, including
     * sub-categories of sub-categories, etc.
     *
     * @return an Iterator for the recursive sub-categories of this category.
     */
    public Iterator recursiveCategories();

    /**
     * Returns the depth of a this category relative to the root. For example,
     * consider the following tree (where <tt>1</tt> is the root category):
     *
     * <pre>
     *   1
     *   |-- 3
     *   |-- |-- 4
     *   |-- |-- |-- 7
     * </pre>
     *
     * The depth of message 4 is 2, the depth of category 7 is 3, etc. This
     * method is useful in combination with the {@link #recursiveCategories()}
     * Iterator to build a UI of hierarchical categories.
     *
     * @return the depth of the category in the category tree.
     */
    public int getCategoryDepth();

    /**
     * Sets the display order of a sub-category. For example, if a sub-category
     * has an index of 0, then it will returned first in the Iterator resulting
     * from the categories method call.
     *
     * @param subCategory
     * @param newIndex
     * @throws UnauthorizedException
     */
    public void setCategoryIndex(ForumCategory subCategory, int newIndex)
            throws UnauthorizedException;

    /**
     * Moves a sub-category to another category. You cannot move a category
     * into a child category. For example, take the following category tree:
     *
     * <pre>
     *   1
     *   |-- 3
     *   |-- |-- 4
     *   |-- |-- |-- 7
     * </pre>
     *
     * Moving 3 to be a child of 7 is not allowed, since that breaks the
     * tree structure.
     *
     * @param subCategory the ForumCategory to move.
     * @param destinationCategory the category to move the sub-category to.
     * @throws UnauthorizedException if not an admin of this category and
     *      the destination category.
     */
    public void moveCategory(ForumCategory subCategory, ForumCategory
            destinationCategory) throws UnauthorizedException;

    /**
     * Creates a new ForumCategory as a sub-category of this category using
     * the name and description.
     *
     * @param name the name of the new category.
     * @param description the description of the new category.
     * @return a new ForumCategory.
     * @throws UnauthorizedException if not an admin.
     */
    public ForumCategory createCategory(String name, String description)
            throws UnauthorizedException;

    /**
     * Deletes a sub-category. Only direct children of this category can
     * be deleted using this method. Attempting to delete a category that is
     * not a direct child will throw an IllegalArgumentException.
     *
     * @param subCategory the ForumCategory to delete.
     * @throws UnauthorizedException if not an admin.
     */
    public void deleteCategory(ForumCategory subCategory)
            throws UnauthorizedException;

    /**
     * Returns a permissions manager that can be used to set permissions for
     * this category. Only admins can perform this function.
     *
     * @return a PermissionsManager to manage the permissions on this forum.
     * @throws UnauthorizedException is not an admin.
     */
    public PermissionsManager getPermissionsManager()
            throws UnauthorizedException;

    /**
     * Returns the permissions for the category that correspond to the
     * passed-in Authorization. This method is not generally useful to skin
     * writers. Instead, the hasPermission(int) method should be used for
     * permission checking.
     *
     * @param authorization the auth token to lookup permissions for.
     */
    public ForumPermissions getPermissions(Authorization authorization);

    /**
     * Returns true if the handle on the object has the permission specified.
     * For example, if a category administrator has a handle on this object, then
     * calling hasPermission(ForumPermissions.CATEGORY_ADMIN) would return true.<p>
     *
     * A list of possible permissions can be found in the ForumPermissions
     * class. Certain methods of this class are restricted to certain
     * permissions as specified in the method comments.
     *
     * @param type a permission type from the ForumPermissions class.
     * @return true if the handle on the object has the specified permission.
     * @see ForumPermissions
     */
    public boolean hasPermission(int type);
}