org.exoplatform.calendar.ws

Class CalendarRestApi

java.lang.Object

org.exoplatform.calendar.ws.CalendarRestApi

All Implemented Interfaces:

org.exoplatform.services.rest.resource.ResourceContainer

public class CalendarRestApi
extends Object
implements org.exoplatform.services.rest.resource.ResourceContainer

This rest service class provides entry point for calendar resources.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CalendarRestApi.Expand

Field Summary

Fields

Modifier and Type	Field and Description
static String	ATTACHMENT_URI
static String	BASE_EVENT_URL
static String	BASE_URL
static String	CAL_BASE_URI
static String	CALENDAR_URI
static String	CATEGORY_URI
static String	DEFAULT_CAL_NAME
static String	DEFAULT_EVENT_NAME
static String[]	EVENT_AVAILABILITY
static String	EVENT_URI
static String	FEED_URI
static String	HEADER_LINK
static String	HEADER_LOCATION
static String	ICS_URI
static String	INVITATION_URI
static String	OCCURRENCE_URI
static String[]	PRIORITY
static String[]	REPEATTYPES
static String[]	RP_WEEKLY_BYDAY
static String	RSS_URI
static String[]	TASK_STATUS
static String	TASK_URI
static String	TEXT_ICS
static javax.ws.rs.core.MediaType	TEXT_ICS_TYPE

Constructor Summary

Constructors

Constructor and Description
CalendarRestApi(org.exoplatform.services.organization.OrganizationService orgService, org.exoplatform.container.xml.InitParams params) Constructor helps to configure the rest service with parameters.

Method Summary

Methods

