forumfactory.java

Jive论坛2.5版本的源程序

/**
 * $RCSfile: ForumFactory.java,v $
 * $Revision: 1.1.1.1 $
 * $Date: 2002/09/09 13:50:42 $
 *
 * New Jive  from Jdon.com.
 *
 * This software is the proprietary information of CoolServlets, Inc.
 * Use is subject to license terms.
 */

package com.jivesoftware.forum;

import java.lang.reflect.*;
import java.util.*;

/**
 * A ForumFactory provides access to and management of Forums. It is the point
 * of entry for the entire Jive system.
 * <p>
 * A concrete instance of ForumFactory can be obtained by calling the getInstance()
 * method with an Authorization token. The Authorization token determines with
 * what permissions the rest of the objects in the system will be accessed with.
 * <p>
 * Usually the first steps of any program interacting with the Jive system are:
 * <ul>
 *   <li> Obtain an authorization token by calling
 *    AuthorizationFactory.getInstance().getAuthorization(username, password);
 *   <li> Use that authorization to get a ForumFactory instance.
 *   <li> Use the forum factory to access forums and other Jive content.
 * </ul>
 * It is also possible to access Jive content with anonymous permissions. See
 * the AuthorizationFactory class for more information.
 * <p>
 * ForumFactory is an abstract class so that the actual implementation is
 * pluggable. For example, the default Jive implementation uses a database
 * backend. You can optionally plug in your own backend that might use the
 * filesystem, for example. When first creating the forum factory, Jive will
 * look for the Jive property "ForumFactory.className". If it fails to find
 * that property, it will use the default class.
 *
 * @see AuthorizationFactory
 */
public abstract class ForumFactory {

    private static Object initLock = new Object();
    private static String className = "com.jivesoftware.forum.database.DbForumFactory";
    private static ForumFactory factory = null;

    /**
     * Returns a concrete ForumFactory instance. Permissions corresponding
     * to the Authorization will be used. If getting the factory fails, null
     * will be returned.
     *
     * @param authorization the auth token for the user.
     * @return a concrete ForumFactory instance.
     */
    public static ForumFactory getInstance(Authorization authorization) {
        //If no valid authorization passed in, return null.
        if (authorization == null) {
            return null;
        }
        if (factory == null) {
            synchronized(initLock) {
                if (factory == null) {
                    // Note, the software license expressely forbids
                    // tampering with this check.
                    //LicenseManager.validateLicense("Jive Forums Basic", "2.0");

                    String classNameProp =
                        JiveGlobals.getJiveProperty("ForumFactory.className");
                    if (classNameProp != null) {
                        className = classNameProp;
                    }
                    try {
                        //Load the class and create an instance.
                        Class c = Class.forName(className);
                        factory = (ForumFactory)c.newInstance();
                    }
                    catch (Exception e) {
                        System.err.println("Failed to load ForumFactory class "
                            + className + ". Jive cannot function normally.");
                        e.printStackTrace();
                        return null;
                    }
                }
            }
        }
        //Now, create a forum factory proxy.
        return new ForumFactoryProxy(authorization, factory,
                factory.getPermissions(authorization));
    }

    /**
     * Creates a new forum. This method should always be used instead of
     * trying to instantiate a forum directly.
     *
     * @param name the name of the forum.
     * @param description the description of the forum.
     * @throws UnauthorizedException if not allowed to create a Forum.
     * @throws ForumAlreadExistsException if the forum name already exists.
     */
    public abstract Forum createForum(String name, String description)
            throws UnauthorizedException, ForumAlreadyExistsException;

    /**
     * Factory method to create a new thread. A root message must supplied
     * when creating the thread. Therefore, the following pattern should
     * be applied to add a new thread to a forum:<ul>
     *      <li>Create a new message, and set each of its properties such as
     *          the subject and body.
     *      <li>Create a new thread using the root message just created.
     *      <li>Set any properties on the new thread.
     *      <li>Add the thread to the forum by calling the addThread(ForumThread)
     *          method.</ul>
     *
     * Note that creating the ForumThread object is only one step of the process.
     * You must also add the thread to the forum with the addThread(ForumThread)
     * method.
     *
     * @param forum the forum to create the thread in.
     * @param rootMessage the root message of the thread.
     * @return a new ForumThread object.
     * @throws UnauthorizedException if does not have CREATE_THREAD permissions.
     */
    public abstract ForumThread createThread(ForumMessage rootMessage) throws
            UnauthorizedException;

    /**
     * Factory method to create a message with an anonymous author.
     */
    public abstract ForumMessage createMessage();

    /**
     * Factory method to create a message.
     *
     * @param user the author of the message.
     * @throws UnauthorizedException if does not have  permissions.
     */
    public abstract ForumMessage createMessage(User user)
            throws UnauthorizedException;

    /**
     * Returns the forum with the specified forumID.
     *
     * @param forumID the id of the forum to return.
     * @return the Forum specified by forumID.
     * @throws UnauthorizedException if not allowed to read the forum.
     * @throws ForumNotFoundException if the requested forum does not exist.
     */
    public abstract Forum getForum(long forumID)
            throws ForumNotFoundException, UnauthorizedException;

    /**
     * Returns the Forum with the specified name.
     *
     * @param name the name of the forum to return.
     * @return the forum with the specified name.
     * @throws ForumNotFoundException if the requested forum does not exist.
     * @throws UnauthorizedException if not allowed to read the forum.
     */
    public abstract Forum getForum(String name)
            throws ForumNotFoundException, UnauthorizedException;

    /**
     * Returns the total number of forums. This number might not agree
     * with the number of forums returned by ForumFactory.forums() since that
     * method return an Iterator of forums that a user has READ access for.
     *
     * @return the total number of forums.
     */
    public abstract int getForumCount();

    /**
     * Returns an Iterator of Forum objects for all the forums in the system
     * that the user has READ access for. Read access can be granted in the
     * following ways:
     * <ul>
     *   <li> Anonymous read permission is enabled for the forum; anyone can
     *        read it.
     *   <li> The "all users" read permission is set so that any registered
     *        user can read the forum.
     *   <li> The user belongs to a group that has been granted read permission.
     *   <li> The user has been specifically granted read permission.
     *   <li> The current user is a system admin or admin of this forum. This
     *        allows automatic read permission.
     * </ul>
     *
     * @return an Iterator of Forum objects for all forums in the system that
     *    the user has read permission for.