KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > nemesis > forum > ForumFactory


1 /*
2  * NEMESIS-FORUM.
3  * Copyright (C) 2002 David Laurent(lithium2@free.fr). All rights reserved.
4  *
5  * Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
6  *
7  * Copyright (C) 2001 Yasna.com. All rights reserved.
8  *
9  * Copyright (C) 2000 CoolServlets.com. All rights reserved.
10  *
11  * NEMESIS-FORUM. is free software; you can redistribute it and/or
12  * modify it under the terms of the Apache Software License, Version 1.1,
13  * or (at your option) any later version.
14  *
15  * NEMESIS-FORUM core framework, NEMESIS-FORUM backoffice, NEMESIS-FORUM frontoffice
16  * application are parts of NEMESIS-FORUM and are distributed under
17  * same terms of licence.
18  *
19  *
20  * NEMESIS-FORUM includes software developed by the Apache Software Foundation (http://www.apache.org/)
21  * and software developed by CoolServlets.com (http://www.coolservlets.com).
22  * and software developed by Yasna.com (http://www.yasna.com).
23  *
24  */

25 package org.nemesis.forum;
26
27 import java.util.Iterator JavaDoc;
28 import java.util.PropertyResourceBundle JavaDoc;
29
30 import org.apache.commons.logging.Log;
31 import org.apache.commons.logging.LogFactory;
32 import org.nemesis.forum.proxy.ForumFactoryProxy;
33 import org.nemesis.forum.exception.ForumAlreadyExistsException;
34 import org.nemesis.forum.exception.ForumNotFoundException;
35 import org.nemesis.forum.exception.UnauthorizedException;
36
37 /**
38  * A ForumFactory provides access to and management of Forums. It is the point
39  * of entry for the entire system.
40  * <p>
41  * A concrete instance of ForumFactory can be obtained by calling the getInstance()
42  * method with an Authorization token. The Authorization token determines with
43  * what permissions the rest of the objects in the system will be accessed with.
44  * <p>
45  * Usually the first steps of any program interacting with the system are:
46  * <ul>
47  * <li> Obtain an authorization token by calling
48  * AuthorizationFactory.getInstance().getAuthorization(username, password);
49  * <li> Use that authorization to get a ForumFactory instance.
50  * <li> Use the forum factory to access forums and other content.
51  * </ul>
52  * It is also possible to access content with anonymous permissions. See
53  * the AuthorizationFactory class for more information.
54  * <p>
55  * ForumFactory is an abstract class so that the actual implementation is
56  * pluggable. For example, the default implementation uses a database
57  * backend. You can optionally plug in your own backend that might use the
58  * filesystem, for example. When first creating the forum factory, will
59  * look for the property "ForumFactory.className". If it fails to find
60  * that property, it will use the default class.
61  *
62  * @see AuthorizationFactory
63  */