Modifier and Type	Method and Description
javax.ws.rs.core.Response	createAttachmentForEvent(javax.ws.rs.core.UriInfo uriInfo, String id, Iterator<org.apache.commons.fileupload.FileItem> iter) Creates attachments for an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.
javax.ws.rs.core.Response	createCalendar(CalendarResource cal, javax.ws.rs.core.UriInfo uriInfo) Creates a calendar based on calendar attributes sent in the request body.
javax.ws.rs.core.Response	createEventForCalendar(String id, EventResource evObject, javax.ws.rs.core.UriInfo uriInfo) Creates an event in a calendar specified by id, in one of conditions: The authenticated user is the owner of the calendar, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.
javax.ws.rs.core.Response	createInvitationForEvent(String id, InvitationResource invitation, javax.ws.rs.core.UriInfo uriInfo) Creates an invitation in an event specified by event id, in one of conditions: the authenticated user is the participant of the event, OR the authenticated user has edit permission on the calendar of the event.
javax.ws.rs.core.Response	createTaskForCalendar(String id, TaskResource evObject, javax.ws.rs.core.UriInfo uriInfo) Creates a task for a calendar specified by id, in one of conditions: The user is the owner of the calendar, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.
javax.ws.rs.core.Response	deleteAttachmentById(String id) Deletes an attachment (of an event/task) specified by attachment id, in one of conditions: The calendar of the event/task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event or is delegated to the task, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	deleteCalendarById(String id) Deletes a calendar specified by id, in one of conditions: - the authenticated user is the owner of the calendar.
javax.ws.rs.core.Response	deleteEventById(String id) Deletes an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.
javax.ws.rs.core.Response	deleteFeedById(String id) Deletes a feed with the given id.
javax.ws.rs.core.Response	deleteInvitationById(String id) Deletes an invitation with specified id.
javax.ws.rs.core.Response	deleteTaskById(String id) Deletes a task specified by id, in one of conditions: the calendar of the task is public; OR the authenticated user is the owner of the calendar; OR the user belongs to the group of the calendar; OR the task is delegated to the user; OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	exportCalendarToIcs(String id, javax.ws.rs.core.Request request) Exports a calendar specified by id into iCal formated file, with one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getAttachmentById(String id, String fields, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Queries an attachment (of an event/task) by attachment id, in one of conditions: The calendar of the event/task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event or is delegated to the task, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getAttachmentsFromEvent(String id, int offset, int limit, String fields, String jsonp, javax.ws.rs.core.UriInfo uriInfo) Returns attachments of an event specified by event id, in one of conditions: The calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getCalendarById(String id, String fields, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Search for a calendar by its id, in one of conditions: The authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getCalendars(String type, int offset, int limit, boolean returnSize, String fields, String jsonp, javax.ws.rs.core.UriInfo uri) Searches for calendars by a type (personal/group/shared), returns calendars that the user has access permission.
javax.ws.rs.core.Response	getEventById(String id, String fields, String expand, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Searches for an event by id, in one of conditions: The calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar of the event has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getEventCategories(int offset, int limit, String fields, String jsonp, javax.ws.rs.core.UriInfo uriInfo) Returns the categories (common and personal categories).
javax.ws.rs.core.Response	getEventCategoryById(String id, String fields, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Returns a category specified by id if it is a common category or is a personal category of the user.
javax.ws.rs.core.Response	getEventsByCalendar(String id, String start, String end, String category, int offset, int limit, String fields, String jsonp, String expand, boolean returnSize, javax.ws.rs.core.UriInfo uri) Returns events of a calendar specified by id, in one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getFeedById(String id, String fields, String expand, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Gets a feed with the given id.
javax.ws.rs.core.Response	getInvitationById(String id, String fields, String jsonp, String expand, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Returns an invitation with specified id if one of conditions: The authenticated user is the participant of the invitation, OR the user has edit permission on the calendar of the event of the invitation.
javax.ws.rs.core.Response	getInvitationsFromEvent(String id, int offset, int limit, boolean returnSize, String status, String fields, String jsonp, String expand, javax.ws.rs.core.UriInfo uriInfo) Returns invitations of an event specified by id when: the authenticated user is the participant of the invitation, OR the authenticated user has edit permission on the calendar of the event.
javax.ws.rs.core.Response	getOccurrencesFromEvent(String id, int offset, int limit, String start, String end, String fields, String jsonp, String expand, boolean returnSize, javax.ws.rs.core.UriInfo uriInfo) Returns occurrences of a recurring event specified by id, in one of conditions: the calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getRssFromFeed(String id, javax.ws.rs.core.UriInfo uri, javax.ws.rs.core.Request request) Gets the RSS stream of a feed with the given id.
javax.ws.rs.core.Response	getSubResources(javax.ws.rs.core.UriInfo uri) Returns all the available sub-resources of this API in JSON.
javax.ws.rs.core.Response	getTaskById(String id, String fields, String expand, String jsonp, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.Request request) Returns a task specified by id, in one of conditions: the calendar of the task is public; OR the authenticated user is the owner of the calendar; OR the user belongs to the group of the calendar; OR the task is delegated to the user; OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	getTasksByCalendar(String id, String start, String end, String category, int offset, int limit, String fields, String jsonp, String expand, boolean returnSize, javax.ws.rs.core.UriInfo uri) Returns tasks of a calendar specified by id, in one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the task is delegated to the user, OR the calendar has been shared with the user or with a group of the user.
javax.ws.rs.core.Response	updateCalendarById(String id, CalendarResource calObj) Update a calendar specified by id, in one of conditions: the authenticated user is the owner of the calendar, OR for group calendars, the authenticated user has edit permission on the calendar.
javax.ws.rs.core.Response	updateEventById(String id, EventResource evObject) Updates an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.
javax.ws.rs.core.Response	updateFeedById(String id, FeedResource feedResource) Updates a feed with the given id.
javax.ws.rs.core.Response	updateInvitationById(String id, String status) Replies to an invitation specified by id.
javax.ws.rs.core.Response	updateTaskById(String id, TaskResource evObject) Updates a task specified by id, in one of conditions: the calendar of the task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the task is delegated to the user, OR the calendar has been shared with the user or with a group of the user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CAL_BASE_URI

public static final String CAL_BASE_URI

See Also:

Constant Field Values

TEXT_ICS

public static final String TEXT_ICS

See Also:

Constant Field Values

TEXT_ICS_TYPE

public static final javax.ws.rs.core.MediaType TEXT_ICS_TYPE

BASE_URL

public static final String BASE_URL

See Also:

Constant Field Values

BASE_EVENT_URL

public static final String BASE_EVENT_URL

See Also:

Constant Field Values

CALENDAR_URI

public static final String CALENDAR_URI

See Also:

Constant Field Values

EVENT_URI

public static final String EVENT_URI

See Also:

Constant Field Values

TASK_URI

public static final String TASK_URI

See Also:

Constant Field Values

ICS_URI

public static final String ICS_URI

See Also:

Constant Field Values

ATTACHMENT_URI

public static final String ATTACHMENT_URI

See Also:

Constant Field Values

OCCURRENCE_URI

public static final String OCCURRENCE_URI

See Also:

Constant Field Values

CATEGORY_URI

public static final String CATEGORY_URI

See Also:

Constant Field Values

FEED_URI

public static final String FEED_URI

See Also:

Constant Field Values

RSS_URI

public static final String RSS_URI

See Also:

Constant Field Values

INVITATION_URI

public static final String INVITATION_URI

See Also:

Constant Field Values

HEADER_LINK

public static final String HEADER_LINK

See Also:

Constant Field Values

HEADER_LOCATION

public static final String HEADER_LOCATION

See Also:

Constant Field Values

DEFAULT_CAL_NAME

public static final String DEFAULT_CAL_NAME

See Also:

Constant Field Values

DEFAULT_EVENT_NAME

public static final String DEFAULT_EVENT_NAME

See Also:

Constant Field Values

RP_WEEKLY_BYDAY

public static final String[] RP_WEEKLY_BYDAY

EVENT_AVAILABILITY

public static final String[] EVENT_AVAILABILITY

REPEATTYPES

public static final String[] REPEATTYPES

PRIORITY

public static final String[] PRIORITY

TASK_STATUS

public static final String[] TASK_STATUS

Constructor Detail

CalendarRestApi

public CalendarRestApi(org.exoplatform.services.organization.OrganizationService orgService,
               org.exoplatform.container.xml.InitParams params)

Constructor helps to configure the rest service with parameters. Here is the configuration parameters: - query_limit maximum number of objects returned by a collection query, default value: 10. - cache_maxage time in milliseconds returned in the cache-control header, default value: 604800.

Parameters:

orgService - eXo organization service implementation.

params - Object contains the configuration parameters.

Method Detail

getSubResources

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getSubResources(@Context
                                                     javax.ws.rs.core.UriInfo uri)

Returns all the available sub-resources of this API in JSON.

Returns:

URLs of all REST services provided by this API, in absolute form.

getCalendars

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getCalendars(String type,
                                                  int offset,
                                                  int limit,
                                                  boolean returnSize,
                                                  String fields,
                                                  String jsonp,
                                                  @Context
                                                  javax.ws.rs.core.UriInfo uri)

Searches for calendars by a type (personal/group/shared), returns calendars that the user has access permission.

Parameters:

type - Type of calendar, can be *personal*, *group* or *shared*. If omitted or unknown, it searches for *all* types.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of calendars returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

returnSize - Default is *false*. If set to *true*, the total number of matched calendars will be returned in JSON, and a "Link" header is added. This header contains "first", "last", "next" and "previous" links.

fields - Comma-separated list of selective calendar attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

List of calendars in JSON.

createCalendar

@RolesAllowed(value="users")
public javax.ws.rs.core.Response createCalendar(CalendarResource cal,
                                                    @Context
                                                    javax.ws.rs.core.UriInfo uriInfo)

Creates a calendar based on calendar attributes sent in the request body. Can be personal or group calendar. This accepts HTTP POST request, with JSON object (cal) represents a CalendarResource. Example: { name: "Calendar name", description: "Description of the calendar" }

Parameters:

cal - JSON object contains attributes of calendar object to create. All attributes are optional. If specified explicitly, calendar name must not empty, contains only letter, digit, space, "-", "_" characters. Default value of calendar name is: calendar.

Returns:

HTTP status code.

getCalendarById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getCalendarById(String id,
                                                     String fields,
                                                     String jsonp,
                                                     @Context
                                                     javax.ws.rs.core.UriInfo uriInfo,
                                                     @Context
                                                     javax.ws.rs.core.Request request)

Search for a calendar by its id, in one of conditions: The authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the calendar to be retrieved.

fields - Comma-separated list of selective calendar attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

Calendar as JSON.

updateCalendarById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response updateCalendarById(String id,
                                                        CalendarResource calObj)

Update a calendar specified by id, in one of conditions: the authenticated user is the owner of the calendar, OR for group calendars, the authenticated user has edit permission on the calendar. This accepts HTTP PUT request, with JSON object (calObj) in the request body, and calendar id in the path. All the attributes of JSON object are optional, any absent/invalid ones will be ignored. *id*, *href* and URLs attributes are Read-only.

Parameters:

id - Identity of the updated calendar.

calObj - JSON object contains attributes of calendar object to update, all the attributes are optional.

Returns:

HTTP status code.

deleteCalendarById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteCalendarById(String id)

Deletes a calendar specified by id, in one of conditions: - the authenticated user is the owner of the calendar. - for group calendars, the authenticated user has edit permission on the calendar. - if it is a shared calendar, the calendar is not shared anymore (but not deleted).

Parameters:

id - Identity of the calendar to be deleted.

Returns:

HTTP status code.

exportCalendarToIcs

@RolesAllowed(value="users")
public javax.ws.rs.core.Response exportCalendarToIcs(String id,
                                                         @Context
                                                         javax.ws.rs.core.Request request)

Exports a calendar specified by id into iCal formated file, with one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the exported calendar.

Returns:

ICS file on success, or HTTP status code 404 on failure.

getEventById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getEventById(String id,
                                                  String fields,
                                                  String expand,
                                                  String jsonp,
                                                  @Context
                                                  javax.ws.rs.core.UriInfo uriInfo,
                                                  @Context
                                                  javax.ws.rs.core.Request request)

Searches for an event by id, in one of conditions: The calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar of the event has been shared with the user or with a group of the user.

Parameters:

id - Identity of the event.

fields - Comma-separated list of selective event attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of property names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", } It returns: { "calendar": { "editPermission": "", "viewPermission": "", "privateURL": null, "publicURL": null, "icsURL": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId/ics", "description": null, "color": "asparagus", "timeZone": "Europe/Brussels", "name": "John Smith", "type": "0", "owner": "john", "groups": null, "href": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", "id": "john-defaultCalendarId" }, }

Returns:

Event as JSON object.

updateEventById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response updateEventById(String id,
                                                     EventResource evObject)

Updates an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission. This accepts HTTP PUT request, with JSON object (evObject) in the request body, and event id in the path. All the attributes of JSON object are optional, any absent/invalid ones will be ignored. Read-only attributes: *id* and *href*, *originalEvent*, *calendar*, *recurrentId* will be ignored too.

Parameters:

id - Identity of the updated event.

evObject - JSON object contains event attributes, all are optional. If provided explicitly (not null), attributes are checked with some rules: 1. *subject* must not be empty. 2. *availability* can only be one of "available", "busy", "outside". 3. *repeat.repeatOn* can only be one of "MO", "TU", "WE", "TH", "FR", "SA", "SU". 4. *repeat.repeatBy* must be >= 1 and <= 31. 5. *repeat.repeatType* must be one of "norepeat", "daily", "weekly", "monthly", "yearly". 6. *from* date must be earlier than *to* date. 7. *priority* must be one of "none", "high", "normal", "low". 8. *privacy* can only be "public" or "private".

Returns:

HTTP status code

deleteEventById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteEventById(String id)

Deletes an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission.

Parameters:

id - Identity of the event.

Returns:

HTTP status code

getAttachmentsFromEvent

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getAttachmentsFromEvent(String id,
                                                             int offset,
                                                             int limit,
                                                             String fields,
                                                             String jsonp,
                                                             @Context
                                                             javax.ws.rs.core.UriInfo uriInfo)

Returns attachments of an event specified by event id, in one of conditions: The calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the event.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of attachments returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

fields - Comma-separated list of selective attachment attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

Attachments in JSON, or HTTP status 404 if event not found.

createAttachmentForEvent

@RolesAllowed(value="users")
public javax.ws.rs.core.Response createAttachmentForEvent(@Context
                                                              javax.ws.rs.core.UriInfo uriInfo,
                                                              String id,
                                                              Iterator<org.apache.commons.fileupload.FileItem> iter)

Creates attachments for an event specified by id, in one of conditions: The authenticated user is the owner of the calendar of the event, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission. This accepts HTTP POST request, with files in HTTP form submit request, and the event id in path.

Parameters:

id - Identity of the event.

iter - Iterator of org.apache.commons.fileupload.FileItem objects. (eXo Rest framework uses Apache file upload to parse the input stream of HTTP form submit request, and inject FileItem objects).

Returns:

HTTP status code

getEventsByCalendar

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getEventsByCalendar(String id,
                                                         String start,
                                                         String end,
                                                         String category,
                                                         int offset,
                                                         int limit,
                                                         String fields,
                                                         String jsonp,
                                                         String expand,
                                                         boolean returnSize,
                                                         @Context
                                                         javax.ws.rs.core.UriInfo uri)
                                              throws Exception

Returns events of a calendar specified by id, in one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of a calendar to search for events.

startTime - Date that complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for events *from* this date. Default: current server time.

endTime - Date that complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for events *to* this date. Default: current server time + 1 week.

category - Search for this category only. If not specified, search events of all categories.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of events returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

returnSize - Default is *false*. If set to *true*, the total number of matched calendars will be returned in JSON, and a "Link" header is added. This header contains "first", "last", "next" and "previous" links.

fields - Comma-separated list of selective event properties to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of event attribute names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", } It returns: { "calendar": { "editPermission": "", "viewPermission": "", "privateURL": null, "publicURL": null, "icsURL": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId/ics", "description": null, "color": "asparagus", "timeZone": "Europe/Brussels", "name": "John Smith", "type": "0", "owner": "john", "groups": null, "href": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", "id": "john-defaultCalendarId" }, }

Returns:

List of events in JSON, or HTTP status 404 if the calendar is not found.

Throws:

Exception

createEventForCalendar

@RolesAllowed(value="users")
public javax.ws.rs.core.Response createEventForCalendar(String id,
                                                            EventResource evObject,
                                                            @Context
                                                            javax.ws.rs.core.UriInfo uriInfo)

Creates an event in a calendar specified by id, in one of conditions: The authenticated user is the owner of the calendar, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission. This accepts HTTP POST request, with JSON object (evObject) in the request body.

Parameters:

evObject - JSON object contains attributes of event. All attributes are optional. If provided explicitly (not null), attributes are checked with some rules: 1. *subject* must not be empty, default value is: default. 2. *availability* can only be one of "available", "busy", "outside". 3. *repeat.repeatOn* can only be one of "MO", "TU", "WE", "TH", "FR", "SA", "SU". 4. *repeat.repeatBy* must be >= 1 and <= 31. 5. *repeat.repeatType* must be one of "norepeat", "daily", "weekly", "monthly", "yearly". 6. *from* date must be earlier than *to* date. 7. *priority* must be one of "none", "high", "normal", "low". 8. *privacy* can only be public or private.

id - Identity of the calendar.

Returns:

HTTP status code.

getOccurrencesFromEvent

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getOccurrencesFromEvent(String id,
                                                             int offset,
                                                             int limit,
                                                             String start,
                                                             String end,
                                                             String fields,
                                                             String jsonp,
                                                             String expand,
                                                             boolean returnSize,
                                                             @Context
                                                             javax.ws.rs.core.UriInfo uriInfo)

Returns occurrences of a recurring event specified by id, in one of conditions: the calendar of the event is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the event.

start - Date complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for occurrences *from* this date. Default: current server time.

end - Date complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for occurrences *to* this date. Default: current server time + 1 week.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of occurrences returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

returnSize - Default is *false*. If set to *true*, the total number of matched calendars will be returned in JSON, and a "Link" header is added. This header contains "first", "last", "next" and "previous" links.

fields - Comma-separated list of selective attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of property names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", } It returns: { "calendar": { "editPermission": "", "viewPermission": "", "privateURL": null, "publicURL": null, "icsURL": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId/ics", "description": null, "color": "asparagus", "timeZone": "Europe/Brussels", "name": "John Smith", "type": "0", "owner": "john", "groups": null, "href": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", "id": "john-defaultCalendarId" }, }

Returns:

List of occurrences.

getTasksByCalendar

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getTasksByCalendar(String id,
                                                        String start,
                                                        String end,
                                                        String category,
                                                        int offset,
                                                        int limit,
                                                        String fields,
                                                        String jsonp,
                                                        String expand,
                                                        boolean returnSize,
                                                        @Context
                                                        javax.ws.rs.core.UriInfo uri)
                                             throws Exception

Returns tasks of a calendar specified by id, in one of conditions: The calendar is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the task is delegated to the user, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the calendar.

startTime - Date complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for tasks *from* this date. Default: current server time.

endTime - Date complies ISO8601 (YYYY-MM-DDThh:mm:ssTZD). Search for tasks *to* this date. Default: current server time + 1 week.

category - Filter the tasks by this category if specified.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of tasks returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

returnSize - Default is *false*. If set to *true*, the total number of matched calendars will be returned in JSON, and a "Link" header is added. This header contains "first", "last", "next" and "previous" links.

fields - Comma-separated list of selective task attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of property names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", } It returns: { "calendar": { "editPermission": "", "viewPermission": "", "privateURL": null, "publicURL": null, "icsURL": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId/ics", "description": null, "color": "asparagus", "timeZone": "Europe/Brussels", "name": "John Smith", "type": "0", "owner": "john", "groups": null, "href": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", "id": "john-defaultCalendarId" }, }

Returns:

List of tasks in JSON, or HTTP status 404 if calendar not found.

Throws:

Exception

createTaskForCalendar

@RolesAllowed(value="users")
public javax.ws.rs.core.Response createTaskForCalendar(String id,
                                                           TaskResource evObject,
                                                           @Context
                                                           javax.ws.rs.core.UriInfo uriInfo)

Creates a task for a calendar specified by id, in one of conditions: The user is the owner of the calendar, OR for group calendars, the user has edit permission on the calendar, OR the calendar has been shared with the user, with edit permission, OR the calendar has been shared with a group of the user, with edit permission. This accepts HTTP POST request, with JSON object (evObject) in the request body. Example: { "name": "...", "note": "...", "categoryId": "", "from": "...", "to": "...", "delegation": ["...", ""], "priority": "", "reminder": [], "status": "" }

Parameters:

evObject - JSON object contains attributes of task. All attributes are optional. If provided explicitly (not null), attributes are checked with some rules: 1. *name* must not be empty, default value is: "default". 2. *from* date must be earlier than *to* date. 3. *priority* must be one of "none", "high", "normal", "low". 4. *status* must be one of "needs-action", "completed", "in-progress", "canceled".

id - Identity of the calendar.

Returns:

HTTP status code.

getTaskById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getTaskById(String id,
                                                 String fields,
                                                 String expand,
                                                 String jsonp,
                                                 @Context
                                                 javax.ws.rs.core.UriInfo uriInfo,
                                                 @Context
                                                 javax.ws.rs.core.Request request)

Returns a task specified by id, in one of conditions: the calendar of the task is public; OR the authenticated user is the owner of the calendar; OR the user belongs to the group of the calendar; OR the task is delegated to the user; OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the task.

fields - Comma-separated list of selective task properties to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of task attributes names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", } It returns: { "calendar": { "editPermission": "", "viewPermission": "", "privateURL": null, "publicURL": null, "icsURL": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId/ics", "description": null, "color": "asparagus", "timeZone": "Europe/Brussels", "name": "John Smith", "type": "0", "owner": "john", "groups": null, "href": "http://localhost:8080/rest/private/v1/calendar/calendars/john-defaultCalendarId", "id": "john-defaultCalendarId" }, }

Returns:

Task in JSON format, or HTTP status 404 if task not found, or 503 if any other failure.

updateTaskById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response updateTaskById(String id,
                                                    TaskResource evObject)

Updates a task specified by id, in one of conditions: the calendar of the task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the task is delegated to the user, OR the calendar has been shared with the user or with a group of the user. This accepts HTTP PUT request, with JSON object (evObject) in the request body, and task id in the path. All the attributes are optional, any absent/invalid attributes will be ignored. *id*, *href*, *calendar* are Read-only. For example: { "name": "...", "note": "...", "categoryId": "", "from": "...", "to": "...", "delegation": ["...", ""], "priority": "", "reminder": [], "status": "" }

Parameters:

id - Identity of the task.

evObject - JSON object contains attributes of the task to be updated, all attributes are optional. If provided explicitly (not null), attributes are checked with some rules: 1. *name* must not be empty. 2. *from* date must be earlier than *to* date. 3. *priority* must be one of "none", "high", "normal", "low". 4. *status* must be one of "needs-action", "completed", "in-progress", "canceled".

Returns:

HTTP status code.

deleteTaskById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteTaskById(String id)

Deletes a task specified by id, in one of conditions: the calendar of the task is public; OR the authenticated user is the owner of the calendar; OR the user belongs to the group of the calendar; OR the task is delegated to the user; OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the task.

Returns:

HTTP status code.

getAttachmentById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getAttachmentById(String id,
                                                       String fields,
                                                       String jsonp,
                                                       @Context
                                                       javax.ws.rs.core.UriInfo uriInfo,
                                                       @Context
                                                       javax.ws.rs.core.Request request)

Queries an attachment (of an event/task) by attachment id, in one of conditions: The calendar of the event/task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event or is delegated to the task, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the attachment.

fields - Comma-separated list of selective attachment attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

Attachment info in JSON.

deleteAttachmentById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteAttachmentById(String id)

Deletes an attachment (of an event/task) specified by attachment id, in one of conditions: The calendar of the event/task is public, OR the authenticated user is the owner of the calendar, OR the user belongs to the group of the calendar, OR the user is a participant of the event or is delegated to the task, OR the calendar has been shared with the user or with a group of the user.

Parameters:

id - Identity of the attachment.

Returns:

HTTP status code.

getEventCategories

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getEventCategories(int offset,
                                                        int limit,
                                                        String fields,
                                                        String jsonp,
                                                        @Context
                                                        javax.ws.rs.core.UriInfo uriInfo)

Returns the categories (common and personal categories).

Parameters:

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of categories returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

fields - Comma-separated list of selective category attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

List of categories.

getEventCategoryById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getEventCategoryById(String id,
                                                          String fields,
                                                          String jsonp,
                                                          @Context
                                                          javax.ws.rs.core.UriInfo uriInfo,
                                                          @Context
                                                          javax.ws.rs.core.Request request)

Returns a category specified by id if it is a common category or is a personal category of the user.

Parameters:

id - Identity of the category.

fields - Comma-separated list of selective category attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

Returns:

A category in JSON.

getFeedById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getFeedById(String id,
                                                 String fields,
                                                 String expand,
                                                 String jsonp,
                                                 @Context
                                                 javax.ws.rs.core.UriInfo uriInfo,
                                                 @Context
                                                 javax.ws.rs.core.Request request)

Gets a feed with the given id. The user must be the owner of the feed.

Parameters:

id - The title of the feed.

fields - Comma-separated list of selective feed attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Used to ask for more attributes of a sub-resource, instead of its link only. This is a comma-separated list of attribute names. For example: expand=calendar,categories. In case of collections, you can specify offset (default: 0), limit (default: *query_limit*). For example, expand=categories(1,5). Instead of: { "id": "...", "calendar": "http://localhost:8080/rest/private/v1/calendar/calendars/demo-defaultCalendarId" ... } It returns: { "id": "...", "calendar": { "id": "...", "name":"demo-defaultId", ... } ... }

Returns:

Feed in JSON.

updateFeedById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response updateFeedById(String id,
                                                    FeedResource feedResource)

Updates a feed with the given id. The user must be the owner of the feed. This accepts HTTP PUT request, with JSON object (feedResource) in the request body, and feed id in the path. All the feed attributes are optional, any absent/invalid attributes will be ignored. *id* and *href* are auto-generated and cannot be edited by the users. For example: { "name": "..", "calendarIds": ["...", "..."] }

Parameters:

id - The title of the feed.

feedResource - JSON object contains attributes of the feed to be updated, all the attributes are optional.

Returns:

HTTP status code.

deleteFeedById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteFeedById(String id)

Deletes a feed with the given id. The user must be the owner of the feed.

Parameters:

id - The title of the feed.

Returns:

HTTP status code.

getRssFromFeed

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getRssFromFeed(String id,
                                                    @Context
                                                    javax.ws.rs.core.UriInfo uri,
                                                    @Context
                                                    javax.ws.rs.core.Request request)

Gets the RSS stream of a feed with the given id. The user must be the owner of the feed.

Parameters:

id - The title of the feed.

Returns:

Calendar RSS.

getInvitationById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getInvitationById(String id,
                                                       String fields,
                                                       String jsonp,
                                                       String expand,
                                                       @Context
                                                       javax.ws.rs.core.UriInfo uriInfo,
                                                       @Context
                                                       javax.ws.rs.core.Request request)
                                            throws Exception

Returns an invitation with specified id if one of conditions: The authenticated user is the participant of the invitation, OR the user has edit permission on the calendar of the event of the invitation.

Parameters:

id - Identity of the invitation.

fields - Comma-separated list of selective invitation attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Use expand=event to get more event attributes instead of only link.

Returns:

Invitation as JSON.

Throws:

Exception

updateInvitationById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response updateInvitationById(String id,
                                                          String status)

Replies to an invitation specified by id. The user must be the invitee.

Parameters:

id - Identity of the invitation.

status - New status to update ("", "maybe", "yes", "no").

Returns:

HTTP status code.

deleteInvitationById

@RolesAllowed(value="users")
public javax.ws.rs.core.Response deleteInvitationById(String id)
                                               throws Exception

Deletes an invitation with specified id. The authenticated user must have edit permission on the calendar.

Parameters:

id - Identity of the invitation.

Returns:

HTTP status code.

Throws:

Exception

getInvitationsFromEvent

@RolesAllowed(value="users")
public javax.ws.rs.core.Response getInvitationsFromEvent(String id,
                                                             int offset,
                                                             int limit,
                                                             boolean returnSize,
                                                             String status,
                                                             String fields,
                                                             String jsonp,
                                                             String expand,
                                                             @Context
                                                             javax.ws.rs.core.UriInfo uriInfo)
                                                  throws Exception

Returns invitations of an event specified by id when: the authenticated user is the participant of the invitation, OR the authenticated user has edit permission on the calendar of the event.

Parameters:

id - Identity of the event.

status - Filter the invitations by this status if specified.

offset - The starting point when paging the result. Default is *0*.

limit - Maximum number of invitations returned. If omitted or exceeds the *query limit* parameter configured for the class, *query limit* is used instead.

returnSize - Default is *false*. If set to *true*, the total number of matched invitations will be returned in JSON, and a "Link" header is added. This header contains "first", "last", "next" and "previous" links.

fields - Comma-separated list of selective invitation attributes to be returned. All returned if not specified.

jsonp - The name of a JavaScript function to be used as the JSONP callback. If not specified, only JSON object is returned.

expand - Use expand=event to get more event attributes instead of only link.

Returns:

Invitations as JSON.

Throws:

Exception

createInvitationForEvent

@RolesAllowed(value="users")
public javax.ws.rs.core.Response createInvitationForEvent(String id,
                                                              InvitationResource invitation,
                                                              @Context
                                                              javax.ws.rs.core.UriInfo uriInfo)
                                                   throws Exception

Creates an invitation in an event specified by event id, in one of conditions: the authenticated user is the participant of the event, OR the authenticated user has edit permission on the calendar of the event. This accepts invitation resource in request body, for example : {"participant":"root","status":""}.

Parameters:

id - Identity of the event.

Returns:

HTTP status code.

Throws:

Exception