org.sakaiproject.service.legacy.discussion
Interface DiscussionChannel

All Superinterfaces:
Entity, MessageChannel
All Known Subinterfaces:
DiscussionChannelEdit
All Known Implementing Classes:
BaseDiscussionService.BaseDiscussionChannelEdit

public interface DiscussionChannel
extends MessageChannel

DiscussionChannel is the extension to the MessageChanel interface for a CHEF Discussion service discussion channel.

Version:
$Revision: 2076 $
Author:
University of Michigan, CHEF Software Development Team

Field Summary
 
Fields inherited from interface org.sakaiproject.service.legacy.entity.Entity
SEPARATOR
 
Method Summary
 boolean addCategory(String category)
          Add a new category for this channel.
 DiscussionMessageEdit addDiscussionMessage(String replyTo)
          A (DiscussionMessage) cover for addMessage to add a new message to this channel.
 DiscussionMessage addDiscussionMessage(String category, String subject, boolean draft, String replyTo, List attachments, String body)
          A (DiscussionMessage) cover for addMessage to add a new message to this channel.
 boolean allowAddTopicMessage()
          check permissions for addMessage() - if the message is a new Topic.
 boolean allowRemoveCategory()
          check permissions for removing category
 DiscussionMessageEdit editDiscussionMessage(String messageId)
          A (DiscussionMessageEdit) cover for editMessage.
 List getCategories(boolean scanMessages)
          Access the list of catagories defined in the channel.
 DiscussionMessage getDiscussionMessage(String messageId)
          A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id.
 DiscussionMessage getDiscussionMessageNoException(String messageId)
          A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id, and ignore exceptions if any
 Iterator getThread(DiscussionMessage message)
          Return an iterator on the DiscussionMessages that are in the response thread to the specified message.
 DiscussionMessage getThreadLatestReply(DiscussionMessage message)
          Access the most recent reply to the thread descending from this message, if any.
 int getThreadNumberOfReplies(DiscussionMessage message)
          Count the number of replies to this thread (i.e. the size of the getThread() iterator).
 Iterator getThreads(String category)
          Return an iterator on all messages in thread - depth first order.
 List getTopicMsgIds(String category)
          Access the message ids for the topics (i.e. messages that are not a response to any other message) in the category.
 Iterator getTopics(String category)
          Return an Iterator on the DiscussionMessages that are "topics", i.e.
 boolean removeCategory(String category)
          Remove a category for this channel.
 
Methods inherited from interface org.sakaiproject.service.legacy.message.MessageChannel
addMessage, allowAddChannelMessage, allowAddMessage, allowEditMessage, allowGetMessages, allowRemoveMessage, cancelMessage, commitMessage, commitMessage, editMessage, getContext, getGroupsAllowAddMessage, getGroupsAllowGetMessage, getMessage, getMessages, mergeMessage, removeMessage, removeMessage
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.Entity
getId, getProperties, getReference, getReference, getUrl, getUrl, toXml
 

Method Detail

getDiscussionMessage

public DiscussionMessage getDiscussionMessage(String messageId)
                                       throws IdUnusedException,
                                              PermissionException
A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id.

Parameters:
messageId - The id of the message to get.
Returns:
the DiscussionMessage that has the specified id.
Throws:
IdUnusedException - If this name is not a defined message in this discussion channel.
PermissionException - If the user does not have any permissions to read the message.

getDiscussionMessageNoException

public DiscussionMessage getDiscussionMessageNoException(String messageId)
A (DiscussionMessage) cover for getMessage to return a specific discussion channel message, as specified by message id, and ignore exceptions if any

Parameters:
messageId - The id of the message to get.
Returns:
the DiscussionMessage that has the specified id.

editDiscussionMessage

public DiscussionMessageEdit editDiscussionMessage(String messageId)
                                            throws IdUnusedException,
                                                   PermissionException,
                                                   InUseException
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!

