ForumFactory


1   /**
2    * Copyright (C) 2001 Yasna.com. All rights reserved.
3    *
4    * ===================================================================
5    * The Apache Software License, Version 1.1
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *       "This product includes software developed by
22   *        Yasna.com (http://www.yasna.com)."
23   *    Alternately, this acknowledgment may appear in the software itself,
24   *    if and wherever such third-party acknowledgments normally appear.
25   *
26   * 4. The names "Yazd" and "Yasna.com" must not be used to
27   *    endorse or promote products derived from this software without
28   *    prior written permission. For written permission, please
29   *    contact yazd@yasna.com.
30   *
31   * 5. Products derived from this software may not be called "Yazd",
32   *    nor may "Yazd" appear in their name, without prior written
33   *    permission of Yasna.com.
34   *
35   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38   * DISCLAIMED.  IN NO EVENT SHALL YASNA.COM OR
39   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46   * SUCH DAMAGE.
47   * ====================================================================
48   *
49   * This software consists of voluntary contributions made by many
50   * individuals on behalf of Yasna.com. For more information
51   * on Yasna.com, please see <http://www.yasna.com>.
52   */
53  
54  /**
55   * Copyright (C) 2000 CoolServlets.com. All rights reserved.
56   *
57   * ===================================================================
58   * The Apache Software License, Version 1.1
59   *
60   * Redistribution and use in source and binary forms, with or without
61   * modification, are permitted provided that the following conditions
62   * are met:
63   *
64   * 1. Redistributions of source code must retain the above copyright
65   *    notice, this list of conditions and the following disclaimer.
66   *
67   * 2. Redistributions in binary form must reproduce the above copyright
68   *    notice, this list of conditions and the following disclaimer in
69   *    the documentation and/or other materials provided with the
70   *    distribution.
71   *
72   * 3. The end-user documentation included with the redistribution,
73   *    if any, must include the following acknowledgment:
74   *       "This product includes software developed by
75   *        CoolServlets.com (http://www.coolservlets.com)."
76   *    Alternately, this acknowledgment may appear in the software itself,
77   *    if and wherever such third-party acknowledgments normally appear.
78   *
79   * 4. The names "Jive" and "CoolServlets.com" must not be used to
80   *    endorse or promote products derived from this software without
81   *    prior written permission. For written permission, please
82   *    contact webmaster@coolservlets.com.
83   *
84   * 5. Products derived from this software may not be called "Jive",
85   *    nor may "Jive" appear in their name, without prior written
86   *    permission of CoolServlets.com.
87   *
88   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
89   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
90   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
91   * DISCLAIMED.  IN NO EVENT SHALL COOLSERVLETS.COM OR
92   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
93   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
94   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
95   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
96   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
97   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
98   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
99   * 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  */
106 
107 package com.Yasna.forum;
108 
109 import com.Yasna.forum.util.ClientIP;
110 
111 import java.lang.reflect.*;
112 import java.util.*;
113 
114 /**
115  * A ForumFactory provides access to and management of Forums. It is the point
116  * of entry for the entire Yazd system.
117  * <p>
118  * A concrete instance of ForumFactory can be obtained by calling the getInstance()
119  * method with an Authorization token. The Authorization token determines with
120  * what permissions the rest of the objects in the system will be accessed with.
121  * <p>
122  * Usually the first steps of any program interacting with the Yazd system are:
123  * <ul>
124  *   <li> Obtain an authorization token by calling
125  *    AuthorizationFactory.getInstance().getAuthorization(username, password);
126  *   <li> Use that authorization to get a ForumFactory instance.
127  *   <li> Use the forum factory to access forums and other Yazd content.
128  * </ul>
129  * It is also possible to access Yazd content with anonymous permissions. See
130  * the AuthorizationFactory class for more information.
131  * <p>
132  * ForumFactory is an abstract class so that the actual implementation is
133  * pluggable. For example, the default Yazd implementation uses a database
134  * backend. You can optionally plug in your own backend that might use the
135  * filesystem, for example. When first creating the forum factory, Yazd will
136  * look for the Yazd property "ForumFactory.className". If it fails to find
137  * that property, it will use the default class.
138  *
139  * @see AuthorizationFactory
140  */
141 public abstract class ForumFactory {
142 
143     private static Object   initLock = new Object  ();
144     private static String   className = "com.Yasna.forum.database.DbForumFactory";
145     private static ForumFactory factory = null;
146 
147     /**
148      * Returns a concrete ForumFactory instance. Permissions corresponding
149      * to the Authorization will be used. If getting the factory fails, null
150      * will be returned.
151      *
152      * @param authorization the auth token for the user.
153      * @return a concrete ForumFactory instance.
154      */
155     public static ForumFactory getInstance(Authorization authorization) {
156         //If no valid authorization passed in, return null.
157         if (authorization == null) {
158             return null;
159         }
160         if (factory == null) {
161             synchronized(initLock) {
162                 if (factory == null) {
163                     String   classNameProp = PropertyManager.getProperty("ForumFactory.className");
164                     if (classNameProp != null) {
165                         className = classNameProp;
166                     }
167                     try {
168                         //Load the class and create an instance.
169                         Class   c = Class.forName(className);
170                         factory = (ForumFactory)c.newInstance();
171                     }
172                     catch (Exception   e) {
173                         System.err.println("Failed to load ForumFactory class "
174                             + className + ". 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(
186                                     factory,
187                                     authorization,
188                                     factory.getPermissions(authorization)
189                                   );
190         return proxy;
191     }
192 
193     /**
194      * Creates a new forum. This method should always be used instead of
195      * trying to instantiate a forum directly.
196      *
197      * @param name the name of the forum.
198      * @param description the description of the forum.
199      * @param moderated when true - posted messages and threads must first be approved
200      * @param forumGroupID every forum belongs to a Category and ForumGroup
201      * @throws UnauthorizedException if not allowed to create a Forum.
202      * @throws ForumAlreadExistsException if the forum name already exists.
203      */
204     public abstract Forum createForum(String   name, String   description,
205                                       boolean moderated, int forumGroupID, boolean article)
206             throws UnauthorizedException, ForumAlreadyExistsException;
207 
208     /**
209      * Returns the forum with the specified forumID.
210      *
211      * @param forumID the id of the forum to return.
212      * @return the Forum specified by forumID.
213      * @throws UnauthorizedException if not allowed to read the forum.
214      * @throws ForumNotFoundException if the requested forum does not exist.
215      */
216     public abstract Forum getForum(int forumID)
217             throws ForumNotFoundException, UnauthorizedException;
218 
219     /**
220      * Returns the Forum with the specified name.
221      *
222      * @param name the name of the forum to return.
223      * @return the forum with the specified name.
224      * @throws ForumNotFoundException if the requested forum does not exist.
225      * @throws UnauthorizedException if not allowed to read the forum.
226      */
227     public abstract Forum getForum(String   name)
228             throws ForumNotFoundException, UnauthorizedException;
229 
230     /**
231      * Returns the total number of forums. This number might not agree
232      * with the number of forums returned by ForumFactory.forums() since that
233      * method return an Iterator of forums that a user has READ access for.
234      *
235      * @return the total number of forums.
236      */
237     public abstract int getForumCount();
238 
239     /**
240      * Returns an Iterator of Category objects
241      *
242      * @return an Iterator of Category objects
243      */
244     public abstract Iterator categories();
245 
246     /**
247      * Returns the category with the specified categoryID.
248      *
249      * @param categoryID the id of the category to return.
250      * @return the Category specified by categoryID.
251      * @throws UnauthorizedException if not allowed to read the category.
252      * @throws CategoryNotFoundException if the requested category does not exist.
253      */
254     public abstract Category getCategory(int categoryID)
255             throws CategoryNotFoundException, UnauthorizedException;
256 
257     /**
258      * Returns the Category with the specified name.
259      *
260      * @param name the name of the category to return.
261      * @return the category with the specified name.
262      * @throws CategoryNotFoundException if the requested category does not exist.
263      * @throws UnauthorizedException if not allowed to read the forum.
264      */
265     public abstract Category getCategory(String   name)
266             throws CategoryNotFoundException, UnauthorizedException;
267 
268     /**
269      * Creates a new Category.
270      *
271      * @param name the name of the category.
272      * @param description the description of the category.
273      * @throws UnauthorizedException if not allowed to create a Category.
274      * @throws CategoryAlreadExistsException if the category name already exists.
275      */
276     public abstract Category createCategory(String   name, String   description)
277             throws UnauthorizedException, CategoryAlreadyExistsException;
278 
279     /**
280      * Returns an Iterator of Forum objects for all the forums in the system
281      * that the user has READ access for. Read access can be granted in the
282      * following ways:
283      * <ul>
284      *   <li> Anonymous read permission is enabled for the forum; anyone can
285      *        read it.
286      *   <li> The "all users" read permission is set so that any registered
287      *        user can read the forum.
288      *   <li> The user belongs to a group that has been granted read permission.
289      *   <li> The user has been specifically granted read permission.
290      *   <li> The current user is a system admin or admin of this forum. This
291      *        allows automatic read permission.
292      * </ul>
293      *
294      * @return an Iterator of Forum objects for all forums in the system that
295      *    the user has read permission for.
296      */
297     public abstract Iterator forums();
298 
299     /**
300      * This method returns the iterator with all the forums including the forums that
301      * are used for discussions around an article or a webpage.
302      * @return an iterator with the forum objects
303      */
304     public abstract Iterator forumsWithArticlesForums();
305 
306    /**
307     * Returns an Iterator of Forum objects for all the forums in the system
308     * that the user has Moderation, Forum Admin or System Admin access to.
309     */
310 
311     public abstract Iterator forumsModeration();
312 
313 
314     /**
315      * Deletes a forum and all of its content. This method is not always
316      * guaranteed to be safe to call. For example, if multiple clients have
317      * handles on a forum, and that forum is subsequently deleted, the behavior
318      * of the forum objects that the clients have handles on is unspecified and
319      * may result in errors.
320      *
321      * @param forum the forum to delete.
322      * @throws UnauthorizedException if not allowed to delete a forum.
323      */
324     public abstract void deleteForum(Forum forum)
325             throws UnauthorizedException;
326 
327     /**
328      * Deletes a category and all of its content. This method is not always
329      * guaranteed to be safe to call.
330      *
331      * @param category the category to delete.
332      * @throws UnauthorizedException if not allowed to delete a category.
333      */
334     public abstract void deleteCategory(Category category)
335             throws UnauthorizedException;
336 
337     /**
338      * Returns a ProfileManager that can be used to manage Users and Groups.
339      */
340     public abstract ProfileManager getProfileManager();
341 
342     /**
343      * Returns the search indexer which can be used to manage the index used
344      * by Yazd to perform searches.
345      *
346      * @throws UnauthorizedException if not a system administator.
347      * @return a search indexer.
348      */
349     public abstract SearchIndexer getSearchIndexer()
350             throws UnauthorizedException;
351 
352     /**
353      * Returns all the userID's of users with a particular system permission.
354      * System permissions apply to all forums.
355      *
356      * @throws UnauthorizedException if does not have ADMIN permissions.
357      */
358     public abstract int [] usersWithPermission(int permissionType)
359             throws UnauthorizedException;
360 
361     /**
362      * Returns all the groupID's of groups with a particular system permission.
363      * System permissions apply to all forums.
364      *
365      * @throws UnauthorizedException if does not have ADMIN permissions.
366      */
367     public abstract int[] groupsWithPermission(int permissionType)
368             throws UnauthorizedException;
369 
370     /**
371      * Returns the permissions for the factory that correspond to the
372      * passed-in Authorization.
373      *
374      * @param authorization the auth token for the user.
375      * @return the permissions for this object.
376      */
377     public abstract ForumPermissions getPermissions(Authorization authorization);
378 
379     /**
380      * Returns true if the handle on the object has the permission specified.
381      * A list of possible permissions can be found in the ForumPermissions
382      * class. Certain methods of this class are restricted to certain
383      * permissions as specified in the method comments.
384      *
385      * @param type the type of permission to check for.
386      * @see ForumPermissions
387      */
388     public abstract boolean hasPermission(int type);
389     /**
390      * This would create a query for all the forums.
391      * If you just need to query one forum you should use the createQuery method in the Forum class.
392      * @return
393      */
394     public abstract Query createQuery();
395 
396     /**
397      * This method adds the IP address to the black list.
398      * @param cip
399      * @throws UnauthorizedException
400      */
401     public abstract void BlackListIP(ClientIP cip,boolean add) 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,Forum forum) throws ForumThreadNotFoundException, UnauthorizedException;
416 
417     public abstract Iterator getThreadTypeIterator();
418 
419     public abstract ThreadType getThreadType(int typeid);
420 
421     public abstract Iterator getSessionList();
422 
423     public abstract int getYesterdayUserCount();
424     
425 
426 
427 }
428
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags