001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/discussion/tags/sakai_2-4-1/discussion-api/api/src/java/org/sakaiproject/discussion/api/DiscussionChannel.java $
003: * $Id: DiscussionChannel.java 8232 2006-04-25 01:11:55Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.discussion.api;
021:
022: import java.util.Iterator;
023: import java.util.List;
024:
025: import org.sakaiproject.exception.IdUnusedException;
026: import org.sakaiproject.exception.InUseException;
027: import org.sakaiproject.exception.PermissionException;
028: import org.sakaiproject.message.api.MessageChannel;
029:
030: /**
031: * <p>
032: * DiscussionChannel is the extension to the MessageChanel interface for a CHEF Discussion service discussion channel.
033: * </p>
034: */
035: public interface DiscussionChannel extends MessageChannel {
036: /**
037: * A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id.
038: *
039: * @param messageId
040: * The id of the message to get.
041: * @return the DiscussionMessage that has the specified id.
042: * @exception IdUnusedException
043: * If this name is not a defined message in this discussion channel.
044: * @exception PermissionException
045: * If the user does not have any permissions to read the message.
046: */
047: public DiscussionMessage getDiscussionMessage(String messageId)
048: throws IdUnusedException, PermissionException;
049:
050: /**
051: * A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id, and ignore exceptions if any
052: *
053: * @param messageId
054: * The id of the message to get.
055: * @return the DiscussionMessage that has the specified id.
056: */
057: public DiscussionMessage getDiscussionMessageNoException(
058: String messageId);
059:
060: /**
061: * A (DiscussionMessageEdit) cover for editMessage. Return a specific channel message, as specified by message name, locked for update. Must commitEdit() to make official, or cancelEdit() when done!
062: *
063: * @param messageId
064: * The id of the message to get.
065: * @return the Message that has the specified id.
066: * @exception IdUnusedException
067: * If this name is not a defined message in this channel.
068: * @exception PermissionException
069: * If the user does not have any permissions to read the message.
070: * @exception InUseException
071: * if the current user does not have permission to mess with this user.
072: */
073: public DiscussionMessageEdit editDiscussionMessage(String messageId)
074: throws IdUnusedException, PermissionException,
075: InUseException;
076:
077: /**
078: * check permissions for addMessage() - if the message is a new Topic.
079: *
080: * @return true if the user is allowed to addMessage(...) for a new Topic, false if not.
081: */
082: public boolean allowAddTopicMessage();
083:
084: /**
085: * check permissions for removing category
086: *
087: * @return true if the user is allowed to remove category, false if not.
088: */
089: public boolean allowRemoveCategory();
090:
091: /**
092: * Add a new category for this channel.
093: *
094: * @param category
095: * The new category string to add.
096: * @return true if the category was new, false if it is already there.
097: * @exception PermissionException
098: * If the user does not have write permission to the channel.
099: */
100: public boolean addCategory(String category) throws InUseException,
101: PermissionException;
102:
103: /**
104: * Remove a category for this channel.
105: *
106: * @param category
107: * The category string to be removed.
108: * @return true if the category can be removed, false if not.
109: * @exception PermissionException
110: * If the user does not have write permission to the channel.
111: */
112: public boolean removeCategory(String category)
113: throws InUseException, PermissionException;
114:
115: /**
116: * A (DiscussionMessage) cover for addMessage to add a new message to this channel. Must commitEdit() to make official, or cancelEdit() when done!
117: *
118: * @param replyTo
119: * The message id to which this message is a reply.
120: * @return The newly added message, locked for update.
121: * @exception PermissionException
122: * If the user does not have write permission to the channel.
123: */
124: public DiscussionMessageEdit addDiscussionMessage(String replyTo)
125: throws PermissionException;
126:
127: /**
128: * A (DiscussionMessage) cover for addMessage to add a new message to this channel.
129: *
130: * @param category
131: * The message header category.
132: * @param subject
133: * The message header subject.
134: * @param draft
135: * The message header draft setting.
136: * @param replyTo
137: * The message header message id to which this is a reply.
138: * @param attachments
139: * The message header attachments, a vector of Reference objects.
140: * @param body
141: * The message body.
142: * @return The newly added message.
143: * @exception PermissionException
144: * If the user does not have write permission to the channel.
145: */
146: public DiscussionMessage addDiscussionMessage(String category,
147: String subject, boolean draft, String replyTo,
148: List attachments, String body) throws PermissionException;
149:
150: /**
151: * Access the list of catagories defined in the channel.
152: *
153: * @param scanMessage
154: * if true, scan the channel's messages for catagories set in messages that may not be in the channel's catagory list, if false, use just the channel's catagory list.
155: * @return A List (String) of all the categories defined in the channel.
156: */
157: public List getCategories(boolean scanMessages);
158:
159: /**
160: * Access the message ids for the topics (i.e. messages that are not a response to any other message) in the category.
161: *
162: * @param category
163: * The category value.
164: * @return A List (Sting) of message id values for each message that is a topic in the category.
165: */
166: public List getTopicMsgIds(String category);
167:
168: /**
169: * Return an Iterator on the DiscussionMessages that are "topics", i.e. are not a response to any other message. Note: use DiscussionMessage.getReplies() to get the direct replies to any specific message.
170: *
171: * @param category
172: * Filter the responses to messages in just this category (optional, may be null).
173: * @return an Iterator on the DiscussionMessages that are "topics", i.e. are not a response to any other message.
174: */
175: public Iterator getTopics(String category);
176:
177: /**
178: * Return an iterator on the DiscussionMessages that are in the response thread to the specified message. They will be returned in depth first order.
179: *
180: * @param message
181: * The message to which those returned are some depth of response.
182: * @return an iterator on the DiscussionMessages that are in the response thread to the specified topic messages, in depth first order (may be empty).
183: */
184: public Iterator getThread(DiscussionMessage message);
185:
186: /**
187: * Access the most recent reply to the thread descending from this message, if any.
188: *
189: * @param message
190: * The message that forms the top of a thread.
191: * @return the most recent DiscussionMessage reply to this thread, or null if there are no replies.
192: */
193: public DiscussionMessage getThreadLatestReply(
194: DiscussionMessage message);
195:
196: /**
197: * Count the number of replies to this thread (i.e. the size of the getThread() iterator).
198: *
199: * @param message
200: * The message that forms the top of a thread.
201: * @return the number of replies to this thread.
202: */
203: public int getThreadNumberOfReplies(DiscussionMessage message);
204:
205: /**
206: * Return an iterator on all messages in thread - depth first order.
207: *
208: * @param category
209: * Filter the responses to messages in just this category (optional, may be null).
210: * @return an iterator on all messages in thread - depth first order (may be empty).
211: */
212: public Iterator getThreads(String category);
213: }
|