Parameters:
messageId - The id of the message to get.
Returns:
the Message that has the specified id.
Throws:
IdUnusedException - If this name is not a defined message in this channel.
PermissionException - If the user does not have any permissions to read the message.
InUseException - if the current user does not have permission to mess with this user.

allowAddTopicMessage

public boolean allowAddTopicMessage()
check permissions for addMessage() - if the message is a new Topic.

Returns:
true if the user is allowed to addMessage(...) for a new Topic, false if not.

allowRemoveCategory

public boolean allowRemoveCategory()
check permissions for removing category

Returns:
true if the user is allowed to remove category, false if not.

addCategory

public boolean addCategory(String category)
                    throws InUseException,
                           PermissionException
Add a new category for this channel.

Parameters:
category - The new category string to add.
Returns:
true if the category was new, false if it is already there.
Throws:
PermissionException - If the user does not have write permission to the channel.
InUseException

removeCategory

public boolean removeCategory(String category)
                       throws InUseException,
                              PermissionException
Remove a category for this channel.

Parameters:
category - The category string to be removed.
Returns:
true if the category can be removed, false if not.
Throws:
PermissionException - If the user does not have write permission to the channel.
InUseException

addDiscussionMessage

public DiscussionMessageEdit addDiscussionMessage(String replyTo)
                                           throws PermissionException
A (DiscussionMessage) cover for addMessage to add a new message to this channel. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
replyTo - The message id to which this message is a reply.
Returns:
The newly added message, locked for update.
Throws:
PermissionException - If the user does not have write permission to the channel.

addDiscussionMessage

public DiscussionMessage addDiscussionMessage(String category,
                                              String subject,
                                              boolean draft,
                                              String replyTo,
                                              List attachments,
                                              String body)
                                       throws PermissionException
A (DiscussionMessage) cover for addMessage to add a new message to this channel.

Parameters:
category - The message header category.
subject - The message header subject.
draft - The message header draft setting.
replyTo - The message header message id to which this is a reply.
attachments - The message header attachments, a vector of Reference objects.
body - The message body.
Returns:
The newly added message.
Throws:
PermissionException - If the user does not have write permission to the channel.

getCategories

public List getCategories(boolean scanMessages)
Access the list of catagories defined in the channel.

Returns:
A List (String) of all the categories defined in the channel.

getTopicMsgIds

public List getTopicMsgIds(String category)
Access the message ids for the topics (i.e. messages that are not a response to any other message) in the category.

Parameters:
category - The category value.
Returns:
A List (Sting) of message id values for each message that is a topic in the category.

getTopics

public Iterator getTopics(String category)
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.

Parameters:
category - Filter the responses to messages in just this category (optional, may be null).
Returns:
an Iterator on the DiscussionMessages that are "topics", i.e. are not a response to any other message.

getThread

public Iterator getThread(DiscussionMessage message)
Return an iterator on the DiscussionMessages that are in the response thread to the specified message. They will be returned in depth first order.

Parameters:
message - The message to which those returned are some depth of response.
Returns:
an iterator on the DiscussionMessages that are in the response thread to the specified topic messages, in depth first order (may be empty).

getThreadLatestReply

public DiscussionMessage getThreadLatestReply(DiscussionMessage message)
Access the most recent reply to the thread descending from this message, if any.

Parameters:
message - The message that forms the top of a thread.
Returns:
the most recent DiscussionMessage reply to this thread, or null if there are no replies.

getThreadNumberOfReplies

public int getThreadNumberOfReplies(DiscussionMessage message)
Count the number of replies to this thread (i.e. the size of the getThread() iterator).

Parameters:
message - The message that forms the top of a thread.
Returns:
the number of replies to this thread.

getThreads

public Iterator getThreads(String category)
Return an iterator on all messages in thread - depth first order.

Parameters:
category - Filter the responses to messages in just this category (optional, may be null).
Returns:
an iterator on all messages in thread - depth first order (may be empty).