org.sakaiproject.announcement.api
Interface AnnouncementService

All Superinterfaces:

org.sakaiproject.entity.api.EntityProducer, org.sakaiproject.entity.api.EntitySummary, org.sakaiproject.message.api.MessageService

public interface AnnouncementService
extends org.sakaiproject.message.api.MessageService

AnnouncementService is the extension to MessageService configured for Announcements.

MessageChannels are AnnouncementMessageChannels, and Messages are AnnouncementMessages with AnnouncementMessageHeaders.

Security in the announcement service, in addition to that defined in the channels, include:

• announcement.channel.add

announcement.channel.remove

Usage Events are generated:

• announcement.channel.add - announcement channel resource id
• announcement.channel.remove - announcement channel resource id

Field Summary

static String	APPLICATION_ID The type string for this application: should not change over time as it may be stored in various parts of persistent entities.
static String	ASSIGNMENT_REFERENCE assignment reference property for announcements
static String	EVENT_ANNC_UPDATE_ACCESS Event for updating announcement access
static String	EVENT_ANNC_UPDATE_AVAILABILITY Event for updating announcement availability
static String	EVENT_ANNC_UPDATE_TITLE Event for updating announcement title
static String	MOD_DATE modified date property names for announcements
static String	REF_TYPE_ANNOUNCEMENT The Reference type for an announcement
static String	REF_TYPE_ANNOUNCEMENT_RSS The Reference type for an announcement rss feed
static String	REFERENCE_ROOT This string starts the references to resources in this service.
static String	RELEASE_DATE release date property names for announcements
static String	RETRACT_DATE retract date property names for announcements
static String	SECURE_ANNC_ADD Security lock / event for adding channel / message.
static String	SECURE_ANNC_ALL_GROUPS Security function giving the user permission to all groups, if granted to at the channel or site level.
static String	SECURE_ANNC_READ Security lock / event for reading channel / message.
static String	SECURE_ANNC_READ_DRAFT Security lock / event for accessing someone elses draft.
static String	SECURE_ANNC_REMOVE_ANY Security lock / event for removing anyone's message or channel.
static String	SECURE_ANNC_REMOVE_OWN Security lock / event for removing one's own message.
static String	SECURE_ANNC_ROOT Security lock / event root for generic message events to make it a mail event.
static String	SECURE_ANNC_UPDATE_ANY Security lock / event for updating any message.
static String	SECURE_ANNC_UPDATE_OWN Security lock / event for updating one's own message or the channel.

Fields inherited from interface org.sakaiproject.message.api.MessageService

REF_TYPE_CHANNEL, REF_TYPE_MESSAGE, SECURE_ADD, SECURE_ALL_GROUPS, SECURE_CREATE, SECURE_READ, SECURE_READ_DRAFT, SECURE_REMOVE_ANY, SECURE_REMOVE_OWN, SECURE_UPDATE_ANY, SECURE_UPDATE_OWN

Method Summary

AnnouncementChannelEdit	addAnnouncementChannel(String ref) A (AnnouncementChannel) cover for addChannel() to add a new announcement channel.
void	clearMessagesCache(String channelRef) clears the message cache for this channel
AnnouncementChannel	getAnnouncementChannel(String ref) A (AnnouncementChannel) cover for getChannel() to return a specific announcement channel.
org.sakaiproject.entity.api.Reference	getAnnouncementReference(String context) Get announcement entity reference for given context
List	getMessages(String channelReference, org.sakaiproject.javax.Filter filter, boolean order, boolean merged) Return a list of messages from the provided channel (merged flag returns merged messages)
String	getRssUrl(org.sakaiproject.entity.api.Reference ref) Get URL to access the announcement rss feed
boolean	isMessageViewable(AnnouncementMessage message) Determine if message viewable based on release/retract dates (if set)

Methods inherited from interface org.sakaiproject.message.api.MessageService

addChannel, allowAddChannel, allowEditChannel, allowGetChannel, allowRemoveChannel, cancelChannel, cancelMessage, channelReference, commitChannel, editChannel, getChannel, getChannelIds, getChannelPublic, getChannels, getMessage, getMessages, getSummary, messageReference, messageReference, removeChannel

Methods inherited from interface org.sakaiproject.entity.api.EntityProducer

archive, getEntity, getEntityAuthzGroups, getEntityDescription, getEntityResourceProperties, getEntityUrl, getHttpAccess, getLabel, merge, parseEntityReference, willArchiveMerge

Methods inherited from interface org.sakaiproject.entity.api.EntitySummary

getSummarizableReference, summarizableToolIds

Field Detail

APPLICATION_ID

static final String APPLICATION_ID

The type string for this application: should not change over time as it may be stored in various parts of persistent entities.

See Also:

Constant Field Values

REF_TYPE_ANNOUNCEMENT

static final String REF_TYPE_ANNOUNCEMENT

The Reference type for an announcement

See Also:

Constant Field Values

REF_TYPE_ANNOUNCEMENT_RSS

static final String REF_TYPE_ANNOUNCEMENT_RSS

The Reference type for an announcement rss feed

See Also:

Constant Field Values

REFERENCE_ROOT

static final String REFERENCE_ROOT

This string starts the references to resources in this service.

