AnnouncementService API

API reference for managing announcements and announcement channels in Sakai LMS

Overview

The AnnouncementService extends the MessageService and provides functionality for managing announcements and announcement channels in Sakai LMS. Announcements are used to broadcast information to site members.

Package: org.sakaiproject.announcement.api

Source: /announcement/announcement-api/api/src/java/org/sakaiproject/announcement/api/AnnouncementService.java

Constants

Application Identifiers

public static final String APPLICATION_ID = "sakai:announcement";
public static final String REF_TYPE_ANNOUNCEMENT = "announcement";
public static final String REFERENCE_ROOT = "/announcement";

Security Permissions

public static final String SECURE_ANNC_READ = "annc.read";
public static final String SECURE_ANNC_ADD = "annc.new";
public static final String SECURE_ANNC_REMOVE_OWN = "annc.remove.own";
public static final String SECURE_ANNC_REMOVE_ANY = "annc.remove.any";
public static final String SECURE_ANNC_UPDATE_OWN = "annc.update.own";
public static final String SECURE_ANNC_UPDATE_ANY = "annc.update.any";
public static final String SECURE_ANNC_ALL_GROUPS = "annc.all.groups";

Core Methods

Channel Management

getAnnouncementChannel

Retrieve a specific announcement channel.

public AnnouncementChannel getAnnouncementChannel(String ref) 
    throws IdUnusedException, PermissionException;

ref · String · required

The channel reference

Returns: The AnnouncementChannel with the specified reference

Throws:

• IdUnusedException - If the channel reference is not defined
• PermissionException - If the user lacks permissions to access the channel

Example:

String channelRef = "/announcement/channel/" + siteId + "/main";
AnnouncementChannel channel = announcementService.getAnnouncementChannel(channelRef);

addAnnouncementChannel

Create a new announcement channel.

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

ref · String · required

The channel reference for the new channel

Returns: The newly created AnnouncementChannelEdit object

Throws:

• IdUsedException - If the channel reference is already in use
• IdInvalidException - If the reference contains invalid characters
• PermissionException - If the user lacks permission to add channels

Example:

String channelRef = "/announcement/channel/" + siteId + "/main";
AnnouncementChannelEdit edit = announcementService.addAnnouncementChannel(channelRef);
edit.getPropertiesEdit().addProperty(ResourceProperties.PROP_DISPLAY_NAME, "Announcements");
announcementService.commitChannel(edit);

Message Retrieval

getMessages

Retrieve messages from a channel with optional filtering and merging.

public List<AnnouncementMessage> getMessages(
    String channelReference, 
    Filter filter, 
    boolean ascending, 
    boolean merged
) throws IdUnusedException, PermissionException;

channelReference · String · required

The channel’s reference string

filter · Filter

A filtering object to accept messages, or null for no filtering

ascending · boolean · required

Order of messages - true for ascending, false for descending

merged · boolean · required

Flag to include merged channel messages from other sites/channels

Returns: List of AnnouncementMessage objects (may be empty)

Example:

String channelRef = "/announcement/channel/" + siteId + "/main";
Filter filter = announcementService.getMaxAgeInDaysAndAmountFilter(30, 10);
List<AnnouncementMessage> messages = announcementService.getMessages(
    channelRef, filter, false, false
);

getChannelMessages

Retrieve messages with advanced filtering options including merged channels and synoptic views.

public List<AnnouncementMessage> getChannelMessages(
    String channelReference,
    Filter filter,
    boolean ascending,
    String mergedChannelDelimitedList,
    boolean allUserSites,
    boolean isSynopticTool,
    String siteId,
    Integer maxAgeInDays
) throws PermissionException;

channelReference · String

The hosting channel reference

filter · Filter

A filtering object, or null if no filtering is desired

ascending · boolean · required

Order of messages - true for ascending, false for descending

mergedChannelDelimitedList · String

Delimited list of channel references to merge

allUserSites · boolean · required

Set to true to retrieve messages from all user’s sites

isSynopticTool · boolean · required

Whether this is being called from a synoptic tool

siteId · String

The site we want messages for

maxAgeInDays · Integer

If filter is null, this will filter returned messages by age

Returns: List of AnnouncementMessage objects

Example:

// Get announcements from all user sites for synoptic view
List<AnnouncementMessage> messages = announcementService.getChannelMessages(
    null, null, false, null, true, true, null, 30
);

getVisibleMessagesOfTheDay

Retrieve visible Message of the Day (MOTD) announcements.

public List<AnnouncementMessage> getVisibleMessagesOfTheDay(
    Time afterDate, 
    int numberOfAnnouncements, 
    boolean ascending
);

afterDate · Time

Optional lower-bound date filter - messages before this are excluded

numberOfAnnouncements · int · required

Maximum number of messages to return (values < 0 are treated as 0)

