CalendarService API

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)

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

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)

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() + ")");
        }
    }
}

Overview

Kernel Services

Tool APIs

REST API

​Overview

​Constants

​Application Identifiers

​Event Types

​Security Permissions

​View Types

​Recurrence Modification Types

​Calendar Management

​addCalendar

​getCalendar

​editCalendar

​commitCalendar

​cancelCalendar

​removeCalendar

​Event Management

​getEvents

​getFilteredEvents

​Recurrence

​newRecurrence

​Reference Methods

​calendarReference

​eventReference

​calendarICalReference

​calendarPdfReference

​Permission Checking

​allowGetCalendar

​allowEditCalendar

​allowImportCalendar

​allowSubscribeCalendar

​Export and Subscription

​getExportEnabled

​setExportEnabled

​Utility Methods

​getCalendarReferences

​isCalendarToolInitialized

​getUpcomingDaysLimit

​Complete Example

​See Also

Build docs developers (and LLMs) love

Overview

Constants

Application Identifiers

Event Types

Security Permissions

View Types

Recurrence Modification Types

Calendar Management

addCalendar

getCalendar

editCalendar

commitCalendar

cancelCalendar

removeCalendar

Event Management

getEvents

getFilteredEvents

Recurrence

newRecurrence

Reference Methods

calendarReference

eventReference

calendarICalReference

calendarPdfReference

Permission Checking

allowGetCalendar

allowEditCalendar

allowImportCalendar

allowSubscribeCalendar

Export and Subscription

getExportEnabled

setExportEnabled

Utility Methods

getCalendarReferences

isCalendarToolInitialized

getUpcomingDaysLimit

Complete Example

See Also