CalendarService API

API reference for managing calendars and calendar events in Sakai LMS

Overview

The CalendarService manages calendars and calendar events in Sakai LMS. Each site can have one or more calendars containing events that can be viewed, edited, and shared.

Package: org.sakaiproject.calendar.api

Source: /calendar/calendar-api/api/src/java/org/sakaiproject/calendar/api/CalendarService.java

Constants

Application Identifiers

public static final String APPLICATION_ID = "sakai:calendar";
public static final String REFERENCE_ROOT = "/calendar";
public static final String REF_TYPE_CALENDAR = "calendar";
public static final String REF_TYPE_EVENT = "event";

Event Types

public static final String EVENT_CREATE_CALENDAR = "calendar.create";
public static final String EVENT_ADD_CALENDAR = "calendar.new";
public static final String EVENT_REMOVE_CALENDAR = "calendar.delete";
public static final String EVENT_MODIFY_CALENDAR = "calendar.revise";
public static final String EVENT_MODIFY_CALENDAR_EVENT_TITLE = "calendar.revise.event.title";
public static final String EVENT_MODIFY_CALENDAR_EVENT_TIME = "calendar.revise.event.time";
public static final String EVENT_MODIFY_CALENDAR_EVENT_TYPE = "calendar.revise.event.type";
public static final String EVENT_MODIFY_CALENDAR_EVENT_ACCESS = "calendar.revise.event.access";

Security Permissions

public static final String AUTH_ADD_CALENDAR = "calendar.new";
public static final String AUTH_REMOVE_CALENDAR_ANY = "calendar.delete.any";
public static final String AUTH_REMOVE_CALENDAR_OWN = "calendar.delete.own";
public static final String AUTH_MODIFY_CALENDAR_ANY = "calendar.revise.any";
public static final String AUTH_MODIFY_CALENDAR_OWN = "calendar.revise.own";
public static final String AUTH_IMPORT_CALENDAR = "calendar.import";
public static final String AUTH_SUBSCRIBE_CALENDAR = "calendar.subscribe";
public static final String AUTH_READ_CALENDAR = "calendar.read";
public static final String AUTH_ALL_GROUPS_CALENDAR = "calendar.all.groups";

View Types

public static final int DAY_VIEW = 0;
public static final int LIST_SUBVIEW = 1;
public static final int WEEK_VIEW = 2;
public static final int MONTH_VIEW = 3;
public static final int LIST_VIEW = 5;

Recurrence Modification Types

public static final int MOD_NA = 0;      // No intention
public static final int MOD_THIS = 1;    // Just this one
public static final int MOD_ALL = 2;     // All occurrences
public static final int MOD_REST = 3;    // This and subsequent
public static final int MOD_PRIOR = 4;   // This and prior

Calendar Management

addCalendar

Create a new calendar.

public CalendarEdit addCalendar(String ref) 
    throws IdUsedException, IdInvalidException, PermissionException;

ref · String · required

The new calendar reference

Returns: The newly created CalendarEdit object

Throws:

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

Note: You must call commitCalendar() to finalize or cancelCalendar() to discard

Example:

String calendarRef = calendarService.calendarReference(siteId, "main");
try {
    CalendarEdit calendar = calendarService.addCalendar(calendarRef);
    calendar.getPropertiesEdit().addProperty(
        ResourceProperties.PROP_DISPLAY_NAME, 
        "Site Calendar"
    );
    calendarService.commitCalendar(calendar);
} catch (IdUsedException e) {
    // Calendar already exists
}

getCalendar

Retrieve a specific calendar.

public Calendar getCalendar(String ref) 
    throws IdUnusedException, PermissionException;

ref · String · required

The calendar reference

Returns: The Calendar with the specified reference

Throws:

• IdUnusedException - If the calendar doesn’t exist
• PermissionException - If the user lacks permissions

Example:

String calendarRef = calendarService.calendarReference(siteId, "main");
try {
    Calendar calendar = calendarService.getCalendar(calendarRef);
    System.out.println("Calendar: " + calendar.getDisplayName());
} catch (IdUnusedException e) {
    System.err.println("Calendar not found");
}

editCalendar

Get a locked calendar for editing.

public CalendarEdit editCalendar(String ref) 
    throws IdUnusedException, PermissionException, InUseException;

ref · String · required

The calendar reference

Returns: A CalendarEdit object for editing

Throws:

