org.sakaiproject.service.legacy.message
Interface MessageService

All Superinterfaces:
EntityProducer
All Known Subinterfaces:
AnnouncementService, ChatService, DiscussionService, MailArchiveService
All Known Implementing Classes:
BaseAnnouncementService, BaseChatService, BaseDiscussionService, BaseMailArchiveService, BaseMessageService

public interface MessageService
extends EntityProducer

GenericMessageService is the base interface for the different specific Sakai communications service such as Chat, Announcements, etc.

The service manages a set of message channels, each containing a set of messages.

Channels and Messages can be worked with through the MessageChannel and Message APIs and their extensions.

Version:
$Revision: 2827 $
Author:
University of Michigan, Sakai Software Development Team

Nested Class Summary
 
Nested classes inherited from class org.sakaiproject.service.legacy.entity.EntityProducer
EntityProducer.ChangeType
 
Field Summary
static String REF_TYPE_CHANNEL
          The Reference type for a channel.
static String REF_TYPE_CHANNEL_GROUPS
          The Reference type for a channel where site groups are to be considered in security computation.
static String REF_TYPE_MESSAGE
          The Reference type for a messgae.
static String SECURE_ADD
          Security function / event for adding channel / message.
static String SECURE_ALL_GROUPS
          Security function giving the user permission to all groups, if granted to at the channel or site level.
static String SECURE_READ
          Security function / event for reading channel / message.
static String SECURE_READ_DRAFT
          Security function / event for accessing someone elses draft.
static String SECURE_REMOVE_ANY
          Security function / event for removing anyone's message or channel.
static String SECURE_REMOVE_OWN
          Security function / event for removing one's own message.
static String SECURE_UPDATE_ANY
          Security function / event for updating any message.
static String SECURE_UPDATE_OWN
          Security function / event for updating one's own message or the channel.
 
Method Summary
 MessageChannelEdit addChannel(String ref)
          Add a new channel.
 boolean allowAddChannel(String ref)
          check permissions for addChannel().
 boolean allowEditChannel(String ref)
          check permissions for editChannel()
 boolean allowGetChannel(String ref)
          check permissions for getChannel().
 boolean allowRemoveChannel(String ref)
          Check permissions for removeChannel().
 void cancelChannel(MessageChannelEdit edit)
          Cancel the changes made to a MessageChannelEdit object, and release the lock.
 void cancelMessage(MessageEdit edit)
          Cancel the changes made to a MessageEdit object, and release the lock.
 String channelReference(String context, String id)
          Access the internal reference which can be used to access the channel from within the system.
 void commitChannel(MessageChannelEdit edit)
          Commit the changes made to a MessageChannelEdit object, and release the lock.
 MessageChannelEdit editChannel(String ref)
          Return a specific channel, as specified by channel id, locked for update.
 MessageChannel getChannel(String ref)
          Return a specific channel.
 List getChannelIds(String context)
          Access a list of channel ids that are defined related to the context.
 List getChannels()
          Return a list of all the defined channels.
 Message getMessage(Reference ref)
          Get a message, given a reference.
 List getMessages(String channelRef, Time afterDate, int limitedToLatest, boolean ascending, boolean includeDrafts, boolean pubViewOnly)
          Access a list of messages in the channel, that are after the date, limited to just the n latest messages, ordered as specified, including drafts if specified.
 String messageReference(String channelRef, String id)
          Access the internal reference which can be used to access the message from within the system.
 String messageReference(String context, String channelId, String id)
          Access the internal reference which can be used to access the message from within the system.
 void removeChannel(MessageChannelEdit channel)
          Remove a channel - it must be locked from editChannel().
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.EntityProducer
archive, getEntity, getEntityAuthzGroups, getEntityDescription, getEntityResourceProperties, getEntityUrl, getHttpAccess, getLabel, importEntities, merge, parseEntityReference, syncWithSiteChange, willArchiveMerge, willImport
 

Field Detail

SECURE_READ

public static final String SECURE_READ
Security function / event for reading channel / message.

See Also:
Constant Field Values

SECURE_ADD

public static final String SECURE_ADD
Security function / event for adding channel / message.

See Also:
Constant Field Values

SECURE_REMOVE_OWN

public static final String SECURE_REMOVE_OWN
Security function / event for removing one's own message.

See Also:
Constant Field Values

SECURE_REMOVE_ANY

public static final String SECURE_REMOVE_ANY
Security function / event for removing anyone's message or channel.

See Also:
Constant Field Values

SECURE_UPDATE_OWN

public static final String SECURE_UPDATE_OWN
Security function / event for updating one's own message or the channel.

See Also:
Constant Field Values

SECURE_UPDATE_ANY

public static final String SECURE_UPDATE_ANY
Security function / event for updating any message.

See Also:
Constant Field Values

SECURE_READ_DRAFT

public static final String SECURE_READ_DRAFT
Security function / event for accessing someone elses draft.

See Also:
Constant Field Values

