001: /*
002: * NEMESIS-FORUM.
003: * Copyright (C) 2002 David Laurent(lithium2@free.fr). All rights reserved.
004: *
005: * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
006: *
007: * Copyright (C) 2001 Yasna.com. All rights reserved.
008: *
009: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
010: *
011: * NEMESIS-FORUM. is free software; you can redistribute it and/or
012: * modify it under the terms of the Apache Software License, Version 1.1,
013: * or (at your option) any later version.
014: *
015: * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
016: * application are parts of NEMESIS-FORUM and are distributed under
017: * same terms of licence.
018: *
019: *
020: * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
021: * and software developed by CoolServlets.com (http://www.coolservlets.com).
022: * and software developed by Yasna.com (http://www.yasna.com).
023: *
024: */
025: package org.nemesis.forum;
026:
027: import java.util.Iterator;
028: import java.util.PropertyResourceBundle;
029:
030: import org.apache.commons.logging.Log;
031: import org.apache.commons.logging.LogFactory;
032: import org.nemesis.forum.proxy.ForumFactoryProxy;
033: import org.nemesis.forum.exception.ForumAlreadyExistsException;
034: import org.nemesis.forum.exception.ForumNotFoundException;
035: import org.nemesis.forum.exception.UnauthorizedException;
036:
037: /**
038: * A ForumFactory provides access to and management of Forums. It is the point
039: * of entry for the entire system.
040: * <p>
041: * A concrete instance of ForumFactory can be obtained by calling the getInstance()
042: * method with an Authorization token. The Authorization token determines with
043: * what permissions the rest of the objects in the system will be accessed with.
044: * <p>
045: * Usually the first steps of any program interacting with the system are:
046: * <ul>
047: * <li> Obtain an authorization token by calling
048: * AuthorizationFactory.getInstance().getAuthorization(username, password);
049: * <li> Use that authorization to get a ForumFactory instance.
050: * <li> Use the forum factory to access forums and other content.
051: * </ul>
052: * It is also possible to access content with anonymous permissions. See
053: * the AuthorizationFactory class for more information.
054: * <p>
055: * ForumFactory is an abstract class so that the actual implementation is
056: * pluggable. For example, the default implementation uses a database
057: * backend. You can optionally plug in your own backend that might use the
058: * filesystem, for example. When first creating the forum factory, will
059: * look for the property "ForumFactory.className". If it fails to find
060: * that property, it will use the default class.
061: *
062: * @see AuthorizationFactory
063: */
064: public abstract class ForumFactory {
065:
066: static protected Log log = LogFactory.getLog(ForumFactory.class);
067:
068: private static Object initLock = new Object();
069:
070: //singleton
071: private static ForumFactory factory = null;
072:
073: private static String Impl = (String) ((PropertyResourceBundle) PropertyResourceBundle
074: .getBundle("org.nemesis.forum.config"))
075: .getObject("ForumFactory.class");
076:
077: /**
078: * Returns a concrete ForumFactory instance. Permissions corresponding
079: * to the Authorization will be used. If getting the factory fails, null
080: * will be returned.
081: *
082: * @param authorization the auth token for the user.
083: * @return a concrete ForumFactory instance.
084: */
085: public static ForumFactory getInstance(Authorization authorization) {
086: //If no valid authorization passed in, return null.
087: if (authorization == null) {
088: return null;
089: }
090: if (factory == null) {
091: synchronized (initLock) {
092: if (factory == null) {
093:
094: try {
095: //Load the class and create an instance.
096: Class c = Class.forName(Impl);
097: factory = (ForumFactory) c.newInstance();
098: } catch (Exception e) {
099: log.fatal("Failed to load ForumFactory class "
100: + Impl
101: + ". forum cannot function normally.",
102: e);
103:
104: return null;
105: }
106: }
107: }
108: }
109:
110: //Wrap the factory with a proxy to provide security. We also pass
111: //in the username and password to the proxy for its special
112: //implementation of the getForum() method. See below for more details.
113: ForumFactoryProxy proxy = new ForumFactoryProxy(factory,
114: authorization, factory.getPermissions(authorization));
115: return proxy;
116: }
117:
118: /**
119: * Creates a new forum. This method should always be used instead of
120: * trying to instantiate a forum directly.
121: *
122: * @param name the name of the forum.
123: * @param description the description of the forum.
124: * @throws UnauthorizedException if not allowed to create a Forum.
125: * @throws ForumAlreadExistsException if the forum name already exists.
126: */
127: public abstract Forum createForum(String name, String description)
128: throws UnauthorizedException, ForumAlreadyExistsException;
129:
130: /**
131: * Returns the forum with the specified forumID.
132: *
133: * @param forumID the id of the forum to return.
134: * @return the Forum specified by forumID.
135: * @throws UnauthorizedException if not allowed to read the forum.
136: * @throws ForumNotFoundException if the requested forum does not exist.
137: */
138: public abstract Forum getForum(int forumID)
139: throws ForumNotFoundException, UnauthorizedException;
140:
141: /**
142: * Returns the Forum with the specified name.
143: *
144: * @param name the name of the forum to return.
145: * @return the forum with the specified name.
146: * @throws ForumNotFoundException if the requested forum does not exist.
147: * @throws UnauthorizedException if not allowed to read the forum.
148: */
149: public abstract Forum getForum(String name)
150: throws ForumNotFoundException, UnauthorizedException;
151:
152: /**
153: * Returns the total number of forums. This number might not agree
154: * with the number of forums returned by ForumFactory.forums() since that
155: * method return an Iterator of forums that a user has READ access for.
156: *
157: * @return the total number of forums.
158: */
159: public abstract int getForumCount();
160:
161: /**
162: * Returns an Iterator of Forum objects for all the forums in the system
163: * that the user has READ access for. Read access can be granted in the
164: * following ways:
165: * <ul>
166: * <li> Anonymous read permission is enabled for the forum; anyone can
167: * read it.
168: * <li> The "all users" read permission is set so that any registered
169: * user can read the forum.
170: * <li> The user belongs to a group that has been granted read permission.
171: * <li> The user has been specifically granted read permission.
172: * <li> The current user is a system admin or admin of this forum. This
173: * allows automatic read permission.
174: * </ul>
175: *
176: * @return an Iterator of Forum objects for all forums in the system that
177: * the user has read permission for.
178: */
179: public abstract Iterator forums();
180:
181: /**
182: * Returns an Iterator of Forum objects for all the forums in the system
183: * that the user has Moderation, Forum Admin or System Admin access to.
184: */
185:
186: public abstract Iterator forumsModeration();
187:
188: /**
189: * Deletes a forum and all of its content. This method is not always
190: * guaranteed to be safe to call. For example, if multiple clients have
191: * handles on a forum, and that forum is subsequently deleted, the behavior
192: * of the forum objects that the clients have handles on is unspecified and
193: * may result in errors.
194: *
195: * @param forum the forum to delete.
196: * @throws UnauthorizedException if not allowed to delete a forum.
197: */
198: public abstract void deleteForum(Forum forum)
199: throws UnauthorizedException;
200:
201: /**
202: * Returns a ProfileManager that can be used to manage Users and Groups.
203: */
204: public abstract ProfileManager getProfileManager();
205:
206: /**
207: * Returns the search indexer which can be used to manage the index used
208: * to perform searches.
209: *
210: * @throws UnauthorizedException if not a system administator.
211: * @return a search indexer.
212: */
213: //public abstract SearchIndexer getSearchIndexer()
214: // throws UnauthorizedException;
215: /**
216: * Returns all the userID's of users with a particular system permission.
217: * System permissions apply to all forums.
218: *
219: * @throws UnauthorizedException if does not have ADMIN permissions.
220: */
221: public abstract int[] usersWithPermission(int permissionType)
222: throws UnauthorizedException;
223:
224: /**
225: * Returns all the groupID's of groups with a particular system permission.
226: * System permissions apply to all forums.
227: *
228: * @throws UnauthorizedException if does not have ADMIN permissions.
229: */
230: public abstract int[] groupsWithPermission(int permissionType)
231: throws UnauthorizedException;
232:
233: /**
234: * Returns the permissions for the factory that correspond to the
235: * passed-in Authorization.
236: *
237: * @param authorization the auth token for the user.
238: * @return the permissions for this object.
239: */
240: public abstract ForumPermissions getPermissions(
241: Authorization authorization);
242:
243: /**
244: * Returns true if the handle on the object has the permission specified.
245: * A list of possible permissions can be found in the ForumPermissions
246: * class. Certain methods of this class are restricted to certain
247: * permissions as specified in the method comments.
248: *
249: * @param type the type of permission to check for.
250: * @see ForumPermissions
251: */
252: public abstract boolean hasPermission(int type);
253: }
|