See Also:

Constant Field Values

SECURE_ANNC_ROOT

static final String SECURE_ANNC_ROOT

Security lock / event root for generic message events to make it a mail event.

See Also:

Constant Field Values

SECURE_ANNC_READ

static final String SECURE_ANNC_READ

Security lock / event for reading channel / message.

See Also:

Constant Field Values

SECURE_ANNC_ADD

static final String SECURE_ANNC_ADD

Security lock / event for adding channel / message.

See Also:

Constant Field Values

SECURE_ANNC_REMOVE_OWN

static final String SECURE_ANNC_REMOVE_OWN

Security lock / event for removing one's own message.

See Also:

Constant Field Values

SECURE_ANNC_REMOVE_ANY

static final String SECURE_ANNC_REMOVE_ANY

Security lock / event for removing anyone's message or channel.

See Also:

Constant Field Values

SECURE_ANNC_UPDATE_OWN

static final String SECURE_ANNC_UPDATE_OWN

Security lock / event for updating one's own message or the channel.

See Also:

Constant Field Values

SECURE_ANNC_UPDATE_ANY

static final String SECURE_ANNC_UPDATE_ANY

Security lock / event for updating any message.

See Also:

Constant Field Values

SECURE_ANNC_READ_DRAFT

static final String SECURE_ANNC_READ_DRAFT

Security lock / event for accessing someone elses draft.

See Also:

Constant Field Values

SECURE_ANNC_ALL_GROUPS

static final String SECURE_ANNC_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

RELEASE_DATE

static final String RELEASE_DATE

release date property names for announcements

See Also:

Constant Field Values

RETRACT_DATE

static final String RETRACT_DATE

retract date property names for announcements

See Also:

Constant Field Values

MOD_DATE

static final String MOD_DATE

modified date property names for announcements

See Also:

Constant Field Values

ASSIGNMENT_REFERENCE

static final String ASSIGNMENT_REFERENCE

assignment reference property for announcements

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_TITLE

static final String EVENT_ANNC_UPDATE_TITLE

Event for updating announcement title

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_ACCESS

static final String EVENT_ANNC_UPDATE_ACCESS

Event for updating announcement access

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_AVAILABILITY

static final String EVENT_ANNC_UPDATE_AVAILABILITY

Event for updating announcement availability

See Also:

Constant Field Values

Method Detail

getAnnouncementChannel

AnnouncementChannel getAnnouncementChannel(String ref)
                                           throws org.sakaiproject.exception.IdUnusedException,
                                                  org.sakaiproject.exception.PermissionException

A (AnnouncementChannel) cover for getChannel() to return a specific announcement channel.

Parameters:

ref - The channel reference.

Returns:

the AnnouncementChannel that has the specified name.

Throws:

org.sakaiproject.exception.IdUnusedException - If this name is not defined for a announcement channel.

org.sakaiproject.exception.PermissionException - If the user does not have any permissions to the channel.

addAnnouncementChannel

AnnouncementChannelEdit addAnnouncementChannel(String ref)
                                               throws org.sakaiproject.exception.IdUsedException,
                                                      org.sakaiproject.exception.IdInvalidException,
                                                      org.sakaiproject.exception.PermissionException

A (AnnouncementChannel) cover for addChannel() to add a new announcement channel.

Parameters:

ref - The channel reference.

Returns:

The newly created channel.

Throws:

org.sakaiproject.exception.IdUsedException - if the id is not unique.

org.sakaiproject.exception.IdInvalidException - if the id is not made up of valid characters.

org.sakaiproject.exception.PermissionException - if the user does not have permission to add a channel.

getAnnouncementReference

org.sakaiproject.entity.api.Reference getAnnouncementReference(String context)

Get announcement entity reference for given context

Parameters:

context - announcement context (site-id)

Returns:

announcement entity reference

getRssUrl

String getRssUrl(org.sakaiproject.entity.api.Reference ref)

Get URL to access the announcement rss feed

Parameters:

ref - The announcement entity reference

Returns:

URL for announcement rss feed

isMessageViewable

boolean isMessageViewable(AnnouncementMessage message)

Determine if message viewable based on release/retract dates (if set)

Parameters:

AnnouncementMessage -

Returns:

boolean

clearMessagesCache

void clearMessagesCache(String channelRef)

clears the message cache for this channel

Parameters:

channelRef -

getMessages

List getMessages(String channelReference,
                 org.sakaiproject.javax.Filter filter,
                 boolean order,
                 boolean merged)
                 throws org.sakaiproject.exception.IdUnusedException,
                        org.sakaiproject.exception.PermissionException,
                        NullPointerException

Return a list of messages from the provided channel (merged flag returns merged messages)

Parameters:

channelReference - Channel's reference String

filter - A filtering object to accept messages, or null if no filtering is desired.

order - Order of messages, ascending if true, descending if false

merged - flag to include merged channel messages, true returns ALL messages including merged sites/channels

Returns:

a list of Message objects or specializations of Message objects (may be empty).

Throws:

org.sakaiproject.exception.IdUnusedException - If this name is not defined for a announcement channel.

org.sakaiproject.exception.PermissionException - if the user does not have read permission to the channel.

NullPointerException