ascending · boolean · required

Sort order - true for oldest-first, false for newest-first

Returns: List of visible MOTD announcements

Example:

Time yesterday = timeService.newTime(System.currentTimeMillis() - 86400000);
List<AnnouncementMessage> motd = announcementService.getVisibleMessagesOfTheDay(
    yesterday, 5, false
);

Utility Methods

getAnnouncementReference

Get the announcement entity reference for a given context.

public Reference getAnnouncementReference(String context);

context · String · required

The announcement context (site-id)

Returns: Announcement entity reference

getRssUrl

Get the URL to access the announcement RSS feed.

public String getRssUrl(Reference ref);

ref · Reference · required

The announcement entity reference

Returns: URL for announcement RSS feed

clearMessagesCache

Clear the message cache for a specific channel.

public void clearMessagesCache(String channelRef);

channelRef · String · required

The channel reference

Example:

String channelRef = "/announcement/channel/" + siteId + "/main";
announcementService.clearMessagesCache(channelRef);

getMaxAgeInDaysAndAmountFilter

Create a filter based on maximum age and message count.

public Filter getMaxAgeInDaysAndAmountFilter(Integer maxAgeInDays, Integer amount);

maxAgeInDays · Integer

Maximum age of messages in days

amount · Integer

Maximum number of messages to return

Returns: A Filter object configured with the specified parameters

Events

Event Types

public static final String EVENT_ANNC_UPDATE_TITLE = "annc.revise.title";
public static final String EVENT_ANNC_UPDATE_ACCESS = "annc.revise.access";
public static final String EVENT_ANNC_UPDATE_AVAILABILITY = "annc.revise.availability";
public static final String EVENT_AVAILABLE_ANNC = "annc.available.announcement";

Tool IDs

public static final String MOTD_TOOL_ID = "sakai.motd";
public static final String SAKAI_ANNOUNCEMENT_TOOL_ID = "sakai.announcements";
public static final String SYNOPTIC_ANNOUNCEMENT_TOOL = "sakai.synoptic.announcement";

Usage Examples

Complete Example: Creating and Posting an Announcement

import org.sakaiproject.announcement.api.*;
import org.sakaiproject.entity.api.ResourceProperties;
import org.sakaiproject.time.api.Time;
import org.sakaiproject.time.api.TimeService;

public class AnnouncementExample {
    
    private AnnouncementService announcementService;
    private TimeService timeService;
    
    public void createAnnouncement(String siteId, String title, String body) {
        try {
            // Get or create the channel
            String channelRef = "/announcement/channel/" + siteId + "/main";
            AnnouncementChannel channel;
            
            try {
                channel = announcementService.getAnnouncementChannel(channelRef);
            } catch (IdUnusedException e) {
                // Channel doesn't exist, create it
                AnnouncementChannelEdit channelEdit = 
                    announcementService.addAnnouncementChannel(channelRef);
                channelEdit.getPropertiesEdit().addProperty(
                    ResourceProperties.PROP_DISPLAY_NAME, "Announcements"
                );
                announcementService.commitChannel(channelEdit);
                channel = announcementService.getAnnouncementChannel(channelRef);
            }
            
            // Create the announcement message
            AnnouncementMessageEdit message = channel.addAnnouncementMessage();
            message.setBody(body);
            
            AnnouncementMessageHeaderEdit header = message.getAnnouncementHeaderEdit();
            header.setSubject(title);
            header.setDraft(false);
            
            // Set release and retract dates
            Time now = timeService.newTime();
            Time oneWeekLater = timeService.newTime(now.getTime() + 7 * 24 * 60 * 60 * 1000);
            header.setDate(now);
            header.setRelease(now);
            header.setRetract(oneWeekLater);
            
            // Commit the message
            channel.commitMessage(message);
            
            System.out.println("Announcement created successfully!");
            
        } catch (Exception e) {
            System.err.println("Error creating announcement: " + e.getMessage());
        }
    }
    
    public void listRecentAnnouncements(String siteId) {
        try {
            String channelRef = "/announcement/channel/" + siteId + "/main";
            Filter filter = announcementService.getMaxAgeInDaysAndAmountFilter(30, 10);
            
            List<AnnouncementMessage> messages = announcementService.getMessages(
                channelRef, filter, false, false
            );
            
            for (AnnouncementMessage msg : messages) {
                System.out.println("Title: " + msg.getAnnouncementHeader().getSubject());
                System.out.println("Date: " + msg.getAnnouncementHeader().getDate());
                System.out.println("Body: " + msg.getBody());
                System.out.println("---");
            }
            
        } catch (Exception e) {
            System.err.println("Error listing announcements: " + e.getMessage());
        }
    }
}

See Also

• MessageService API - Parent service interface
• Entity API - Entity and reference handling
• Security API - Permission checking