• IdUnusedException - If the calendar doesn’t exist
• PermissionException - If the user lacks permission
• InUseException - If the calendar is locked by another user

Note: Must call commitCalendar(), cancelCalendar(), or removeCalendar() when done

commitCalendar

Commit changes to a calendar and release the lock.

public void commitCalendar(CalendarEdit edit);

edit · CalendarEdit · required

The calendar edit object to commit

Note: The CalendarEdit is disabled after this call

cancelCalendar

Cancel changes to a calendar and release the lock.

public void cancelCalendar(CalendarEdit edit);

edit · CalendarEdit · required

The calendar edit object to cancel

removeCalendar

Remove a calendar that is locked for edit.

public void removeCalendar(CalendarEdit edit) throws PermissionException;

edit · CalendarEdit · required

The calendar to remove

Throws: PermissionException if the user lacks permission

Event Management

getEvents

Merge events from multiple calendars within a time range.

public CalendarEventVector getEvents(
    List references, 
    TimeRange range
);

references · List · required

List of calendar references

range · TimeRange

Time period to select events (null = one year before and after)

Returns: CalendarEventVector with the union of all events

Example:

List<String> calendarRefs = Arrays.asList(
    calendarService.calendarReference(siteId, "main")
);

TimeRange thisWeek = timeService.newTimeRange(
    timeService.newTime(),
    7 * 24 * 60 * 60 * 1000L
);

CalendarEventVector events = calendarService.getEvents(calendarRefs, thisWeek);
for (Object obj : events) {
    CalendarEvent event = (CalendarEvent) obj;
    System.out.println(event.getDisplayName() + " at " + event.getRange());
}

getFilteredEvents

Retrieve filtered events for the current user.

public List<CalendarEvent> getFilteredEvents(
    Map<EventFilterKey, Object> options
);

options · Map<EventFilterKey, Object> · required

Filter options (supports “limit” and “siteId”)

Returns: List of CalendarEvent objects matching the filter

Example:

Map<EventFilterKey, Object> options = new HashMap<>();
options.put(EventFilterKey.SITE_ID, siteId);
options.put(EventFilterKey.LIMIT, 10);

List<CalendarEvent> events = calendarService.getFilteredEvents(options);

Recurrence

newRecurrence

Create a new recurrence rule.

public RecurrenceRule newRecurrence(String frequency);
public RecurrenceRule newRecurrence(String frequency, int interval);
public RecurrenceRule newRecurrence(String frequency, int interval, int count);
public RecurrenceRule newRecurrence(String frequency, int interval, Time until);

frequency · String · required

The frequency description (“DAILY”, “WEEKLY”, “MONTHLY”, “YEARLY”)

interval · int

The recurrence interval

count · int

Number of occurrences

until · Time

Time after which recurrences stop

Returns: A new RecurrenceRule object

Example:

// Every week for 10 occurrences
RecurrenceRule weeklyRule = calendarService.newRecurrence("WEEKLY", 1, 10);

// Daily until a specific date
Time endDate = timeService.newTime(System.currentTimeMillis() + 30L * 24 * 60 * 60 * 1000);
RecurrenceRule dailyRule = calendarService.newRecurrence("DAILY", 1, endDate);

Reference Methods

calendarReference

Get the internal reference for a calendar.

public String calendarReference(String context, String id);

context · String · required

The context (site ID)

id · String · required

The calendar ID

Returns: The internal reference string

eventReference

Get the internal reference for an event.

public String eventReference(String context, String calendarId, String id);

context · String · required

The context (site ID)

calendarId · String · required

The calendar ID

id · String · required

The event ID

Returns: The internal reference string for the event

calendarICalReference

Get the iCal reference for a calendar.

public String calendarICalReference(Reference ref);

ref · Reference · required

The calendar reference

Returns: The iCal reference string

calendarPdfReference

Get the PDF reference for a calendar.

public String calendarPdfReference(
    String context,
    String id,
    int scheduleType,
    String timeRangeString,
    String userName,
    boolean reverseOrder
);

context · String · required

The context (site ID)

id · String · required

The calendar ID

scheduleType · int · required

The view type (DAY_VIEW, WEEK_VIEW, etc.)

timeRangeString · String · required

Time range for the PDF

userName · String · required

The user name for the PDF

reverseOrder · boolean · required

Whether to reverse event order

Returns: The PDF reference string

Permission Checking

allowGetCalendar

Check if the user can get a calendar.

