org.sakaiproject.service.legacy.message
Interface MessageChannel

All Superinterfaces:
Entity
All Known Subinterfaces:
AnnouncementChannel, AnnouncementChannelEdit, ChatChannel, ChatChannelEdit, DiscussionChannel, DiscussionChannelEdit, MailArchiveChannel, MailArchiveChannelEdit, MessageChannelEdit
All Known Implementing Classes:
BaseAnnouncementService.BaseAnnouncementChannelEdit, BaseChatService.BaseChatChannelEdit, BaseDiscussionService.BaseDiscussionChannelEdit, BaseMailArchiveService.BaseMailArchiveChannelEdit, BaseMessageService.BaseMessageChannelEdit

public interface MessageChannel
extends Entity

MessageChannel is the base interface for Sakai communications service message channels. Extensions to this interface configure types of communications channels (Chat, Announcements, etc.)

Channels contains collections of messages, each Message (or extension) object. Each chat channel has a unique channel id (read only), and is a Sakai Resource.

The chat channel can be asked:

The chat channel can be subscribed to providing notification when:

Security on the channel include:

Security Roles for the channel include:

Event handling is defined in the specific extension classes.

Author:
Sakai Software Development Team

Field Summary
 
Fields inherited from interface org.sakaiproject.service.legacy.entity.Entity
SEPARATOR
 
Method Summary
 MessageEdit addMessage()
          Add a new message to this channel.
 boolean allowAddChannelMessage()
          Check if the user has permission to add a channel-wide (not grouped) message.
 boolean allowAddMessage()
          check permissions for addMessage().
 boolean allowEditMessage(String messageId)
          check permissions for editMessage()
 boolean allowGetMessages()
          check permissions for getMessages() or getMessage().
 boolean allowRemoveMessage(Message message)
          check permissions for removeMessage().
 void cancelMessage(MessageEdit edit)
          Cancel the changes made to a MessageEdit object, and release the lock.
 void commitMessage(MessageEdit edit)
          Commit the changes made to a MessageEdit object, and release the lock.
 void commitMessage(MessageEdit edit, int priority)
          Commit the changes made to a MessageEdit object, and release the lock.
 MessageEdit editMessage(String messageId)
          Return a specific channel message, as specified by message name, locked for update.
 String getContext()
          Access the context of the resource.
 Collection getGroupsAllowAddMessage()
          Get the collection of Groups defined for the context of this channel that the end user has add message permissions in.
 Collection getGroupsAllowGetMessage()
          Get the collection of Group defined for the context of this channel that the end user has get message permissions in.
 Message getMessage(String messageId)
          Return a specific channel message, as specified by message name.
 List getMessages(Filter filter, boolean ascending)
          Return a list of all or filtered messages in the channel.
 MessageEdit mergeMessage(Element el)
          Merge in a new message as defined in the xml.
 void removeMessage(MessageEdit message)
          Remove a message from the channel - it must be locked from editMessage().
 void removeMessage(String messageId)
          Remove a message from the channel based on message id
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.Entity
getId, getProperties, getReference, getReference, getUrl, getUrl, toXml
 

Method Detail

getContext

public String getContext()
Access the context of the resource.

Returns:
The context.

allowGetMessages

public boolean allowGetMessages()
check permissions for getMessages() or getMessage().

Returns:
true if the user is allowed to get messages from this channel, false if not.

getMessages

public List getMessages(Filter filter,
                        boolean ascending)
                 throws PermissionException
Return a list of all or filtered messages in the channel. The order in which the messages will be found in the iteration is by date, oldest first if ascending is true, newest first if ascending is false.

Parameters:
filter - A filtering object to accept messages, or null if no filtering is desired.
ascending - Order of messages, ascending if true, descending if false
Returns:
a list of channel Message objects or specializations of Message objects (may be empty).
Throws:
PermissionException - if the user does not have read permission to the channel.

getMessage

public Message getMessage(String messageId)
                   throws IdUnusedException,
                          PermissionException
Return a specific channel message, as specified by message name.

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.

allowEditMessage

public boolean allowEditMessage(String messageId)
check permissions for editMessage()

Returns:
true if the user is allowed to update the message, false if not.

editMessage

public MessageEdit editMessage(String messageId)
                        throws IdUnusedException,
                               PermissionException,
                               InUseException
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 edit the message.
InUseException - if the message is locked for edit by someone else.

commitMessage

public void commitMessage(MessageEdit edit)
                   throws PermissionException
Commit the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call. If the message is in a form that the user has no permission to store, a PermissionException is thrown, and the edit is canceled.

Throws:
PermissionException - If the user does not have permission to store this message.

commitMessage

public void commitMessage(MessageEdit edit,
                          int priority)
                   throws PermissionException
Commit the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call. If the message is in a form that the user has no permission to store, a PermissionException is thrown, and the edit is canceled.

Parameters:
priority - The notification priority for this commit.
Throws:
PermissionException - If the user does not have permission to store this message.

cancelMessage

public void cancelMessage(MessageEdit edit)
Cancel the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call.


allowAddMessage

public boolean allowAddMessage()
check permissions for addMessage().

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

allowAddChannelMessage

public boolean allowAddChannelMessage()
Check if the user has permission to add a channel-wide (not grouped) message.

Returns:
true if the user has permission to add a channel-wide (not grouped) message.

addMessage

public MessageEdit addMessage()
                       throws PermissionException
Add a new message to this channel. Must commitEdit() to make official, or cancelEdit() when done!

Returns:
The newly added message, locked for update.
Throws:
PermissionException - If the user does not have write permission to the channel.

allowRemoveMessage

public boolean allowRemoveMessage(Message message)
check permissions for removeMessage().

Parameters:
message - The message from this channel to remove.
Returns:
true if the user is allowed to removeMessage(...), false if not.

removeMessage

public void removeMessage(String messageId)
                   throws PermissionException
Remove a message from the channel based on message id

Parameters:
messageId - The messageId for the message of the channel to remove.
Throws:
PermissionException - if the user does not have permission to remove the message.

removeMessage

public void removeMessage(MessageEdit message)
                   throws PermissionException
Remove a message from the channel - it must be locked from editMessage().

Parameters:
message - The message from this channel to remove.
Throws:
PermissionException - if the user does not have permission to remove the message.

mergeMessage

public MessageEdit mergeMessage(Element el)
                         throws PermissionException,
                                IdUsedException
Merge in a new message as defined in the xml. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
el - The message information in XML in a DOM element.
Returns:
The newly added message, locked for update.
Throws:
PermissionException - If the user does not have write permission to the channel.
IdUsedException - if the user id is already used.

getGroupsAllowAddMessage

public Collection getGroupsAllowAddMessage()
Get the collection of Groups defined for the context of this channel that the end user has add message permissions in.

Returns:
The Collection (Group) of groups defined for the context of this channel that the end user has add message permissions in, empty if none.

getGroupsAllowGetMessage

public Collection getGroupsAllowGetMessage()
Get the collection of Group defined for the context of this channel that the end user has get message permissions in.

Returns:
The Collection (Group) of groups defined for the context of this channel that the end user has get message permissions in, empty if none.