01: /**********************************************************************************
02: * $URL: https://source.sakaiproject.org/svn/discussion/tags/sakai_2-4-1/discussion-api/api/src/java/org/sakaiproject/discussion/api/DiscussionService.java $
03: * $Id: DiscussionService.java 21006 2007-02-05 02:40:41Z csev@umich.edu $
04: ***********************************************************************************
05: *
06: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
07: *
08: * Licensed under the Educational Community License, Version 1.0 (the "License");
09: * you may not use this file except in compliance with the License.
10: * You may obtain a copy of the License at
11: *
12: * http://www.opensource.org/licenses/ecl1.php
13: *
14: * Unless required by applicable law or agreed to in writing, software
15: * distributed under the License is distributed on an "AS IS" BASIS,
16: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17: * See the License for the specific language governing permissions and
18: * limitations under the License.
19: *
20: **********************************************************************************/package org.sakaiproject.discussion.api;
21:
22: import org.sakaiproject.exception.IdInvalidException;
23: import org.sakaiproject.exception.IdUnusedException;
24: import org.sakaiproject.exception.IdUsedException;
25: import org.sakaiproject.exception.PermissionException;
26: import org.sakaiproject.message.api.MessageService;
27:
28: /**
29: * <p>
30: * DiscussionService is the extension to MessageService configured for Discussions.
31: * </p>
32: * <p>
33: * MessageChannels are DiscussionMessageChannels, and Messages are DiscussionMessages with DiscussionMessageHeaders.
34: * </p>
35: * <p>
36: * Security in the discussion service, in addition to that defined in the channels, include:
37: * <ul>
38: * <li>discussion.channel.add</li>
39: * </ul>
40: * </p>
41: * <li>discussion.channel.remove</li>
42: * </ul>
43: * </p>
44: * <p>
45: * Usage Events are generated:
46: * <ul>
47: * <li>discussion.channel.add - discussion channel resource id</li>
48: * <li>discussion.channel.remove - discussion channel resource id</li>
49: * </ul>
50: * </p>
51: */
52: public interface DiscussionService extends MessageService {
53: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
54: static final String APPLICATION_ID = "sakai:discussion";
55:
56: /** This string starts the references to resources in this service. */
57: public static final String REFERENCE_ROOT = "/discussion";
58:
59: /** Security lock for posting topic messages to a channel. */
60: public static final String SECURE_ADD_TOPIC = "new.topic";
61:
62: /** Security lock for posting category to a channel. */
63: public static final String SECURE_ADD_CATEGORY = "new.category";
64:
65: /** Security lock for removing category from a channel. */
66: public static final String SECURE_REMOVE_CATEGORY = "delete.category";
67:
68: /**
69: * A (DiscussionChannel) cover for getChannel() to return a specific discussion channel.
70: *
71: * @param ref
72: * The channel reference.
73: * @return the DiscussionChannel that has the specified name.
74: * @exception IdUnusedException
75: * If this name is not defined for a discussion channel.
76: * @exception PermissionException
77: * If the user does not have any permissions to the channel.
78: */
79: public DiscussionChannel getDiscussionChannel(String ref)
80: throws IdUnusedException, PermissionException;
81:
82: /**
83: * A (DiscussionChannel) cover for addChannel() to add a new discussion channel.
84: *
85: * @param ref
86: * The channel reference.
87: * @return The newly created channel.
88: * @exception IdUsedException
89: * if the id is not unique.
90: * @exception IdInvalidException
91: * if the id is not made up of valid characters.
92: * @exception PermissionException
93: * if the user does not have permission to add a channel.
94: */
95: public DiscussionChannelEdit addDiscussionChannel(String ref)
96: throws IdUsedException, IdInvalidException,
97: PermissionException;
98:
99: }
|