public boolean allowGetCalendar(String ref);

ref · String · required

The calendar reference

Returns: true if the user is allowed to get the calendar

allowEditCalendar

Check if the user can edit a calendar.

public boolean allowEditCalendar(String ref);

ref · String · required

The calendar reference

Returns: true if the user can edit the calendar

allowImportCalendar

Check if the user can import calendar events.

public boolean allowImportCalendar(String ref);

ref · String · required

The calendar reference

Returns: true if the user can import events

allowSubscribeCalendar

Check if the user can subscribe to external calendars.

public boolean allowSubscribeCalendar(String ref);

ref · String · required

The calendar reference

Returns: true if the user can subscribe to external calendars

Export and Subscription

getExportEnabled

Check if public iCal export is enabled for a calendar.

public boolean getExportEnabled(String ref);

ref · String · required

The calendar reference

Returns: true if export is enabled

setExportEnabled

Enable or disable public iCal export for a calendar.

public void setExportEnabled(String ref, boolean enable);

ref · String · required

The calendar reference

enable · boolean · required

True to enable, false to disable

Utility Methods

getCalendarReferences

Get all calendar references for a site.

public List<String> getCalendarReferences(String siteId);

siteId · String · required

The site ID

Returns: List of calendar reference strings

isCalendarToolInitialized

Check if the calendar tool has been initialized for a site.

public boolean isCalendarToolInitialized(String siteId);

siteId · String · required

The site ID

Returns: true if the calendar has been created

getUpcomingDaysLimit

Get the limit on upcoming days for filtered events.

public int getUpcomingDaysLimit();

Returns: The number of days (default 60, configurable via calendar.upcoming_days_limit)

Complete Example

import org.sakaiproject.calendar.api.*;
import org.sakaiproject.time.api.*;
import org.sakaiproject.entity.api.ResourceProperties;

public class CalendarExample {
    
    private CalendarService calendarService;
    private TimeService timeService;
    
    public void createEventExample(String siteId) {
        try {
            // Get or create calendar
            String calendarRef = calendarService.calendarReference(siteId, "main");
            Calendar calendar;
            
            try {
                calendar = calendarService.getCalendar(calendarRef);
            } catch (IdUnusedException e) {
                CalendarEdit calEdit = calendarService.addCalendar(calendarRef);
                calEdit.getPropertiesEdit().addProperty(
                    ResourceProperties.PROP_DISPLAY_NAME, 
                    "Site Calendar"
                );
                calendarService.commitCalendar(calEdit);
                calendar = calendarService.getCalendar(calendarRef);
            }
            
            // Edit calendar to add event
            CalendarEdit calEdit = calendarService.editCalendar(calendarRef);
            
            // Create event
            CalendarEventEdit event = calEdit.addEvent();
            event.setDisplayName("Team Meeting");
            event.setDescription("Discuss project progress");
            event.setType("Meeting");
            
            // Set time range (1 hour from now)
            Time start = timeService.newTime();
            Time end = timeService.newTime(start.getTime() + 60 * 60 * 1000);
            TimeRange range = timeService.newTimeRange(start, end);
            event.setRange(range);
            
            // Optional: Make it recurring (weekly for 10 weeks)
            RecurrenceRule rule = calendarService.newRecurrence("WEEKLY", 1, 10);
            event.setRecurrenceRule(rule);
            
            // Commit changes
            calendarService.commitCalendar(calEdit);
            
            System.out.println("Event created: " + event.getDisplayName());
            
        } catch (Exception e) {
            System.err.println("Error creating event: " + e.getMessage());
        }
    }
    
    public void listUpcomingEvents(String siteId) {
        String calendarRef = calendarService.calendarReference(siteId, "main");
        List<String> refs = Arrays.asList(calendarRef);
        
        // Get events for next 7 days
        Time now = timeService.newTime();
        Time weekFromNow = timeService.newTime(now.getTime() + 7 * 24 * 60 * 60 * 1000);
        TimeRange range = timeService.newTimeRange(now, weekFromNow);
        
        CalendarEventVector events = calendarService.getEvents(refs, range);
        
        System.out.println("Upcoming events:");
        for (Object obj : events) {
            CalendarEvent event = (CalendarEvent) obj;
            System.out.println("- " + event.getDisplayName() + 
                             " (" + event.getRange().firstTime() + ")");
        }
    }
}

See Also

• Time API - Time and TimeRange objects
• Entity API - Entity and reference handling