SECURE_ALL_GROUPS

public static final String SECURE_ALL_GROUPS
Security function giving the user permission to all groups, if granted to at the channel or site level.

See Also:
Constant Field Values

REF_TYPE_CHANNEL

public static final String REF_TYPE_CHANNEL
The Reference type for a channel.

See Also:
Constant Field Values

REF_TYPE_CHANNEL_GROUPS

public static final String REF_TYPE_CHANNEL_GROUPS
The Reference type for a channel where site groups are to be considered in security computation.

See Also:
Constant Field Values

REF_TYPE_MESSAGE

public static final String REF_TYPE_MESSAGE
The Reference type for a messgae.

See Also:
Constant Field Values
Method Detail

getChannels

public List getChannels()
Return a list of all the defined channels.

Returns:
a list of MessageChannel (or extension) objects (may be empty).

allowGetChannel

public boolean allowGetChannel(String ref)
check permissions for getChannel().

Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to getChannel(channelId), false if not.

getChannel

public MessageChannel getChannel(String ref)
                          throws IdUnusedException,
                                 PermissionException
Return a specific channel.

Parameters:
ref - The channel reference.
Returns:
the MessageChannel that has the specified name.
Throws:
IdUnusedException - If this name is not defined for any channel.
PermissionException - If the user does not have any permissions to the channel.

allowAddChannel

public boolean allowAddChannel(String ref)
check permissions for addChannel().

Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to addChannel(channelId), false if not.

addChannel

public MessageChannelEdit addChannel(String ref)
                              throws IdUsedException,
                                     IdInvalidException,
                                     PermissionException
Add a new channel. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
ref - The channel reference.
Returns:
The newly created channel, locked for update.
Throws:
IdUsedException - if the id is not unique.
IdInvalidException - if the id is not made up of valid characters.
PermissionException - if the user does not have permission to add a channel.

allowEditChannel

public boolean allowEditChannel(String ref)
check permissions for editChannel()

Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to update the channel, false if not.

editChannel

public MessageChannelEdit editChannel(String ref)
                               throws IdUnusedException,
                                      PermissionException,
                                      InUseException
Return a specific channel, as specified by channel id, locked for update. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:
ref - The channel reference.
Returns:
the Channel that has the specified id.
Throws:
IdUnusedException - If this name is not a defined channel.
PermissionException - If the user does not have any permissions to edit the channel.
InUseException - if the channel is locked for edit by someone else.

commitChannel

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


cancelChannel

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


allowRemoveChannel

public boolean allowRemoveChannel(String ref)
Check permissions for removeChannel().

Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to removeChannel(), false if not.

removeChannel

public void removeChannel(MessageChannelEdit channel)
                   throws PermissionException
Remove a channel - it must be locked from editChannel().

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

channelReference

public String channelReference(String context,
                               String id)
Access the internal reference which can be used to access the channel from within the system.

Parameters:
context - The context.
id - The channel id.
Returns:
The the internal reference which can be used to access the channel from within the system.

messageReference

public String messageReference(String context,
                               String channelId,
                               String id)
Access the internal reference which can be used to access the message from within the system.

Parameters:
context - The context.
channelId - The channel id.
id - The message id.
Returns:
The the internal reference which can be used to access the message from within the system.

messageReference

public String messageReference(String channelRef,
                               String id)
Access the internal reference which can be used to access the message from within the system.

Parameters:
channelRef - The channel reference.
id - The message id.
Returns:
The the internal reference which can be used to access the message from within the system.

getMessage

public Message getMessage(Reference ref)
                   throws IdUnusedException,
                          PermissionException
Get a message, given a reference. This call avoids the need to have channel security, as long as the user has permissions to the message.

Parameters:
ref - The message reference
Returns:
The message.
Throws:
IdUnusedException - If this reference does not identify a message.
PermissionException - If the user does not have any permissions to the 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.


getMessages

public List getMessages(String channelRef,
                        Time afterDate,
                        int limitedToLatest,
                        boolean ascending,
                        boolean includeDrafts,
                        boolean pubViewOnly)
                 throws PermissionException
Access a list of messages in the channel, that are after the date, limited to just the n latest messages, ordered as specified, including drafts if specified. Channel read permission is required, unless pubViewOnly is selected - draft read on the channel is required to see drafts.

Parameters:
afterDate - if null, no date limit, else limited to only messages after this date.
limitedToLatest - if 0, no count limit, else limited to only the latest this number of messages.
ascending - if true, sort oldest first, else sort latest first.
includeDrafts - if true, include drafts (if the user has draft permission), else leave them out.
pubViewOnly - if true, include only messages marked pubview, else include any.
Returns:
A list of Message objects that meet the criteria; may be empty
Throws:
PermissionException - If the current user does not have channel read permission.

getChannelIds

public List getChannelIds(String context)
Access a list of channel ids that are defined related to the context.

Parameters:
context - The context in which to search
Returns:
A List (String) of channel id for channels withing the context.