001: /**
002: * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE, version 2.1, dated February 1999.
003: *
004: * This program is free software; you can redistribute it and/or modify
005: * it under the terms of the latest version of the GNU Lesser General
006: * Public License as published by the Free Software Foundation;
007: *
008: * This program is distributed in the hope that it will be useful,
009: * but WITHOUT ANY WARRANTY; without even the implied warranty of
010: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
011: * GNU Lesser General Public License for more details.
012: *
013: * You should have received a copy of the GNU Lesser General Public License
014: * along with this program (LICENSE.txt); if not, write to the Free Software
015: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
016: */package org.jamwiki;
017:
018: import java.util.Collection;
019: import java.util.LinkedHashMap;
020: import java.util.List;
021: import java.util.Locale;
022: import java.util.Vector;
023: import org.jamwiki.model.Role;
024: import org.jamwiki.model.Topic;
025: import org.jamwiki.model.TopicVersion;
026: import org.jamwiki.model.VirtualWiki;
027: import org.jamwiki.model.Watchlist;
028: import org.jamwiki.model.WikiFile;
029: import org.jamwiki.model.WikiFileVersion;
030: import org.jamwiki.model.WikiGroup;
031: import org.jamwiki.model.WikiUser;
032: import org.jamwiki.model.WikiUserInfo;
033: import org.jamwiki.utils.Pagination;
034:
035: /**
036: * This interface provides all methods needed when retrieving or modifying
037: * Wiki data. Any database or other persistency class must implement
038: * this interface, and there should also be a corresponding
039: * <data-handler> entry for the class in the
040: * <code>jamwiki-configuration.xml</code> file.
041: *
042: * @see org.jamwiki.WikiBase#getDataHandler
043: */
044: public interface DataHandler {
045:
046: /**
047: * Determine if a topic can be moved to a new location. If the
048: * destination is not an existing topic, is a topic that has been deleted,
049: * or is a topic that redirects to the source topic then this method
050: * should return <code>true</code>.
051: *
052: * @param fromTopic The Topic that is being moved.
053: * @param destination The new name for the topic.
054: * @return <code>true</code> if the topic can be moved to the destination,
055: * <code>false</code> otherwise.
056: * @throws Exception Thrown if any error occurs during method execution.
057: */
058: boolean canMoveTopic(Topic fromTopic, String destination)
059: throws Exception;
060:
061: /**
062: * Mark a topic deleted by setting its delete date to a non-null value.
063: * Prior to calling this method the topic content should also be set
064: * empty. This method will also delete recent changes for the topic,
065: * and a new TopicVersion should be supplied reflecting the topic deletion
066: * event.
067: *
068: * @param topic The Topic object that is being deleted.
069: * @param topicVersion A TopicVersion object that indicates the delete
070: * date, author, and other parameters for the topic.
071: * @param userVisible Set to <code>true</code> if a recent change should
072: * should be created indicating that the topic was deleted,
073: * <code>false</code> otherwise.
074: * @param transactionObject If this method is being called as part of a
075: * transaction then this parameter should contain the transaction object,
076: * such as a database connection. If this method is not part of a
077: * transaction then this value should be <code>null</code>.
078: * @throws Exception Thrown if any error occurs during method execution.
079: */
080: void deleteTopic(Topic topic, TopicVersion topicVersion,
081: boolean userVisible, Object transactionObject)
082: throws Exception;
083:
084: /**
085: * Return a List of all Category objects for a given virtual wiki.
086: *
087: * @param virtualWiki The virtual wiki for which categories are being
088: * retrieved.
089: * @param pagination A Pagination object indicating the total number of
090: * results and offset for the results to be retrieved.
091: * @return A List of all Category objects for a given virutal wiki.
092: * @throws Exception Thrown if any error occurs during method execution.
093: */
094: List getAllCategories(String virtualWiki, Pagination pagination)
095: throws Exception;
096:
097: /**
098: * Return a List of all Role objects for the wiki.
099: *
100: * @return A List of all Role objects for the wiki.
101: * @throws Exception Thrown if any error occurs during method execution.
102: */
103: List getAllRoles() throws Exception;
104:
105: /**
106: * Return a List of all topic names for all non-deleted topics that
107: * exist for the virtual wiki.
108: *
109: * @param virtualWiki The virtual wiki for which topics are being
110: * retrieved.
111: * @return A List of all topic names for all non-deleted topics that
112: * exist for the virtual wiki.
113: * @throws Exception Thrown if any error occurs during method execution.
114: */
115: List getAllTopicNames(String virtualWiki) throws Exception;
116:
117: /**
118: * Retrieve a List of all TopicVersions for a given topic, sorted
119: * chronologically.
120: *
121: * @param virtualWiki The virtual wiki for the topic being queried.
122: * @param topicName The name of the topic being queried.
123: * @param descending Set to <code>true</code> if the results should be
124: * sorted with the most recent version first, <code>false</code> if the
125: * results should be sorted with the oldest versions first.
126: * @return A List of all TopicVersion objects for the given topic.
127: * If no matching topic exists then an exception is thrown.
128: * @throws Exception Thrown if any error occurs during method execution.
129: */
130: List getAllWikiFileVersions(String virtualWiki, String topicName,
131: boolean descending) throws Exception;
132:
133: /**
134: * Retrieve a List of all RecentChange objects for a given virtual
135: * wiki, sorted chronologically.
136: *
137: * @param virtualWiki The virtual wiki for which recent changes are being
138: * retrieved.
139: * @param pagination A Pagination object indicating the total number of
140: * results and offset for the results to be retrieved.
141: * @param descending Set to <code>true</code> if the results should be
142: * sorted with the most recent changes first, <code>false</code> if the
143: * results should be sorted with the oldest changes first.
144: * @return A List of all RecentChange objects for a given virtual
145: * wiki, sorted chronologically.
146: * @throws Exception Thrown if any error occurs during method execution.
147: */
148: List getRecentChanges(String virtualWiki, Pagination pagination,
149: boolean descending) throws Exception;
150:
151: /**
152: * Retrieve a List of all RecentChange objects for a given topic,
153: * sorted chronologically.
154: *
155: * @param virtualWiki The virtual wiki for the topic being queried.
156: * @param topicName The name of the topic being queried.
157: * @param pagination A Pagination object indicating the total number of
158: * results and offset for the results to be retrieved.
159: * @param descending Set to <code>true</code> if the results should be
160: * sorted with the most recent changes first, <code>false</code> if the
161: * results should be sorted with the oldest changes first.
162: * @return A List of all RecentChange objects for a given topic,
163: * sorted chronologically.
164: * @throws Exception Thrown if any error occurs during method execution.
165: */
166: List getRecentChanges(String virtualWiki, String topicName,
167: Pagination pagination, boolean descending) throws Exception;
168:
169: /**
170: * Retrieve a List of RoleMap objects for all users whose login
171: * contains the given login fragment.
172: *
173: * @param loginFragment A value that must be contained with the user's
174: * login. This method will return partial matches, so "name" will
175: * match "name", "firstname" and "namesake".
176: * @return A Collection of RoleMap objects containing all roles for all
177: * users whose login contains the login fragment. If no matches are
178: * found then this method returns an empty List. This method will
179: * never return <code>null</code>.
180: * @throws Exception Thrown if any error occurs during method execution.
181: */
182: Collection getRoleMapByLogin(String loginFragment) throws Exception;
183:
184: /**
185: * Retrieve a Collection of RoleMap objects for all users and groups who
186: * have been assigned the specified role.
187: *
188: * @param roleName The name of the role being queried against.
189: * @return A Collection of RoleMap objects containing all roles for all
190: * users and groups who have been assigned the specified role. If no
191: * matches are found then this method returns an empty List. This
192: * method will never return <code>null</code>.
193: * @throws Exception Thrown if any error occurs during method execution.
194: */
195: Collection getRoleMapByRole(String roleName) throws Exception;
196:
197: /**
198: * Retrieve all roles assigned to a given group.
199: *
200: * @param groupName The name of the group for whom roles are being retrieved.
201: * @return An array of Role objects for the given group, or an empty
202: * array if no roles are assigned to the group. This method will
203: * never return <code>null</code>.
204: * @throws Exception Thrown if any error occurs during method execution.
205: */
206: Role[] getRoleMapGroup(String groupName) throws Exception;
207:
208: /**
209: * Retrieve a Collection of RoleMap objects for all groups.
210: *
211: * @return A Collection of RoleMap objects containing all roles for all
212: * groups. If no matches are found then this method returns an empty
213: * List. This method will never return <code>null</code>.
214: * @throws Exception Thrown if any error occurs during method execution.
215: */
216: Collection getRoleMapGroups() throws Exception;
217:
218: /**
219: * Retrieve all roles assigned to a given user.
220: *
221: * @param login The login of the user for whom roles are being retrieved.
222: * @return An array of Role objects for the given user, or an empty
223: * array if no roles are assigned to the user. This method will
224: * never return <code>null</code>.
225: * @throws Exception Thrown if any error occurs during method execution.
226: */
227: Role[] getRoleMapUser(String login) throws Exception;
228:
229: /**
230: * Retrieve a List of topic names for all admin-only topics, sorted
231: * alphabetically.
232: *
233: * @param virtualWiki The virtual wiki for which admin-only topics are
234: * being retrieved.
235: * @param pagination A Pagination object indicating the total number of
236: * results and offset for the results to be retrieved.
237: * @return A List of topic names for all admin-only topics, sorted
238: * alphabetically.
239: * @throws Exception Thrown if any error occurs during method execution.
240: */
241: List getTopicsAdmin(String virtualWiki, Pagination pagination)
242: throws Exception;
243:
244: /**
245: * Retrieve a List of RecentChange objects corresponding to all
246: * changes made by a particular user.
247: *
248: * @param virtualWiki The virtual wiki for which changes are being
249: * retrieved.
250: * @param userString Either an IP address (for anonymous users) or the
251: * user login corresponding to the user for whom contributions are
252: * being retrieved.
253: * @param pagination A Pagination object indicating the total number of
254: * results and offset for the results to be retrieved.
255: * @param descending Set to <code>true</code> if the results should be
256: * sorted with the most recent changes first, <code>false</code> if the
257: * results should be sorted with the oldest changes first.
258: * @return A List of RecentChange objects corresponding to all
259: * changes made by a particular user.
260: * @throws Exception Thrown if any error occurs during method execution.
261: */
262: List getUserContributions(String virtualWiki, String userString,
263: Pagination pagination, boolean descending) throws Exception;
264:
265: /**
266: * Return a List of all VirtualWiki objects that exist for the wiki.
267: *
268: * @param transactionObject If this method is being called as part of a
269: * transaction then this parameter should contain the transaction object,
270: * such as a database connection. If this method is not part of a
271: * transaction then this value should be <code>null</code>.
272: * @return A List of all VirtualWiki objects that exist for the
273: * wiki.
274: * @throws Exception Thrown if any error occurs during method execution.
275: */
276: List getVirtualWikiList(Object transactionObject) throws Exception;
277:
278: /**
279: * Retrieve a user's watchlist.
280: *
281: * @param virtualWiki The virtual wiki for which a watchlist is being
282: * retrieved.
283: * @param userId The ID of the user whose watchlist is being retrieved.
284: * @return The Watchlist object for the user.
285: * @throws Exception Thrown if any error occurs during method execution.
286: */
287: Watchlist getWatchlist(String virtualWiki, int userId)
288: throws Exception;
289:
290: /**
291: * Retrieve a List of RecentChange objects corresponding to a user's
292: * watchlist. This method is primarily used to display a user's watchlist
293: * on the Special:Watchlist page.
294: *
295: * @param virtualWiki The virtual wiki for which a watchlist is being
296: * retrieved.
297: * @param userId The ID of the user whose watchlist is being retrieved.
298: * @param pagination A Pagination object indicating the total number of
299: * results and offset for the results to be retrieved.
300: * @return A List of RecentChange objects corresponding to a user's
301: * watchlist.
302: * @throws Exception Thrown if any error occurs during method execution.
303: */
304: List getWatchlist(String virtualWiki, int userId,
305: Pagination pagination) throws Exception;
306:
307: /**
308: * Retrieve a List of Category objects corresponding to all topics
309: * that belong to the category, sorted by either the topic name, or
310: * category sort key (if specified).
311: *
312: * @param virtualWiki The virtual wiki for the category being queried.
313: * @param categoryName The name of the category being queried.
314: * @return A List of all Category objects corresponding to all
315: * topics that belong to the category, sorted by either the topic name,
316: * or category sort key (if specified).
317: * @throws Exception Thrown if any error occurs during method execution.
318: */
319: List lookupCategoryTopics(String virtualWiki, String categoryName)
320: throws Exception;
321:
322: /**
323: * Retrieve a Topic object that matches the given virtual wiki and topic
324: * name.
325: *
326: * @param virtualWiki The virtual wiki for the topic being queried.
327: * @param topicName The name of the topic being queried.
328: * @param deleteOK Set to <code>true</code> if deleted topics can be
329: * retrieved, <code>false</code> otherwise.
330: * @param transactionObject If this method is being called as part of a
331: * transaction then this parameter should contain the transaction object,
332: * such as a database connection. If this method is not part of a
333: * transaction then this value should be <code>null</code>.
334: * @return A Topic object that matches the given virtual wiki and topic
335: * name, or <code>null</code> if no matching topic exists.
336: * @throws Exception Thrown if any error occurs during method execution.
337: */
338: Topic lookupTopic(String virtualWiki, String topicName,
339: boolean deleteOK, Object transactionObject)
340: throws Exception;
341:
342: /**
343: * Return a count of all topics, including redirects, comments pages and
344: * templates, for the given virtual wiki. Deleted topics are not included
345: * in the count.
346: *
347: * @param virtualWiki The virtual wiki for which the total topic count is
348: * being returned.
349: * @return A count of all topics, including redirects, comments pages and
350: * templates, for the given virtual wiki. Deleted topics are not included
351: * in the count.
352: * @throws Exception Thrown if any error occurs during method execution.
353: */
354: int lookupTopicCount(String virtualWiki) throws Exception;
355:
356: /**
357: * Return a List of topic names for all non-deleted topics in the
358: * virtual wiki that match a specific topic type.
359: *
360: * @param virtualWiki The virtual wiki for the topics being queried.
361: * @param topicType The type of topics to return.
362: * @param pagination A Pagination object indicating the total number of
363: * results and offset for the results to be retrieved.
364: * @return A List of topic names for all non-deleted topics in the
365: * virtual wiki that match a specific topic type.
366: * @throws Exception Thrown if any error occurs during method execution.
367: */
368: List lookupTopicByType(String virtualWiki, int topicType,
369: Pagination pagination) throws Exception;
370:
371: /**
372: * Retrieve a TopicVersion object for a given topic version ID.
373: *
374: * @param topicVersionId The ID of the topic version being retrieved.
375: * @param transactionObject If this method is being called as part of a
376: * transaction then this parameter should contain the transaction object,
377: * such as a database connection. If this method is not part of a
378: * transaction then this value should be <code>null</code>.
379: * @return A TopicVersion object matching the given topic version ID,
380: * or <code>null</code> if no matching topic version is found.
381: * @throws Exception Thrown if any error occurs during method execution.
382: */
383: TopicVersion lookupTopicVersion(int topicVersionId,
384: Object transactionObject) throws Exception;
385:
386: /**
387: * Given a virtual wiki name, return the corresponding VirtualWiki object.
388: *
389: * @param virtualWikiName The name of the VirtualWiki object that is
390: * being retrieved.
391: * @return The VirtualWiki object that corresponds to the virtual wiki
392: * name being queried, or <code>null</code> if no matching VirtualWiki
393: * can be found.
394: * @throws Exception Thrown if any error occurs during method execution.
395: */
396: VirtualWiki lookupVirtualWiki(String virtualWikiName)
397: throws Exception;
398:
399: /**
400: * Retrieve a WikiFile object for a given virtual wiki and topic name.
401: *
402: * @param virtualWiki The virtual wiki for the file being queried.
403: * @param topicName The topic name for the file being queried.
404: * @return The WikiFile object for the given virtual wiki and topic name,
405: * or <code>null</code> if no matching WikiFile exists.
406: * @throws Exception Thrown if any error occurs during method execution.
407: */
408: WikiFile lookupWikiFile(String virtualWiki, String topicName)
409: throws Exception;
410:
411: /**
412: * Return a count of all wiki files for the given virtual wiki. Deleted
413: * files are not included in the count.
414: *
415: * @param virtualWiki The virtual wiki for which the total file count is
416: * being returned.
417: * @return A count of all wiki files for the given virtual wiki. Deleted
418: * files are not included in the count.
419: * @throws Exception Thrown if any error occurs during method execution.
420: */
421: int lookupWikiFileCount(String virtualWiki) throws Exception;
422:
423: /**
424: * Retrieve a WikiUser object matching a given user ID.
425: *
426: * @param userId The ID of the WikiUser being retrieved.
427: * @param transactionObject If this method is being called as part of a
428: * transaction then this parameter should contain the transaction object,
429: * such as a database connection. If this method is not part of a
430: * transaction then this value should be <code>null</code>.
431: * @return The WikiUser object matching the given user ID, or
432: * <code>null</code> if no matching WikiUser exists.
433: * @throws Exception Thrown if any error occurs during method execution.
434: */
435: WikiUser lookupWikiUser(int userId, Object transactionObject)
436: throws Exception;
437:
438: /**
439: * Retrieve a WikiUser object matching a given username.
440: *
441: * @param username The username of the WikiUser being retrieved.
442: * @param transactionObject If this method is being called as part of a
443: * transaction then this parameter should contain the transaction object,
444: * such as a database connection. If this method is not part of a
445: * transaction then this value should be <code>null</code>.
446: * @return The WikiUser object matching the given username, or
447: * <code>null</code> if no matching WikiUser exists.
448: * @throws Exception Thrown if any error occurs during method execution.
449: */
450: WikiUser lookupWikiUser(String username, Object transactionObject)
451: throws Exception;
452:
453: /**
454: * Return a count of all wiki users.
455: *
456: * @return A count of all wiki users.
457: * @throws Exception Thrown if any error occurs during method execution.
458: */
459: int lookupWikiUserCount() throws Exception;
460:
461: /**
462: * Return a List of user logins for all wiki users.
463: *
464: * @param pagination A Pagination object indicating the total number of
465: * results and offset for the results to be retrieved.
466: * @return A List of user logins for all wiki users.
467: * @throws Exception Thrown if any error occurs during method execution.
468: */
469: List lookupWikiUsers(Pagination pagination) throws Exception;
470:
471: /**
472: * Move a topic to a new name, creating a redirect topic in the old
473: * topic location. An exception will be thrown if the topic cannot be
474: * moved for any reason.
475: *
476: * @param fromTopic The Topic object that is being moved.
477: * @param fromVersion A TopicVersion object that indicates the move
478: * date, author, and other parameters for the topic.
479: * @param destination The new name for the topic.
480: * @param transactionObject If this method is being called as part of a
481: * transaction then this parameter should contain the transaction object,
482: * such as a database connection. If this method is not part of a
483: * transaction then this value should be <code>null</code>.
484: * @throws Exception Thrown if any error occurs during method execution.
485: */
486: void moveTopic(Topic fromTopic, TopicVersion fromVersion,
487: String destination, Object transactionObject)
488: throws Exception;
489:
490: /**
491: * Delete all existing recent changes and reload the recent changes based
492: * on the most recent topic versions.
493: *
494: * @param transactionObject If this method is being called as part of a
495: * transaction then this parameter should contain the transaction object,
496: * such as a database connection. If this method is not part of a
497: * transaction then this value should be <code>null</code>.
498: * @throws Exception Thrown if any error occurs during method execution.
499: */
500: void reloadRecentChanges(Object transactionObject) throws Exception;
501:
502: /**
503: * Perform any required setup steps for the DataHandler instance.
504: *
505: * @param locale The locale to be used when setting up the data handler
506: * instance. This parameter will affect any messages or defaults used
507: * for the DataHandler.
508: * @param user The admin user to use when creating default topics and
509: * other DataHandler parameters.
510: * @throws Exception Thrown if any error occurs during method execution.
511: */
512: void setup(Locale locale, WikiUser user) throws Exception;
513:
514: /**
515: * Create the special pages used on the wiki, such as the left menu and
516: * default stylesheet.
517: *
518: * @param locale The locale to be used when setting up special pages such
519: * as the left menu and default stylesheet. This parameter will affect
520: * the language used when setting up these pages.
521: * @param user The admin user to use when creating the special pages.
522: * @param virtualWiki The VirtualWiki for which special pages are being
523: * created.
524: * @param transactionObject If this method is being called as part of a
525: * transaction then this parameter should contain the transaction object,
526: * such as a database connection. If this method is not part of a
527: * transaction then this value should be <code>null</code>.
528: * @throws Exception Thrown if any error occurs during method execution.
529: */
530: // FIXME - move this to another location
531: void setupSpecialPages(Locale locale, WikiUser user,
532: VirtualWiki virtualWiki, Object transactionObject)
533: throws Exception;
534:
535: /**
536: * Undelete a previously deleted topic by setting its delete date to a
537: * null value. Prior to calling this method the topic content should be
538: * restored to its previous value. A new TopicVersion should be supplied
539: * reflecting the topic undeletion event.
540: *
541: * @param topic The Topic object that is being undeleted.
542: * @param topicVersion A TopicVersion object that indicates the undelete
543: * date, author, and other parameters for the topic.
544: * @param userVisible Set to <code>true</code> if a recent change should
545: * should be created indicating that the topic was undeleted,
546: * <code>false</code> otherwise.
547: * @param transactionObject If this method is being called as part of a
548: * transaction then this parameter should contain the transaction object,
549: * such as a database connection. If this method is not part of a
550: * transaction then this value should be <code>null</code>.
551: * @throws Exception Thrown if any error occurs during method execution.
552: */
553: void undeleteTopic(Topic topic, TopicVersion topicVersion,
554: boolean userVisible, Object transactionObject)
555: throws Exception;
556:
557: /**
558: * Update a special page used on the wiki, such as the left menu or
559: * default stylesheet.
560: *
561: * @param locale The locale to be used when updating a special page such
562: * as the left menu and default stylesheet. This parameter will affect
563: * the language used when updating up the page.
564: * @param virtualWiki The VirtualWiki for which the special page are being
565: * updated.
566: * @param topicName The name of the special page topic that is being
567: * updated.
568: * @param user The admin user to use when updating the special page.
569: * @param ipAddress The IP address of the user updating special pages.
570: * @param transactionObject If this method is being called as part of a
571: * transaction then this parameter should contain the transaction object,
572: * such as a database connection. If this method is not part of a
573: * transaction then this value should be <code>null</code>.
574: * @throws Exception Thrown if any error occurs during method execution.
575: */
576: // FIXME - move this to another location
577: void updateSpecialPage(Locale locale, String virtualWiki,
578: String topicName, WikiUser user, String ipAddress,
579: Object transactionObject) throws Exception;
580:
581: /**
582: * Add or update a WikiFile object. This method will add a new record if
583: * the WikiFile does not have a file ID, otherwise it will perform an update.
584: * A WikiFileVersion object will also be created to capture the author, date,
585: * and other parameters for the file.
586: *
587: * @param wikiFile The WikiFile to add or update. If the WikiFile does not
588: * have a file ID then a new record is created, otherwise an update is
589: * performed.
590: * @param wikiFileVersion A WikiFileVersion containing the author, date, and
591: * other information about the version being added.
592: * @param transactionObject If this method is being called as part of a
593: * transaction then this parameter should contain the transaction object,
594: * such as a database connection. If this method is not part of a
595: * transaction then this value should be <code>null</code>.
596: * @throws Exception Thrown if any error occurs during method execution.
597: */
598: void writeFile(WikiFile wikiFile, WikiFileVersion wikiFileVersion,
599: Object transactionObject) throws Exception;
600:
601: /**
602: * Add or update a Role object. This method will add a new record if
603: * the role does not yet exist, otherwise the role will be updated.
604: *
605: * @param role The Role to add or update. If the Role does not yet
606: * exist then a new record is created, otherwise an update is
607: * performed.
608: * @param transactionObject If this method is being called as part of a
609: * transaction then this parameter should contain the transaction object,
610: * such as a database connection. If this method is not part of a
611: * transaction then this value should be <code>null</code>.
612: * @param update A boolean value indicating whether this transaction is
613: * updating an existing role or not.
614: * @throws Exception Thrown if any error occurs during method execution.
615: */
616: // FIXME - the update flag should not be necessary
617: void writeRole(Role role, Object transactionObject, boolean update)
618: throws Exception;
619:
620: /**
621: * Add a set of group role mappings. This method will first delete all
622: * existing role mappings for the specified group, and will then create
623: * a mapping for each specified role.
624: *
625: * @param groupId The group id for whom role mappings are being modified.
626: * @param roles A List of String role names for all roles that are
627: * to be assigned to this group.
628: * @param transactionObject If this method is being called as part of a
629: * transaction then this parameter should contain the transaction object,
630: * such as a database connection. If this method is not part of a
631: * transaction then this value should be <code>null</code>.
632: * @throws Exception Thrown if any error occurs during method execution.
633: */
634: void writeRoleMapGroup(int groupId, List roles,
635: Object transactionObject) throws Exception;
636:
637: /**
638: * Add a set of user role mappings. This method will first delete all
639: * existing role mappings for the specified user, and will then create
640: * a mapping for each specified role.
641: *
642: * @param userId The user id for whom role mappings are being modified.
643: * @param roles A List of String role names for all roles that are
644: * to be assigned to this user.
645: * @param transactionObject If this method is being called as part of a
646: * transaction then this parameter should contain the transaction object,
647: * such as a database connection. If this method is not part of a
648: * transaction then this value should be <code>null</code>.
649: * @throws Exception Thrown if any error occurs during method execution.
650: */
651: void writeRoleMapUser(int userId, List roles,
652: Object transactionObject) throws Exception;
653:
654: /**
655: * Add or update a Topic object. This method will add a new record if
656: * the Topic does not have a topic ID, otherwise it will perform an update.
657: * A TopicVersion object will also be created to capture the author, date,
658: * and other parameters for the topic.
659: *
660: * @param topic The Topic to add or update. If the Topic does not have
661: * a topic ID then a new record is created, otherwise an update is
662: * performed.
663: * @param topicVersion A TopicVersion containing the author, date, and
664: * other information about the version being added.
665: * @param categories A mapping of categories and their associated sort keys (if any)
666: * for all categories that are associated with the current topic.
667: * @param links A List of all topic names that are linked to from the
668: * current topic. These will be passed to the search engine to create
669: * searchable metadata.
670: * @param userVisible Set to <code>false</code> if no recent change record
671: * should be created for the topic add/update, <code>true</code>
672: * otherwise.
673: * @param transactionObject If this method is being called as part of a
674: * transaction then this parameter should contain the transaction object,
675: * such as a database connection. If this method is not part of a
676: * transaction then this value should be <code>null</code>.
677: * @throws Exception Thrown if any error occurs during method execution.
678: */
679: void writeTopic(Topic topic, TopicVersion topicVersion,
680: LinkedHashMap categories, Vector links,
681: boolean userVisible, Object transactionObject)
682: throws Exception;
683:
684: /**
685: * Add or update a VirtualWiki object. This method will add a new record
686: * if the VirtualWiki does not have a virtual wiki ID, otherwise it will
687: * perform an update.
688: *
689: * @param virtualWiki The VirtualWiki to add or update. If the
690: * VirtualWiki does not have a virtual wiki ID then a new record is
691: * created, otherwise an update is performed.
692: * @param transactionObject If this method is being called as part of a
693: * transaction then this parameter should contain the transaction object,
694: * such as a database connection. If this method is not part of a
695: * transaction then this value should be <code>null</code>.
696: * @throws Exception Thrown if any error occurs during method execution.
697: */
698: void writeVirtualWiki(VirtualWiki virtualWiki,
699: Object transactionObject) throws Exception;
700:
701: /**
702: * Add or delete an item from a user's watchlist. If the topic is
703: * already in the user's watchlist it will be deleted, otherwise it will
704: * be added.
705: *
706: * @param watchlist The user's current Watchlist.
707: * @param virtualWiki The virtual wiki name for the current virtual wiki.
708: * @param topicName The name of the topic being added or removed from
709: * the watchlist.
710: * @param userId The ID of the user whose watchlist is being updated.
711: * @param transactionObject If this method is being called as part of a
712: * transaction then this parameter should contain the transaction object,
713: * such as a database connection. If this method is not part of a
714: * transaction then this value should be <code>null</code>.
715: * @throws Exception Thrown if any error occurs during method execution.
716: */
717: void writeWatchlistEntry(Watchlist watchlist, String virtualWiki,
718: String topicName, int userId, Object transactionObject)
719: throws Exception;
720:
721: /**
722: * Add or update a WikiGroup object. This method will add a new record if
723: * the group does not have a group ID, otherwise it will perform an update.
724: *
725: * @param group The WikiGroup to add or update. If the group does not have
726: * a group ID then a new record is created, otherwise an update is
727: * performed.
728: * @param transactionObject If this method is being called as part of a
729: * transaction then this parameter should contain the transaction object,
730: * such as a database connection. If this method is not part of a
731: * transaction then this value should be <code>null</code>.
732: * @throws Exception Thrown if any error occurs during method execution.
733: */
734: void writeWikiGroup(WikiGroup group, Object transactionObject)
735: throws Exception;
736:
737: /**
738: * Add or update a WikiUser object. This method will add a new record
739: * if the WikiUser does not have a user ID, otherwise it will perform an
740: * update.
741: *
742: * @param user The WikiUser being added or updated. If the WikiUser does
743: * not have a user ID then a new record is created, otherwise an update
744: * is performed.
745: * @param userInfo The WikiUserInfo object for the WikiUser being added or
746: * updated.
747: * @param transactionObject If this method is being called as part of a
748: * transaction then this parameter should contain the transaction object,
749: * such as a database connection. If this method is not part of a
750: * transaction then this value should be <code>null</code>.
751: * @throws Exception Thrown if any error occurs during method execution.
752: */
753: void writeWikiUser(WikiUser user, WikiUserInfo userInfo,
754: Object transactionObject) throws Exception;
755: }
|