64 public abstract class ForumFactory {
65
66     static protected Log log = LogFactory.getLog(ForumFactory.class);
67
68     private static Object JavaDoc initLock = new Object JavaDoc();
69
70     //singleton
71
private static ForumFactory factory = null;
72
73     private static String JavaDoc Impl =
74         (String JavaDoc) ((PropertyResourceBundle JavaDoc) PropertyResourceBundle.getBundle("org.nemesis.forum.config")).getObject("ForumFactory.class");
75
76     /**
77      * Returns a concrete ForumFactory instance. Permissions corresponding
78      * to the Authorization will be used. If getting the factory fails, null
79      * will be returned.
80      *
81      * @param authorization the auth token for the user.
82      * @return a concrete ForumFactory instance.
83      */

84     public static ForumFactory getInstance(Authorization authorization) {
85         //If no valid authorization passed in, return null.
86
if (authorization == null) {
87             return null;
88         }
89         if (factory == null) {
90             synchronized (initLock) {
91                 if (factory == null) {
92
93                     try {
94                         //Load the class and create an instance.
95
Class JavaDoc c = Class.forName(Impl);
96                         factory = (ForumFactory) c.newInstance();
97                     } catch (Exception JavaDoc e) {
98                         log.fatal("Failed to load ForumFactory class " + Impl + ". forum cannot function normally.", e);
99
100                         return null;
101                     }
102                 }
103             }
104         }
105
106         //Wrap the factory with a proxy to provide security. We also pass
107
//in the username and password to the proxy for its special
108
//implementation of the getForum() method. See below for more details.
109
ForumFactoryProxy proxy = new ForumFactoryProxy(factory, authorization, factory.getPermissions(authorization));
110         return proxy;
111     }
112
113     /**
114      * Creates a new forum. This method should always be used instead of
115      * trying to instantiate a forum directly.
116      *
117      * @param name the name of the forum.
118      * @param description the description of the forum.
119      * @throws UnauthorizedException if not allowed to create a Forum.
120      * @throws ForumAlreadExistsException if the forum name already exists.
121      */

122     public abstract Forum createForum(String JavaDoc name, String JavaDoc description) throws UnauthorizedException, ForumAlreadyExistsException;
123
124     /**
125      * Returns the forum with the specified forumID.
126      *
127      * @param forumID the id of the forum to return.
128      * @return the Forum specified by forumID.
129      * @throws UnauthorizedException if not allowed to read the forum.
130      * @throws ForumNotFoundException if the requested forum does not exist.
131      */

132     public abstract Forum getForum(int forumID) throws ForumNotFoundException, UnauthorizedException;
133
134     /**
135      * Returns the Forum with the specified name.
136      *
137      * @param name the name of the forum to return.
138      * @return the forum with the specified name.
139      * @throws ForumNotFoundException if the requested forum does not exist.
140      * @throws UnauthorizedException if not allowed to read the forum.
141      */

142     public abstract Forum getForum(String JavaDoc name) throws ForumNotFoundException, UnauthorizedException;
143
144     /**
145      * Returns the total number of forums. This number might not agree
146      * with the number of forums returned by ForumFactory.forums() since that
147      * method return an Iterator of forums that a user has READ access for.
148      *
149      * @return the total number of forums.
150      */

151     public abstract int getForumCount();
152
153     /**
154      * Returns an Iterator of Forum objects for all the forums in the system
155      * that the user has READ access for. Read access can be granted in the
156      * following ways:
157      * <ul>
158      * <li> Anonymous read permission is enabled for the forum; anyone can
159      * read it.
160      * <li> The "all users" read permission is set so that any registered
161      * user can read the forum.
162      * <li> The user belongs to a group that has been granted read permission.
163      * <li> The user has been specifically granted read permission.
164      * <li> The current user is a system admin or admin of this forum. This
165      * allows automatic read permission.
166      * </ul>
167      *
168      * @return an Iterator of Forum objects for all forums in the system that
169      * the user has read permission for.
170      */

171     public abstract Iterator JavaDoc forums();
172
173     /**
174      * Returns an Iterator of Forum objects for all the forums in the system
175      * that the user has Moderation, Forum Admin or System Admin access to.
176      */

177
178     public abstract Iterator JavaDoc forumsModeration();
179
180     /**
181      * Deletes a forum and all of its content. This method is not always
182      * guaranteed to be safe to call. For example, if multiple clients have
183      * handles on a forum, and that forum is subsequently deleted, the behavior
184      * of the forum objects that the clients have handles on is unspecified and
185      * may result in errors.
186      *
187      * @param forum the forum to delete.
188      * @throws UnauthorizedException if not allowed to delete a forum.
189      */

190     public abstract void deleteForum(Forum forum) throws UnauthorizedException;
191
192     /**
193      * Returns a ProfileManager that can be used to manage Users and Groups.
194      */

195     public abstract ProfileManager getProfileManager();
196
197     /**
198      * Returns the search indexer which can be used to manage the index used
199      * to perform searches.
200      *
201      * @throws UnauthorizedException if not a system administator.
202      * @return a search indexer.
203      */

204     //public abstract SearchIndexer getSearchIndexer()
205
// throws UnauthorizedException;
206

207     /**
208      * Returns all the userID's of users with a particular system permission.
209      * System permissions apply to all forums.
210      *
211      * @throws UnauthorizedException if does not have ADMIN permissions.
212      */

213     public abstract int[] usersWithPermission(int permissionType) throws UnauthorizedException;
214
215     /**
216      * Returns all the groupID's of groups 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[] groupsWithPermission(int permissionType) throws UnauthorizedException;
222
223     /**
224      * Returns the permissions for the factory that correspond to the
225      * passed-in Authorization.
226      *
227      * @param authorization the auth token for the user.
228      * @return the permissions for this object.
229      */

230     public abstract ForumPermissions getPermissions(Authorization authorization);
231
232     /**
233      * Returns true if the handle on the object has the permission specified.
234      * A list of possible permissions can be found in the ForumPermissions
235      * class. Certain methods of this class are restricted to certain
236      * permissions as specified in the method comments.
237      *
238      * @param type the type of permission to check for.
239      * @see ForumPermissions
240      */

241     public abstract boolean hasPermission(int type);
242 }
243
Popular Tags