Package org.sakaiproject.announcement.api

Interface AnnouncementService

All Superinterfaces:

EntityProducer, EntitySummary, MessageService

public interface AnnouncementService
extends 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

Fields

Modifier and Type	Field	Description
static String	ANNOUNCEMENT_CHANNEL_PROPERTY	The property name of the channel to use instead of the site channel
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	EVENT_AVAILABLE_ANNC	Event for delayed announcement
static String	MOD_DATE	modified date property names for announcements
static String	MOTD_TOOL_ID
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

Modifier and Type	Method	Description
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.
Reference	getAnnouncementReference(String context)	Get announcement entity reference for given context
List	getMessages(String channelReference, Filter filter, boolean ascending, boolean merged)	Return a list of messages from the provided channel (merged flag returns merged messages)
String	getRssUrl(Reference ref)	Get URL to access the announcement rss feed
Map<String,List<AnnouncementMessage>>	getViewableAnnouncementsForCurrentUser(Integer maxAgeInDays)
List<AnnouncementMessage>	getViewableAnnouncementsForSite(String channelRef, Integer maxAgeInDays)
boolean	isMessageViewable(AnnouncementMessage message)	Determine if message viewable based on release/retract dates (if set)

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

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

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

getSummarizableReference, summarizableToolIds

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

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

ANNOUNCEMENT_CHANNEL_PROPERTY

static final String ANNOUNCEMENT_CHANNEL_PROPERTY

The property name of the channel to use instead of the site channel

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

MOTD_TOOL_ID

static final String MOTD_TOOL_ID

See Also:

Constant Field Values

EVENT_AVAILABLE_ANNC

static final String EVENT_AVAILABLE_ANNC

Event for delayed announcement

See Also:

Constant Field Values

Method Detail

getAnnouncementChannel

AnnouncementChannel getAnnouncementChannel(String ref)
                                    throws IdUnusedException,
                                           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:

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

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

addAnnouncementChannel

AnnouncementChannelEdit addAnnouncementChannel(String ref)
                                        throws IdUsedException,
                                               IdInvalidException,
                                               PermissionException

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

Parameters:

ref - The channel reference.

Returns:

The newly created channel.

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.

getAnnouncementReference

Reference getAnnouncementReference(String context)

Get announcement entity reference for given context

Parameters:

context - announcement context (site-id)

Returns:

announcement entity reference

getRssUrl

String getRssUrl(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,
                 Filter filter,
                 boolean ascending,
                 boolean merged)
          throws IdUnusedException,
                 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.

ascending - 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:

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

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

NullPointerException

getViewableAnnouncementsForCurrentUser

Map<String,List<AnnouncementMessage>> getViewableAnnouncementsForCurrentUser(Integer maxAgeInDays)

getViewableAnnouncementsForSite

List<AnnouncementMessage> getViewableAnnouncementsForSite(String channelRef,
                                                          Integer maxAgeInDays)