001: /**
002: * Copyright (C) 2001 Yasna.com. All rights reserved.
003: *
004: * ===================================================================
005: * The Apache Software License, Version 1.1
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The end-user documentation included with the redistribution,
020: * if any, must include the following acknowledgment:
021: * "This product includes software developed by
022: * Yasna.com (http://www.yasna.com)."
023: * Alternately, this acknowledgment may appear in the software itself,
024: * if and wherever such third-party acknowledgments normally appear.
025: *
026: * 4. The names "Yazd" and "Yasna.com" must not be used to
027: * endorse or promote products derived from this software without
028: * prior written permission. For written permission, please
029: * contact yazd@yasna.com.
030: *
031: * 5. Products derived from this software may not be called "Yazd",
032: * nor may "Yazd" appear in their name, without prior written
033: * permission of Yasna.com.
034: *
035: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL YASNA.COM OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: *
049: * This software consists of voluntary contributions made by many
050: * individuals on behalf of Yasna.com. For more information
051: * on Yasna.com, please see <http://www.yasna.com>.
052: */
053:
054: /**
055: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
056: *
057: * ===================================================================
058: * The Apache Software License, Version 1.1
059: *
060: * Redistribution and use in source and binary forms, with or without
061: * modification, are permitted provided that the following conditions
062: * are met:
063: *
064: * 1. Redistributions of source code must retain the above copyright
065: * notice, this list of conditions and the following disclaimer.
066: *
067: * 2. Redistributions in binary form must reproduce the above copyright
068: * notice, this list of conditions and the following disclaimer in
069: * the documentation and/or other materials provided with the
070: * distribution.
071: *
072: * 3. The end-user documentation included with the redistribution,
073: * if any, must include the following acknowledgment:
074: * "This product includes software developed by
075: * CoolServlets.com (http://www.coolservlets.com)."
076: * Alternately, this acknowledgment may appear in the software itself,
077: * if and wherever such third-party acknowledgments normally appear.
078: *
079: * 4. The names "Jive" and "CoolServlets.com" must not be used to
080: * endorse or promote products derived from this software without
081: * prior written permission. For written permission, please
082: * contact webmaster@coolservlets.com.
083: *
084: * 5. Products derived from this software may not be called "Jive",
085: * nor may "Jive" appear in their name, without prior written
086: * permission of CoolServlets.com.
087: *
088: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
089: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
090: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
091: * DISCLAIMED. IN NO EVENT SHALL COOLSERVLETS.COM OR
092: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
093: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
094: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
095: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
096: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
097: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
098: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
099: * SUCH DAMAGE.
100: * ====================================================================
101: *
102: * This software consists of voluntary contributions made by many
103: * individuals on behalf of CoolServlets.com. For more information
104: * on CoolServlets.com, please see <http://www.coolservlets.com>.
105: */package com.Yasna.forum;
106:
107: import com.Yasna.forum.util.ClientIP;
108:
109: import java.lang.reflect.*;
110: import java.util.*;
111:
112: /**
113: * A ForumFactory provides access to and management of Forums. It is the point
114: * of entry for the entire Yazd system.
115: * <p>
116: * A concrete instance of ForumFactory can be obtained by calling the getInstance()
117: * method with an Authorization token. The Authorization token determines with
118: * what permissions the rest of the objects in the system will be accessed with.
119: * <p>
120: * Usually the first steps of any program interacting with the Yazd system are:
121: * <ul>
122: * <li> Obtain an authorization token by calling
123: * AuthorizationFactory.getInstance().getAuthorization(username, password);
124: * <li> Use that authorization to get a ForumFactory instance.
125: * <li> Use the forum factory to access forums and other Yazd content.
126: * </ul>
127: * It is also possible to access Yazd content with anonymous permissions. See
128: * the AuthorizationFactory class for more information.
129: * <p>
130: * ForumFactory is an abstract class so that the actual implementation is
131: * pluggable. For example, the default Yazd implementation uses a database
132: * backend. You can optionally plug in your own backend that might use the
133: * filesystem, for example. When first creating the forum factory, Yazd will
134: * look for the Yazd property "ForumFactory.className". If it fails to find
135: * that property, it will use the default class.
136: *
137: * @see AuthorizationFactory
138: */
139: public abstract class ForumFactory {
140:
141: private static Object initLock = new Object();
142: private static String className = "com.Yasna.forum.database.DbForumFactory";
143: private static ForumFactory factory = null;
144:
145: /**
146: * Returns a concrete ForumFactory instance. Permissions corresponding
147: * to the Authorization will be used. If getting the factory fails, null
148: * will be returned.
149: *
150: * @param authorization the auth token for the user.
151: * @return a concrete ForumFactory instance.
152: */
153: public static ForumFactory getInstance(Authorization authorization) {
154: //If no valid authorization passed in, return null.
155: if (authorization == null) {
156: return null;
157: }
158: if (factory == null) {
159: synchronized (initLock) {
160: if (factory == null) {
161: String classNameProp = PropertyManager
162: .getProperty("ForumFactory.className");
163: if (classNameProp != null) {
164: className = classNameProp;
165: }
166: try {
167: //Load the class and create an instance.
168: Class c = Class.forName(className);
169: factory = (ForumFactory) c.newInstance();
170: } catch (Exception e) {
171: System.err
172: .println("Failed to load ForumFactory class "
173: + className
174: + ". Yazd cannot function normally.");
175: e.printStackTrace();
176: return null;
177: }
178: }
179: }
180: }
181:
182: //Wrap the factory with a proxy to provide security. We also pass
183: //in the username and password to the proxy for its special
184: //implementation of the getForum() method. See below for more details.
185: ForumFactoryProxy proxy = new ForumFactoryProxy(factory,
186: authorization, factory.getPermissions(authorization));
187: return proxy;
188: }
189:
190: /**
191: * Creates a new forum. This method should always be used instead of
192: * trying to instantiate a forum directly.
193: *
194: * @param name the name of the forum.
195: * @param description the description of the forum.
196: * @param moderated when true - posted messages and threads must first be approved
197: * @param forumGroupID every forum belongs to a Category and ForumGroup
198: * @throws UnauthorizedException if not allowed to create a Forum.
199: * @throws ForumAlreadExistsException if the forum name already exists.
200: */
201: public abstract Forum createForum(String name, String description,
202: boolean moderated, int forumGroupID, boolean article)
203: throws UnauthorizedException, ForumAlreadyExistsException;
204:
205: /**
206: * Returns the forum with the specified forumID.
207: *
208: * @param forumID the id of the forum to return.
209: * @return the Forum specified by forumID.
210: * @throws UnauthorizedException if not allowed to read the forum.
211: * @throws ForumNotFoundException if the requested forum does not exist.
212: */
213: public abstract Forum getForum(int forumID)
214: throws ForumNotFoundException, UnauthorizedException;
215:
216: /**
217: * Returns the Forum with the specified name.
218: *
219: * @param name the name of the forum to return.
220: * @return the forum with the specified name.
221: * @throws ForumNotFoundException if the requested forum does not exist.
222: * @throws UnauthorizedException if not allowed to read the forum.
223: */
224: public abstract Forum getForum(String name)
225: throws ForumNotFoundException, UnauthorizedException;
226:
227: /**
228: * Returns the total number of forums. This number might not agree
229: * with the number of forums returned by ForumFactory.forums() since that
230: * method return an Iterator of forums that a user has READ access for.
231: *
232: * @return the total number of forums.
233: */
234: public abstract int getForumCount();
235:
236: /**
237: * Returns an Iterator of Category objects
238: *
239: * @return an Iterator of Category objects
240: */
241: public abstract Iterator categories();
242:
243: /**
244: * Returns the category with the specified categoryID.
245: *
246: * @param categoryID the id of the category to return.
247: * @return the Category specified by categoryID.
248: * @throws UnauthorizedException if not allowed to read the category.
249: * @throws CategoryNotFoundException if the requested category does not exist.
250: */
251: public abstract Category getCategory(int categoryID)
252: throws CategoryNotFoundException, UnauthorizedException;
253:
254: /**
255: * Returns the Category with the specified name.
256: *
257: * @param name the name of the category to return.
258: * @return the category with the specified name.
259: * @throws CategoryNotFoundException if the requested category does not exist.
260: * @throws UnauthorizedException if not allowed to read the forum.
261: */
262: public abstract Category getCategory(String name)
263: throws CategoryNotFoundException, UnauthorizedException;
264:
265: /**
266: * Creates a new Category.
267: *
268: * @param name the name of the category.
269: * @param description the description of the category.
270: * @throws UnauthorizedException if not allowed to create a Category.
271: * @throws CategoryAlreadExistsException if the category name already exists.
272: */
273: public abstract Category createCategory(String name,
274: String description) throws UnauthorizedException,
275: CategoryAlreadyExistsException;
276:
277: /**
278: * Returns an Iterator of Forum objects for all the forums in the system
279: * that the user has READ access for. Read access can be granted in the
280: * following ways:
281: * <ul>
282: * <li> Anonymous read permission is enabled for the forum; anyone can
283: * read it.
284: * <li> The "all users" read permission is set so that any registered
285: * user can read the forum.
286: * <li> The user belongs to a group that has been granted read permission.
287: * <li> The user has been specifically granted read permission.
288: * <li> The current user is a system admin or admin of this forum. This
289: * allows automatic read permission.
290: * </ul>
291: *
292: * @return an Iterator of Forum objects for all forums in the system that
293: * the user has read permission for.
294: */
295: public abstract Iterator forums();
296:
297: /**
298: * This method returns the iterator with all the forums including the forums that
299: * are used for discussions around an article or a webpage.
300: * @return an iterator with the forum objects
301: */
302: public abstract Iterator forumsWithArticlesForums();
303:
304: /**
305: * Returns an Iterator of Forum objects for all the forums in the system
306: * that the user has Moderation, Forum Admin or System Admin access to.
307: */
308:
309: public abstract Iterator forumsModeration();
310:
311: /**
312: * Deletes a forum and all of its content. This method is not always
313: * guaranteed to be safe to call. For example, if multiple clients have
314: * handles on a forum, and that forum is subsequently deleted, the behavior
315: * of the forum objects that the clients have handles on is unspecified and
316: * may result in errors.
317: *
318: * @param forum the forum to delete.
319: * @throws UnauthorizedException if not allowed to delete a forum.
320: */
321: public abstract void deleteForum(Forum forum)
322: throws UnauthorizedException;
323:
324: /**
325: * Deletes a category and all of its content. This method is not always
326: * guaranteed to be safe to call.
327: *
328: * @param category the category to delete.
329: * @throws UnauthorizedException if not allowed to delete a category.
330: */
331: public abstract void deleteCategory(Category category)
332: throws UnauthorizedException;
333:
334: /**
335: * Returns a ProfileManager that can be used to manage Users and Groups.
336: */
337: public abstract ProfileManager getProfileManager();
338:
339: /**
340: * Returns the search indexer which can be used to manage the index used
341: * by Yazd to perform searches.
342: *
343: * @throws UnauthorizedException if not a system administator.
344: * @return a search indexer.
345: */
346: public abstract SearchIndexer getSearchIndexer()
347: throws UnauthorizedException;
348:
349: /**
350: * Returns all the userID's of users with a particular system permission.
351: * System permissions apply to all forums.
352: *
353: * @throws UnauthorizedException if does not have ADMIN permissions.
354: */
355: public abstract int[] usersWithPermission(int permissionType)
356: throws UnauthorizedException;
357:
358: /**
359: * Returns all the groupID's of groups with a particular system permission.
360: * System permissions apply to all forums.
361: *
362: * @throws UnauthorizedException if does not have ADMIN permissions.
363: */
364: public abstract int[] groupsWithPermission(int permissionType)
365: throws UnauthorizedException;
366:
367: /**
368: * Returns the permissions for the factory that correspond to the
369: * passed-in Authorization.
370: *
371: * @param authorization the auth token for the user.
372: * @return the permissions for this object.
373: */
374: public abstract ForumPermissions getPermissions(
375: Authorization authorization);
376:
377: /**
378: * Returns true if the handle on the object has the permission specified.
379: * A list of possible permissions can be found in the ForumPermissions
380: * class. Certain methods of this class are restricted to certain
381: * permissions as specified in the method comments.
382: *
383: * @param type the type of permission to check for.
384: * @see ForumPermissions
385: */
386: public abstract boolean hasPermission(int type);
387:
388: /**
389: * This would create a query for all the forums.
390: * If you just need to query one forum you should use the createQuery method in the Forum class.
391: * @return
392: */
393: public abstract Query createQuery();
394:
395: /**
396: * This method adds the IP address to the black list.
397: * @param cip
398: * @throws UnauthorizedException
399: */
400: public abstract void BlackListIP(ClientIP cip, boolean add)
401: throws UnauthorizedException;
402:
403: /**
404: * This method checks to see if this ip address has been black listed.
405: * @param cip
406: * @return true if black listed
407: */
408: public abstract boolean isBlackListed(ClientIP cip);
409:
410: /**
411: * This method returns the thread for a page key that is specified.
412: * @param pageKey
413: * @return forumthread
414: */
415: public abstract ForumThread getArticleThread(String pageKey,
416: Forum forum) throws ForumThreadNotFoundException,
417: UnauthorizedException;
418:
419: public abstract Iterator getThreadTypeIterator();
420:
421: public abstract ThreadType getThreadType(int typeid);
422:
423: public abstract Iterator getSessionList();
424:
425: public abstract int getYesterdayUserCount();
426:
427: }
|