Added: james/project/trunk/server/protocols/jmap/doc/spec/calendarevent.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/calendarevent.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/calendarevent.mdwn 
(added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/calendarevent.mdwn Tue 
Jan 26 10:04:59 2016
@@ -0,0 +1,302 @@
+## Calendar Events
+
+A CalendarEvent contains information about an event, or recurring series of 
events, that takes place at a particular time. The object is designed to be 
easily convertible to/from iCalendar format ([RFC 
5545](https://tools.ietf.org/html/rfc5545)) for compatibility with existing 
calendaring systems.
+
+A **CalendarEvent** object has the following properties:
+
+- **id**: `String`
+  The id of the event. This property is immutable.
+- **calendarId**: `String`
+  The id of the calendar this event belongs to.
+- **summary**: `String`
+  A short summary of the event. This maps to the SUMMARY property in iCalendar.
+- **description**: `String`
+  A longer form description of the event. This is plain text, not HTML, but
+  a client *should* attempt to mark up URLs. This maps to the DESCRIPTION 
property in iCalendar.
+- **location**: `String`
+  Where the event is to take place. This maps to the LOCATION property in 
iCalendar.
+- **showAsFree**: `Boolean`
+  If true, the even should be ignored when calculating free/busy data for the
+  user. This maps to the TRANSP property in iCalendar (`false <=> OPAQUE`, 
`true <=> TRANSPARENT`).
+- **isAllDay**: `Boolean`
+  Is the event an all day event, such as a birthday or public holiday? This 
corresponds to the type (DATE or DATE-TIME) of the DTSTART property in 
iCalendar.
+- **start**: `LocalDate`
+  The date/time the event would start in the event's time zone. This 
corresponds to the DTSTART property in iCalendar.
+- **end**: `LocalDate`
+  The date/time the event would end in the event's time zone. This corresponds 
to the DTSTART/DURATION or DTEND property in iCalendar.
+- **startTimeZone**: `String|null`
+  The [Olsen Time Zone Database](http://www.iana.org/time-zones) name for the 
timezone the start of the event is actually in, or `null` for floating time. 
This corresponds to the TZID part of the DTSTART property; if the underlying 
iCalendar file does not use an Olsen name, the server SHOULD try to guess the 
correct time zone based on the VTIMEZONE information, or fallback to floating 
time.
+- **endTimeZone**: `String|null`
+  The [Olsen Time Zone Database](http://www.iana.org/time-zones) name for the 
timezone the end of the event is actually in, or `null` for floating time. This 
corresponds to the TZID part of the DTEND property (or DTSTART if not present); 
if the underlying iCalendar file does not use an Olsen name, the server SHOULD 
try to guess the correct time zone based on the VTIMEZONE information, or 
fallback to floating time.
+- **recurrence**: `Recurrence|null`
+  The recurrence rule for the event, or `null` if it does not recur. This 
corresponds to the RRULE property in iCalendar.
+- **inclusions**: `LocalDate[]|null`
+  List of extra **local** start times to recur on. The list MUST be sorted in 
date order (oldest first). This corresponds to the RDATE property in iCalendar.
+- **exceptions**: `LocalDate[null|CalendarEvent]|null`
+  An object mapping an occurrence start time (in **local time**, not UTC) to 
either:
+  - `null`: The occurrence has been deleted. This corresponds to the EXDATE 
property in iCalendar.
+  - `CalendarEvent`: A partial CalendarEvent object. Any properties in the 
object override the property of the same name for this occurrence. This 
corresponds to extra VEVENTs with RECURRENCE-IDs in iCalendar. Allowed 
properties are:
+    - summary
+    - description
+    - location
+    - showAsFree
+    - start
+    - end
+    - startTimeZone
+    - endTimeZone
+    - alerts
+    - organizer
+    - attendees
+- **alerts**: `Alert[]|null`
+  A list of alerts to display or send the user for this event. This maps to 
the VALARM property in iCalendar.
+- **organizer**: `Participant|null`
+  The organizer of the event. This maps to the ORGANIZER property in iCalendar
+- **attendees**: `Participant[]|null`
+  A list of attendees at the event. This maps to the ATTENDEE property in 
iCalendar.
+- **attachments**: `File[]|null`
+  A list of file attachments to the event. This maps to the ATTACH property in 
iCalendar.
+
+Conditions:
+
+- The *end* date MUST be equal to or after the *start* date when both are 
converted to UTC time (the event MUST NOT have a negative duration).
+- if *isAllDay* is `true`, the *start*/*end* properties MUST have a time 
component of `T00:00:00` and *startTimeZone*/*endTimeZone* properties MUST be 
`null`.
+- if *recurrence* is `null`, *inclusions* and *exceptions* MUST also be `null`.
+- either both organizer and attendees are `null`, or neither are.
+- any `null`able array/object property MUST be `null` rather than an empty 
array or object.
+
+A **Recurrence** object is a JSON object mapping of a RECUR value type in 
iCalendar. To make it easier to check if two recurrence rules are identical, 
optional properties MUST NOT be included if the value is the default. A 
Recurrence object has the following properties:
+
+- **frequency**: `String`
+  This MUST be one of the following values:
+  - `"yearly"`
+  - `"monthly"`
+  - `"weekly"`
+  - `"daily"`
+  - `"hourly"`
+  - `"minutely"`
+  - `"secondly"`
+  To convert from iCal, simply lower-case the FREQ part.
+- **interval**: `Number` (optional)
+  The INTERVAL part from iCal. Defaults to `1` if not present. This MUST NOT 
be included if the interval == 1, to ensure a canonical representation. If 
included, it MUST be an integer `x > 1`.
+- **firstDayOfWeek**: `Number` (optional)
+  The WKST part from iCal. Defaults to `1` (Monday) if not present. This MUST 
NOT be included if == 1 (Monday), to ensure a canonical representation. It MUST 
be an integer in the range (0,6), where SU => 0, TU => 2, WE => 3 etc.
+- **byDay**: `Number[]` (optional)
+  The BYDAY part from iCal. The array MUST have at least one entry if included 
and MUST be sorted in ascending order. To convert from the iCal string format 
(e.g. SU,+1MO):
+  1. Convert SU/MO/TU… <-> 0/1/2…
+  2. If it has a number attached (+1, -2 etc.), add on 7 * the attached number.
+  e.g. `+1MO => 1 + (7 * +1) => 8`, `-2TH => 4 + (7 * -2) => -10`
+- **byDate**: `Number[]` (optional)
+  The BYMONTHDAY part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **byMonth**: `Number[]` (optional)
+  The BYMONTH part from iCal, but with Jan == 0, Feb == 1 etc. (Jan == 1 in 
iCal). The array MUST have at least one entry if included and MUST be sorted in 
ascending order.
+- **byYearDay**: `Number[]` (optional)
+  The BYYEARDAY part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **byWeekNo**: `Number[]` (optional)
+  The BYWEEKNO part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **byHour**: `Number[]` (optional)
+  The BYHOUR part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **byMinute**: `Number[]` (optional)
+  The BYMINUTE part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **bySecond**: `Number[]` (optional)
+  The BYSECOND part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **bySetPosition**: `Number[]` (optional)
+  The BYSETPOS part from iCal. The array MUST have at least one entry if 
included and MUST be sorted in ascending order.
+- **count**: `Number` (optional)
+  The COUNT part from iCal. This MUST NOT be included if an *until* property 
is specified.
+- **until**: `LocalDate` (optional)
+  The UNTIL part from iCal. This MUST NOT be included if a *count* property is 
specified.
+
+An **Alert** Object has the following properties:
+
+- **minutesBefore**: `Number`
+  The number of minutes before the start time of the event to show the alert. 
The number MAY be negative for an alert after the event start. Note, if the 
event is in floating time (including all-day events), the server SHOULD use the 
user's default time zone when determining the start time.
+- **type**: `String`
+  The value MUST be one of the following:
+  - `"email"` – the server will send an email to the user at the specified 
time. The format of this email is service-specific.
+  - `"alert"` – a message should be shown to the user on any client 
connected to this account at the specified time.
+
+A **Participant** Object has the following properties:
+
+- **name**: `String`
+  The name of the participant.
+- **email**: `String`
+  The email address of the participant.
+- **isYou**: `Boolean`
+  This is `true` if the participant is the logged in user (determining this is 
not defined and is server dependent).
+- **rsvp**: `String`
+  The value MUST be one of:
+  - `""`: no RSVP made.
+  - `"yes"`: the participant is attending
+  - `"maybe"`: the participant may be attending
+  - `"no"`: the participant is not attending
+
+A **File** Object has the following properties:
+
+- **blobId**: `String`
+  The id of the binary data.
+- **type**: `String|null`
+  The content-type of the attachment, if known.
+- **name**: `String|null`
+  The full file name, if known. e.g. "myworddocument.doc"
+- **size**: `Number|null`
+  The size, in bytes, of the attachment when fully decoded (i.e. the number of 
bytes in the file the user would download), if known.
+
+### getCalendarEvents
+
+CalendarEvents can only be fetched explicitly by id. To fetch events, make a 
call to `getCalendarEvents`. It takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If not given, defaults to the 
primary account.
+- **ids**: `String[]`
+  An array of ids for the events to fetch.
+- **properties**: `String[]|null`
+  A list of properties to fetch for each event. If `null`, all properties will 
be fetched.
+
+The `id` property is always returned, regardless of whether it is in the list 
of requested properties. The possible values for `properties` can be found 
above in the description of the CalendarEvent object.
+
+The response to *getCalendarEvents* is called *calendarEvents*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **state**: `String`
+  A string encoding the current state on the server. This string will change
+  if any events change (that is, an event is created, updated or deleted). It 
can be passed to *getCalendarEventUpdates* to efficiently get the list of 
changes from the previous state.
+- **list**: `CalendarEvent[]`
+  An array of CalendarEvent objects for the requested event ids. This may not 
be in the same order as the ids were in the request.
+- **notFound**: `String[]|null`
+  An array of calendar event ids requested which could not be found, or `null` 
if all ids were found.
+
+The following errors may be returned instead of the *events* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any calendar data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A *description* property MAY be present on the response object to help 
debug with an explanation of what the problem was.
+
+### getCalendarEventUpdates
+
+The *getCalendarEventUpdates* call allows a client to efficiently update the 
state of its cached calendar events to match the new state on the server. It 
takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **sinceState**: `String`
+  The current state of the client. This is the string that was returned as the 
*state* argument in the *calendarEvents* response. The server will return the 
changes made since this state.
+- **maxChanges**: `Number|null`
+  The maximum number of CalendarEvent ids to return in the response. The 
server MAY choose to clamp this value to a particular maximum or set a maximum 
if none is given by the client. If supplied by the client, the value MUST be a 
positive integer greater than 0. If a value outside of this range is given, the 
server MUST reject the call with an `invalidArguments` error.
+- **fetchRecords**: `Boolean|null`
+  If `true`, after outputting a *calendarEventUpdates* response, an implicit 
call will be made to *getCalendarEvents* with the *changed* property of the 
response as the *ids* argument, and the *fetchRecordProperties* argument as the 
*properties* argument. If `false` or `null`, no implicit call will be made.
+- **fetchRecordProperties**: `String[]|null`
+  Passed through as the *properties* argument to any implicit 
*getCalendarEvents* call.
+
+The response to *getCalendarEventUpdates* is called *calendarEventUpdates*. It 
has the following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String`
+  This is the *sinceState* argument echoed back; the state from which the 
server is returning changes.
+- **newState**: `String`
+  This is the state the client will be in after applying the set of changes to 
the old state.
+- **hasMoreUpdates**: `Boolean`
+  If `true`, the client may call *getCalendarEventUpdates* again with the 
*newState* returned to get further updates. If `false`, *newState* is the 
current server state.
+- **changed**: `String[]`
+  An array of CalendarEvent ids where a property of the event has changed 
between the old state and the new state, or the event has been created, and the 
event has not been destroyed.
+- **removed**: `String[]`
+  An array of CalendarEvent ids for events which have been destroyed since the 
old state.
+
+If a *maxChanges* is supplied, or set automatically by the server, the server 
must try to limit the number of ids across *changed* and *removed* to the 
number given. If there are more changes than this between the client's state 
and the current server state, the update returned MUST take the client to an 
intermediate state, from which the client can continue to call 
*getCalendarEventUpdates* until it is fully up to date. The server MAY return 
more ids than the *maxChanges* total if this is required for it to be able to 
produce an update to an intermediate state, but it SHOULD try to keep it close 
to the maximum requested.
+
+If an event has been modified AND deleted since the oldState, the server 
should just return the id in the *removed* array, but MAY return it in the 
*changed* array as well. If an event has been created AND deleted since the 
oldState, the server SHOULD remove the event id from the response entirely, but 
MAY include it in the *removed* array, and optionally the *changed* array as 
well.
+
+The following errors may be returned instead of the `calendarEventUpdates` 
response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any calendar data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.
+
+`cannotCalculateChanges`: Returned if the server cannot calculate the changes 
from the state string given by the client. Usually due to the client's state 
being too old, or the server being unable to produce an update to an 
intermediate state when there are too many updates. The client MUST invalidate 
its CalendarEvent cache. The error object MUST also include a `newState: 
String` property with the current state for the type.
+
+### setCalendarEvents
+
+Modifying the state of CalendarEvent objects on the server is done via the 
*setCalendarEvents* method. This encompasses creating, updating and destroying 
CalendarEvent records.
+
+The *setCalendarEvents* method takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **ifInState**: `String|null`
+  This is a state string as returned by the *getCalendarEvents* method. If 
supplied, the string must match the current state, otherwise the method will be 
aborted and a `stateMismatch` error returned. If `null`, the change will be 
applied to the current state.
+- **create**: `String[CalendarEvent]|null`
+  A map of *creation id* (an arbitrary string set by the client) to 
CalendarEvent objects (containing all properties except the id).
+- **update**: `String[CalendarEvent]|null`
+  A map of id to a CalendarEvent object. The object may omit any property; 
only properties that have changed need be included.
+- **destroy**: `String[]|null`
+  A list of ids for CalendarEvent objects to permanently delete.
+
+Each create, update or destroy is considered an atomic unit. It is permissible 
for the server to commit some of the changes but not others, however it is not 
permissible to only commit part of an update to a single event (e.g. update the 
*start* property but not the *startTimeZone* property if both are supplied in 
the update object).
+
+If a create, update or destroy is rejected, the appropriate error should be 
added to the notCreated/notUpdated/notDestroyed property of the response and 
the server MUST continue to the next create/update/destroy. It does not 
terminate the method.
+
+If an id given cannot be found, the update or destroy MUST be rejected with a 
`notFound` set error.
+
+CalendarEvents reference a Calendar object. When events are created or 
modified, they may reference a calendar being created *in the same API request* 
by using the creation id prefixed with a `#`. The order of the method calls in 
the request by the client MUST be such that the calendar being referenced is 
created in an earlier call. The server thus never has to look ahead. Instead, 
while processing a request (a series of method calls), the server MUST keep a 
simple map for the duration of the request of creation id to Calendar id for 
each newly created calendar, so it can substitute in the correct value if 
necessary in later method calls.
+
+To add new attachments, the file must first be uploaded using the standard 
upload mechanism (see the File Uploads section of this spec). This will give 
the client a valid blobId/size/type to use.
+
+When an event is created, updated or destroyed, the server MUST also ensure 
the following:
+
+- Any alerts are scheduled/cancelled correctly..
+- If `organizer.isYou == true`:
+  - If an event is created with attendees, send a REQUEST iMIP email with the
+    event as an ICS attachment to all attendees with `isYou == false`.
+  - When an event is updated, email all attendees with `isYou == false` the
+    change with an appropriate iMIP email.
+  - When an event is destroyed, if it is in the future, then email all
+    attendees with `isYou == false` to inform them that the event has been 
cancelled. If it is in the past, the server SHOULD NOT send a message.
+- If `organizer.isYou != true` and one of the attendees of the event has 
`isYou == true`, then changing the RSVP status of this attendee MUST send the 
appropriate email to the organizer to inform them of the change in status, as 
per the iMIP standard.
+
+Note, for compatibility with CalDAV clients, when updating an attendee, the 
server SHOULD maintain any ROLE, CUTYPE, MEMBER, DELEGATED-TO, DELEGATED-FROM, 
SENT-BY etc. parameters currently in the iCalendar object for that attendee, 
even though this API does not currently care about it.
+
+The response to *setCalendarEvents* is called *calendarEventsSet*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String|null`
+  The state string that would have been returned by *getCalendarEvents* before 
making the requested changes, or `null` if the server doesn't know what the 
previous state string was.
+- **newState**: `String`
+  The state string that will now be returned by *getCalendarEvents*.
+- **created**: `String[CalendarEvent]`
+  A map of the creation id to an object containing the **id** property for all 
successfully created events
+- **updated**: `String[]`
+  A list of ids for events that were successfully updated.
+- **destroyed**: `String[]`
+  A list of ids for events that were successfully destroyed.
+- **notCreated**: `String[SetError]`
+  A map of creation id to a SetError object for each event that failed to be 
created. The possible errors are defined in the description of the method for 
specific data types.
+- **notUpdated**: `String[SetError]`
+  A map of CalendarEvent id to a SetError object for each event that failed to 
be updated. The possible errors are defined in the description of the method 
for specific data types.
+- **notDestroyed**: `String[SetError]`
+  A map of CalendarEvent id to a SetError object for each event that failed to 
be destroyed. The possible errors are defined in the description of the method 
for specific data types.
+
+A **SetError** object has the following properties:
+
+- **type**: `String`
+  The type of error.
+- **description**: `String|null`
+  A description of the error to display to the user.
+
+If any of the properties in a create or update are invalid (immutable and 
different to the current server value, wrong type, invalid value for the 
property – like a *calendarId* for a non-existent calendar), the server MUST 
reject the create/update with a SetError of type `invalidProperties`. The 
SetError object SHOULD contain a property called *properties* of type 
`String[]` that lists **all** the properties that were invalid. The object MAY 
also contain a *description* property of type `String` with a user-friendly 
description of the problems.
+
+The following errors may be returned instead of the *calendarEventsSet* 
response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any calendar data.
+
+`accountReadOnly`: Returned if the account has `isReadOnly == true`.
+
+`invalidArguments`: Returned if one of the arguments is of the wrong type, or 
otherwise invalid. A *description* property MAY be present on the response 
object to help debug with an explanation of what the problem was.
+
+`stateMismatch`: Returned if an *ifInState* argument was supplied and it does 
not match the current state.

Added: james/project/trunk/server/protocols/jmap/doc/spec/calendareventlist.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/calendareventlist.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/calendareventlist.mdwn 
(added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/calendareventlist.mdwn 
Tue Jan 26 10:04:59 2016
@@ -0,0 +1,94 @@
+## CalendarEventLists
+
+A **CalendarEventList** is a query on the set of events in a user's calendars. 
The client can optionally also fetch the events.
+
+### getCalendarEventList
+
+To fetch a calendar event list, make a call to *getCalendarEventList*. It 
takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **filter**: `FilterCondition|FilterOperator|null`
+  Determines the set of events returned in the results. See the "Filtering" 
section below for allowed values and semantics.
+- **position**: `Number|null`
+  The 0-based index of the first result in the list to return, presumed `0` if 
`null`. If a negative value is given, the call MUST be rejected with an 
`invalidArguments` error.
+- **limit**: `Number|null`
+  The maximum number of results to return. If `null`, no limit presumed. The 
server MAY choose to enforce a maximum `limit` argument. In this case, if a 
greater value is given (or if it is `null`), the limit should be clamped to the 
maximum; since the total number of results in the list is returned, the client 
can determine if it has received all the results. If a negative value is given, 
the call MUST be rejected with an `invalidArguments` error.
+- **fetchCalendarEvents**: `Boolean|null`
+  If `true` then after outputting a *calendarEventList* response, an implicit 
call will be made to *getCalendarEvents* with the `calendarEventIds` array in 
the response as the *ids* argument. If `false` or `null`, no implicit call will 
be made.
+
+#### Filtering
+
+A **FilterOperator** object has the following properties:
+
+- **operator**: `String`
+  This MUST be one of the following strings: "AND"/"OR"/"NOT":
+  - **AND**: all of the conditions must match for the filter to match.
+  - **OR**: at least one of the conditions must match for the filter to match.
+  - **NOT**: none of the conditions must match for the filter to match.
+- **conditions**: `(FilterCondition|FilterOperator)[]`
+  The conditions to evaluate against each event.
+
+A **FilterCondition** object has the following properties:
+
+- **inCalendars**: `String[]|null`
+  A list of calendar ids. An event must be in ANY of these calendars to match 
the condition.
+- **after**: `Date|null`
+  The end of the event, or any recurrence of the event, in UTC time must be 
after this date to match the condition.
+- **before**: `Date|null`
+  The start of the event, or any recurrence of the event, in UTC time must be 
before this date to match the condition.
+- **text**: `String|null`
+  Looks for the text in the *summary*, *description*, *location*, *organizer*, 
*attendees* properties of the event or any recurrence of the event (matching 
either name or email in the organizer/attendee case).
+- **summary**: `String|null`
+  Looks for the text in the *summary* property of the event, or the overridden 
*summary* property of a recurrence.
+- **description**: `String|null`
+  Looks for the text in the *description* property of the event, or the 
overridden *description* property of a recurrence.
+- **location**: `String|null`
+  Looks for the text in the *location* property of the event, or the 
overridden *location* property of a recurrence.
+- **organizer**: `String|null`
+  Looks for the text in the name or email fields of the *organizer* property 
of the event, or the overridden *organizer* property of a recurrence.
+- **attendee**: `String|null`
+  Looks for the text in the name or email of any item in the *attendees* 
property of the event, or the overridden *attendees* property of a recurrence.
+
+If zero properties are specified on the FilterCondition, the condition MUST 
always evaluate to `true`. If multiple properties are specified, ALL must apply 
for the condition to be `true` (it is equivalent to splitting the object into 
one-property conditions and making them all the child of an AND filter 
operator).
+
+The exact semantics for matching `String` fields is **deliberately not 
defined** to allow for flexibility in indexing implementation, subject to the 
following:
+
+- Text SHOULD be matched in a case-insensitive manner.
+- Text contained in either (but matched) single or double quotes SHOULD be 
treated as a **phrase search**, that is a match is required for that exact 
sequence of words, excluding the surrounding quotation marks. Use `\"`, `\'` 
and `\\` to match a literal `"`, `'` and `\` respectively in a phrase.
+- Outside of a phrase, white-space SHOULD be treated as dividing separate 
tokens that may be searched for separately in the event, but MUST all be 
present for the event to match the filter.
+- Tokens MAY be matched on a whole-word basis using stemming (so for example a 
text search for `bus` would match "buses" but not "business").
+
+#### Sorting
+
+Results MUST be sorted in a stable order so the client can load the full list 
in sections. The exact ordering to use is server dependent.
+
+#### Windowing
+
+To paginate the results the client MAY supply a *position* argument: this is 
the 0-based index of the first result to return in the list of events after 
filtering and sorting. If the index is greater than or equal to the total 
number of events in the list, then there are no results to return, but this 
DOES NOT generate an error. If `null`, this defaults to `0`.
+
+#### Response
+
+The response to a call to *getCalendarEventList* is called 
*calendarEventList*. It has the following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **filter**: `FilterCondition|FilterOperator|null`
+  The filter of the event list. Echoed back from the call.
+- **state**: `String`
+  A string encoding the current state on the server. This string will change
+  if the results of the event list MAY have changed (for example, there has 
been a change to the state of the set of CalendarEvents; it does not guarantee 
that anything in the list has changed).
+- **position**: `Number`
+  The 0-based index of the first result in the `calendarEventIds` array within 
the complete list.
+- **total**: `Number`
+  The total number of events in the list (given the *filter*).
+- **calendarEventIds**: `String[]`
+  The list of CalendarEvent ids for each event in the list after filtering and 
sorting, starting at the index given by the *position* argument of this 
response, and continuing until it hits the end of the list or reaches the 
`limit` number of ids. Note, that recurrences are not returned separately in 
any way; the event only occurs once in the calendarEventIds array no matter how 
many times it recurs.
+
+The following errors may be returned instead of the `calendarEventList` 
response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any calendar data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.

Added: james/project/trunk/server/protocols/jmap/doc/spec/contact.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/contact.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/contact.mdwn (added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/contact.mdwn Tue Jan 26 
10:04:59 2016
@@ -0,0 +1,243 @@
+## Contacts
+
+A **Contact** object stores information about a person or company. It has the 
following properties:
+
+- **id**: `String`
+  The id of the contact. This property is immutable.
+- **isFlagged**: `Boolean`
+  Is the contact flagged (marked as important in some way by the user)?
+- **avatar**: `File|null`
+  A file containing an image to be used to represent this contact.
+- **prefix**: `String`
+  The honorific title of the contact, e.g. "Mr", "Ms", "Dr", etc.
+- **firstName**: `String`
+  The first name(s) of a contact.
+- **lastName**: `String`
+  The last name of a contact.
+- **suffix**: `String`
+  The honorific suffix of the contact, e.g. "B.A.", "Esq." etc.
+- **nickname**: `String`
+  The nickname of the contact.
+- **birthday**: `String`
+  The person's birth date in the form `"YYYY-MM-DD"` (any part may be all `0`s 
for unknown).
+- **anniversary**: `String`
+  The person's anniversary date in the form `"YYYY-MM-DD"` (any part may be 
all `0`s for unknown).
+- **company**: `String`
+  The company for which the person works.
+- **department**: `String`
+  The department within the company for which the person works.
+- **jobTitle**: `String`
+  The job title of the person.
+- **emails**: `ContactInformation[]`
+  An array of ContactInformation objects where the values are email addresses. 
Types are:
+  - `"personal"` The address is for emailing the person in a personal context.
+  - `"work"` The address is for emailing the person in a professional context.
+  - `"other"` The address is for some other purpose. A *label* property MAY be 
included to display next to the address to help the user identify its purpose.
+- **phones**: `ContactInformation[]`
+  An array of ContactInformation objects where the values are phone numbers. 
Types are:
+  - `"home"` The number is for contacting the person at their residence.
+  - `"work"` The number is for contacting the person at their workplace.
+  - `"mobile"` The number is for contacting the person regardless of location.
+  - `"fax"` The number is for sending faxes to the contact.
+  - `"pager"` The number is for a pager or beeper associated with the contact.
+  - `"other"` The number is for some other purpose. A *label* property MAY be 
included to display next to the number to help the user identify its purpose.
+- **online**: `ContactInformation[]`
+  An array of ContactInformation objects where the values are URIs or 
usernames associated with the person for online services.
+  Types are:
+  - `"uri"` The value is a URI, e.g. a website link.
+  - `"username"` The value is a username associated with the person (e.g. for 
Twitter, or Facebook, or an IM client). A *label* property SHOULD be included 
to identify what service this is for. For compatibility between clients, this 
label SHOULD be the canonical service name, including capitalisation. e.g. 
`"Twitter"`, `"Facebook"`, `"Skype"`, `"GitHub"`, `"XMPP"`.
+  - `"other"` The value is something else not covered by the above categories. 
A *label* property MAY be included to display next to the number to help the 
user identify its purpose.
+- **addresses**: `Address[]`
+  An array of Address objects, containing physical locations associated with 
the person.
+  Types are:
+  - `"home"` An address of a residence associated with the person.
+  - `"work"` An address of a workplace associated with the person.
+  - `"billing"` An address to be used with billing associated with the person.
+  - `"postal"` An address to be used for delivering physical items to the 
person.
+  - `"other"` An address not covered by the above categories.
+- **notes**: `String`
+  Arbitrary notes about the contact.
+
+Note, none of these properties have a `null`able type. If the specific 
information is not known for a contact, the empty string or empty array should 
be used as appropriate, or in the case of birthday the string `"0000-00-00"`.
+
+A **ContactInformation** object has the following properties:
+
+- **type**: `String`
+  Specifies the context of the contact information. This MUST be taken from 
the set of values allowed depending on whether this is part of the *phones*, 
*emails* or *online* property (see above).
+- **label**: `String|null`
+  A label describing the value in more detail, especially if `type === 
"other"` (but MAY be included with any type).
+- **value**: `String`
+  The actual contact information, e.g. the email address or phone number.
+- **isDefault**: `Boolean`
+  Whether this contact is the default for its type (SHOULD only be one per 
type, but some backends will allow multiple defaults)
+
+An **Address** object has the following properties:
+
+- **type**: `String`
+  Specifies the context of the contact information. This MUST be taken from 
the set of values allowed depending on whether this is part of the *phones*, 
*emails* or *online* property (see above).
+- **label**: `String|null`
+  A label describing the value in more detail, especially if `type === 
"other"` (but MAY be included with any type).
+- **street**: `String`
+  The street address. This MAY be multiple lines; newlines MUST be preserved.
+- **locality**: `String`
+  The city, town, village, post town, or other locality within which the 
street address may be found.
+- **region**: `String`
+  The province, such as a state, county, or canton within which the locality 
may be found.
+- **postcode**: `String`
+  The postal code, post code, ZIP code or other short code associated with the 
address by the relevant country's postal system.
+- **country**: `String`
+  The country name.
+- **isDefault**: `Boolean`
+  Whether this contact is the default for its type (SHOULD only be one per 
type, but some backends will allow multiple defaults)
+
+A **File** Object has the following properties:
+
+- **blobId**: `String`
+  The id of the binary data.
+- **type**: `String|null`
+  The content-type of the file, if known.
+- **name**: `String|null`
+  The full file name, if known. e.g. "myface.png"
+- **size**: `Number|null`
+  The size, in bytes, of the file when fully decoded (i.e. the number of bytes 
in the file the user would download), if known.
+
+### getContacts
+
+Contacts can either be fetched explicitly by id, or all of them at once. To 
fetch contacts, make a call to `getContacts`. It takes the following arguments:
+
+- **accountId**: `String|null`
+  The Account to fetch the contacts for. If `null`, the primary account is 
used.
+- **ids**: `String|null`
+  The ids of the contacts to fetch. If `null`, all contacts in the account are 
be fetched.
+- **properties**: `String[]|null`
+  If supplied, only the properties listed in the array will be returned for 
each contact. If `null`, all properties are returned. The id of the contact 
will **always** be returned, even if not explicitly requested.
+
+The response to *getContacts* is called *contacts*. It has the following 
arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **state**: `String`
+  A string representing the state on the server for **all** contacts. If the 
state of a contact changes, or a new contact is created, or a contact is 
destroyed, this string will change. It is used to get delta updates.
+- **list**: `Contact[]`
+  An array of the Contact objects requested. This will be the **empty array** 
if the *ids* argument was the empty array, or contained only ids for contacts 
that could not be found.
+- **notFound**: `String[]|null`
+  This array contains the ids passed to the method for contacts that do not 
exist, or `null` if all requested ids were found. It will always be `null` if 
the *ids* argument in the call was `null`.
+
+The following errors may be returned instead of the *contacts* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any contact data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.
+
+### getContactUpdates
+
+The *getContactUpdates* call allows a client to efficiently update the state 
of its cached contacts to match the new state on the server. It takes the 
following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **sinceState**: `String`
+  The current state of the client. This is the string that was returned as the 
*state* argument in the *contacts* response. The server will return the changes 
made since this state.
+- **maxChanges**: `Number|null`
+  The maximum number of Contact ids to return in the response. The server MAY 
choose to clamp this value to a particular maximum or set a maximum if none is 
given by the client. If supplied by the client, the value MUST be a positive 
integer greater than 0. If a value outside of this range is given, the server 
MUST reject the call with an `invalidArguments` error.
+- **fetchRecords**: `Boolean|null`
+  If `true`, after outputting a *contactUpdates* response, an implicit call 
will be made to *getContacts* with the *changed* property of the response as 
the *ids* argument, and the *fetchRecordProperties* argument as the 
*properties* argument. If `false` or `null`, no implicit call is made.
+- **fetchRecordProperties**: `String[]|null`
+  Passed through as the *properties* argument to any implicit *getContacts* 
call.
+
+The response to *getContactUpdates* is called *contactUpdates*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String`
+  This is the *sinceState* argument echoed back; the state from which the 
server is returning changes.
+- **newState**: `String`
+  This is the state the client will be in after applying the set of changes to 
the old state.
+- **hasMoreUpdates**: `Boolean`
+  If `true`, the client may call *getContactUpdates* again with the *newState* 
returned to get further updates. If `false`, *newState* is the current server 
state.
+- **changed**: `String[]`
+  An array of Contact ids where a property of the contact has changed between 
the old state and the new state, or the contact has been created, and the 
contact has not been destroyed.
+- **removed**: `String[]`
+  An array of Contact ids for contacts which have been destroyed since the old 
state.
+
+If a *maxChanges* is supplied, or set automatically by the server, the server 
must try to limit the number of ids across *changed* and *removed* to the 
number given. If there are more changes than this between the client's state 
and the current server state, the update returned MUST take the client to an 
intermediate state, from which the client can continue to call 
*getContactUpdates* until it is fully up to date. The server MAY return more 
ids than the *maxChanges* total if this is required for it to be able to 
produce an update to an intermediate state, but it SHOULD try to keep it close 
to the maximum requested.
+
+If a contact has been modified AND deleted since the oldState, the server 
should just return the id in the *removed* array, but MAY return it in the 
*changed* array as well. If a contact has been created AND deleted since the 
oldState, the server SHOULD remove the contact id from the response entirely, 
but MAY include it in the *removed* array, and optionally the *changed* array 
as well.
+
+The following errors may be returned instead of the `contactUpdates` response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any contacts data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.
+
+`cannotCalculateChanges`: Returned if the server cannot calculate the changes 
from the state string given by the client. Usually due to the client's state 
being too old, or the server being unable to produce an update to an 
intermediate state when there are too many updates. The client MUST invalidate 
its Contact cache. The error object MUST also include a `newState: String` 
property with the current state for the type.
+
+### setContacts
+
+Modifying the state of Contact objects on the server is done via the 
*setContacts* method. This encompasses creating, updating and destroying 
Contact records.
+
+The *setContacts* method takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **ifInState**: `String|null`
+  This is a state string as returned by the *getContacts* method. If supplied, 
the string must match the current state, otherwise the method will be aborted 
and a `stateMismatch` error returned. If `null`, the change will be applied to 
the current state.
+- **create**: `String[Contact]|null`
+  A map of *creation id* (an arbitrary string set by the client) to Contact 
objects (containing all properties except the id).
+- **update**: `String[Contact]|null`
+  A map of id to a Contact object. The object may omit any property; only 
properties that have changed need be included.
+- **destroy**: `String[]|null`
+  A list of ids for Contact objects to permanently delete.
+
+Each create, update or destroy is considered an atomic unit. It is permissible 
for the server to commit some of the changes but not others, however it is not 
permissible to only commit part of an update to a single contact (e.g. update 
the *firstName* property but not the *lastName* property if both are supplied 
in the update object).
+
+If a create, update or destroy is rejected, the appropriate error should be 
added to the notCreated/notUpdated/notDestroyed property of the response and 
the server MUST continue to the next create/update/destroy. It does not 
terminate the method.
+
+If an id given cannot be found, the update or destroy MUST be rejected with a 
`notFound` set error.
+
+To set a new avatar, the file must first be uploaded using the standard upload 
mechanism (see the File Uploads section of this spec). This will give the 
client a valid blobId/size/type to use. The server SHOULD reject attempts to 
set a file that is not a recognised image type as the avatar for a contact.
+
+The response to *setContacts* is called *contactsSet*. It has the following 
arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String|null`
+  The state string that would have been returned by *getContacts* before 
making the requested changes, or `null` if the server doesn't know what the 
previous state string was.
+- **newState**: `String`
+  The state string that will now be returned by *getContacts*.
+- **created**: `String[Contact]`
+  A map of the creation id to an object containing the **id** property for all 
successfully created contacts.
+- **updated**: `String[]`
+  A list of ids for contacts that were successfully updated.
+- **destroyed**: `String[]`
+  A list of ids for contacts that were successfully destroyed.
+- **notCreated**: `String[SetError]`
+  A map of creation id to a SetError object for each contact that failed to be 
created. The possible errors are defined in the description of the method for 
specific data types.
+- **notUpdated**: `String[SetError]`
+  A map of Contact id to a SetError object for each contact that failed to be 
updated. The possible errors are defined in the description of the method for 
specific data types.
+- **notDestroyed**: `String[SetError]`
+  A map of Contact id to a SetError object for each contact that failed to be 
destroyed. The possible errors are defined in the description of the method for 
specific data types.
+
+A **SetError** object has the following properties:
+
+- **type**: `String`
+  The type of error.
+- **description**: `String|null`
+  A description of the error to display to the user.
+
+Other properties may also be present on the object, as described in the 
relevant methods.
+
+The following errors may be returned instead of the *contactsSet* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any contacts data.
+
+`accountReadOnly`: Returned if the account has `isReadOnly == true`.
+
+`invalidArguments`: Returned if one of the arguments is of the wrong type, or 
otherwise invalid. A *description* property MAY be present on the response 
object to help debug with an explanation of what the problem was.
+
+`stateMismatch`: Returned if an *ifInState* argument was supplied and it does 
not match the current state.

Added: james/project/trunk/server/protocols/jmap/doc/spec/contactgroup.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/contactgroup.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/contactgroup.mdwn (added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/contactgroup.mdwn Tue 
Jan 26 10:04:59 2016
@@ -0,0 +1,135 @@
+## Contact Groups
+
+A **Contact Group** represents a named set of contacts. It has the following 
properties:
+
+- **id**: `String`
+  The id of the group. This property is immutable.
+- **name**: `String`
+  The user-visible name for the group, e.g. "Friends". This may be any UTF-8 
string of at least 1 character in length and maximum 256 bytes in size. The 
same name may be used by two different groups.
+- **contactIds**: `String[]`
+  The ids of the contacts in the group. This must be returned in the same 
order given by the client when the property is set.
+
+### getContactGroups
+
+Contact Groups can either be fetched explicitly by id, or all of them at once. 
To fetch contact groups, make a call to `getContactGroups`. It takes the 
following arguments:
+
+- **accountId**: `String|null`
+  The Account to fetch the groups for. If `null`, the primary account is used.
+- **ids**: `String[]|null`
+  The ids of the groups to fetch. If `null`, all contact groups in the account 
are be fetched.
+
+The response to *getContactGroups* is called *contactGroups*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **state**: `String`
+  A string representing the state on the server for **all** contact groups. If 
the name of a group changes, or a new group is created, or a group is 
destroyed, this string will change. It is used to get delta updates.
+- **list**: `ContactGroup[]`
+  An array of the ContactGroup objects requested. This will be the **empty 
array** if the *ids* argument was the empty array, or contained only ids for 
contact groups that could not be found.
+- **notFound**: `String[]|null`
+  This array contains the ids passed to the method for groups that do not 
exist, or `null` if all requested ids were found. It will always be `null` if 
the *ids* argument in the call was `null`.
+
+The following errors may be returned instead of the *contactGroups* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any contact data.
+
+`invalidArguments`: Returned if one of the arguments is of the wrong type, or 
otherwise invalid. A `description` property MAY be present on the response 
object to help debug with an explanation of what the problem was.
+
+### getContactGroupUpdates
+
+The *getContactGroupUpdates* call allows a client to efficiently update the 
state of its cached contacts to match the new state on the server. It takes the 
following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **sinceState**: `String`
+  The current state of the client. This is the string that was returned as the 
*state* argument in the *contactGroups* response. The server will return the 
changes made since this state.
+- **fetchRecords**: `Boolean|null`
+  If `true`, after outputting a *contactGroupUpdates* response, an implicit 
call will be made to *getContactGroups* with the *changed* property of the 
response as the *ids* argument. If `false` or `null`, no implicit call will be 
made.
+
+The response to *getContactGroupUpdates* is called *contactGroupUpdates*. It 
has the following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String`
+  This is the *sinceState* argument echoed back; the state from which the 
server is returning changes.
+- **newState**: `String`
+  This is the state the client will be in after applying the set of changes to 
the old state.
+- **changed**: `String[]`
+  An array of ContactGroup ids where a property of the group has changed 
between the old state and the new state, or the group has been created, and the 
group has not been destroyed.
+- **removed**: `String[]`
+  An array of ContactGroup ids for groups which have been destroyed since the 
old state.
+
+If a group has been modified AND deleted since the oldState, the server should 
just return the id in the *removed* array, but MAY return it in the *changed* 
array as well. If a group has been created AND deleted since the oldState, the 
server SHOULD remove the group id from the response entirely, but MAY include 
it in the *removed* array, and optionally the *changed* array as well.
+
+The following errors may be returned instead of the `contactGroupUpdates` 
response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not contain any contacts data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.
+
+`cannotCalculateChanges`: Returned if the server cannot calculate the changes 
from the state string given by the client. Usually due to the client's state 
being too old. The client MUST invalidate its ContactGroup cache. The error 
object MUST also include a `newState: String` property with the current state 
for the type.
+
+### setContactGroups
+
+Modifying the state of ContactGroup objects on the server is done via the 
*setContactGroups* method. This encompasses creating, updating and destroying 
ContactGroup records.
+
+The *setContactGroups* method takes the following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **ifInState**: `String|null`
+  This is a state string as returned by the *getContactGroups* method. If 
supplied, the string must match the current state, otherwise the method will be 
aborted and a `stateMismatch` error returned. If `null`, the change will be 
applied to the current state.
+- **create**: `String[ContactGroup]|null`
+  A map of *creation id* (an arbitrary string set by the client) to 
ContactGroup objects (containing all properties except the id).
+- **update**: `String[ContactGroup]|null`
+  A map of id to a ContactGroup object. The object may omit any property; only 
properties that have changed need be included.
+- **destroy**: `String[]|null`
+  A list of ids for ContactGroup objects to permanently delete.
+
+Each create, update or destroy is considered an atomic unit. It is permissible 
for the server to commit some of the changes but not others, however it is not 
permissible to only commit part of an update to a single group (e.g. update the 
*name* property but not the *contactIds* property if both are supplied in the 
update object).
+
+If a create, update or destroy is rejected, the appropriate error should be 
added to the notCreated/notUpdated/notDestroyed property of the response and 
the server MUST continue to the next create/update/destroy. It does not 
terminate the method.
+
+If an id given cannot be found, the update or destroy MUST be rejected with a 
`notFound` set error.
+
+If any of the properties in a create or update are invalid (immutable and 
different to the current server value, wrong type, non-existent contactId value 
in contactsIds list), the server MUST reject the create/update with a SetError 
of type `invalidProperties`. The SetError object SHOULD contain a property 
called *properties* of type `String[]` that lists **all** the properties that 
were invalid. The object MAY also contain a *description* property of type 
`String` with a user-friendly description of the problems.
+
+Contacts Groups reference Contacts. When groups are created or modified, they 
may reference contacts being created *in the same API request* by using the 
creation id prefixed with a `#`. The order of the method calls in the request 
by the client MUST be such that the contact being referenced is created in an 
earlier call. The server thus never has to look ahead. Instead, while 
processing a request (a series of method calls), the server MUST keep a simple 
map for the duration of the request of creation id to Contact id for each newly 
created contact, so it can substitute in the correct value if necessary in 
later method calls.
+
+The response to *setContactGroups* is called *contactGroupsSet*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **oldState**: `String|null`
+  The state string that would have been returned by *getContactGroups* before 
making the requested changes, or `null` if the server doesn't know what the 
previous state string was.
+- **newState**: `String`
+  The state string that will now be returned by *getContactGroups*.
+- **created**: `String[Contact]`
+  A map of the creation id to an object containing the **id** property for all 
successfully created groups.
+- **updated**: `String[]`
+  A list of ids for groups that were successfully updated.
+- **destroyed**: `String[]`
+  A list of ids for groups that were successfully destroyed.
+- **notCreated**: `String[SetError]`
+  A map of creation id to a SetError object for each group that failed to be 
created. The possible errors are defined in the description of the method for 
specific data types.
+- **notUpdated**: `String[SetError]`
+  A map of ContactGroup id to a SetError object for each group that failed to 
be updated. The possible errors are defined in the description of the method 
for specific data types.
+- **notDestroyed**: `String[SetError]`
+  A map of ContactGroup id to a SetError object for each group that failed to 
be destroyed. The possible errors are defined in the description of the method 
for specific data types.
+
+A **SetError** object has the following properties:
+
+- **type**: `String`
+  The type of error.
+- **description**: `String|null`
+  A description of the error to display to the user.
+
+The following errors may be returned instead of the *contactGroupsSet* 
response:
+
+`invalidArguments`: Returned if one of the arguments is of the wrong type, or 
otherwise invalid. A `description` property MAY be present on the response 
object to help debug with an explanation of what the problem was.
+
+`stateMismatch`: Returned if an `ifInState` argument was supplied and it does 
not match the current state.

Added: james/project/trunk/server/protocols/jmap/doc/spec/contactlist.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/contactlist.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/contactlist.mdwn (added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/contactlist.mdwn Tue Jan 
26 10:04:59 2016
@@ -0,0 +1,111 @@
+## ContactLists
+
+A **ContactList** is a query on the set of contacts in a user's contacts. The 
client can optionally also fetch the contacts.
+
+### getContactList
+
+To fetch a contact list, make a call to *getContactList*. It takes the 
following arguments:
+
+- **accountId**: `String|null`
+  The id of the account to use for this call. If `null`, the primary account 
will be used.
+- **filter**: `FilterCondition|FilterOperator|null`
+  Determines the set of contacts returned in the results. See the "Filtering" 
section below for allowed values and semantics.
+- **position**: `Number|null`
+  The 0-based index of the first result in the list to return, presumed `0` if 
`null`. If a negative value is given, the call MUST be rejected with an 
`invalidArguments` error.
+- **limit**: `Number|null`
+  The maximum number of results to return. If `null`, no limit presumed. The 
server MAY choose to enforce a maximum `limit` argument. In this case, if a 
greater value is given (or if it is `null`), the limit should be clamped to the 
maximum; since the total number of results in the list is returned, the client 
can determine if it has received all the results. If a negative value is given, 
the call MUST be rejected with an `invalidArguments` error.
+- **fetchContacts**: `Boolean|null`
+  If `true` then after outputting a *contactList* response, an implicit call 
will be made to *getContacts* with the `contactIds` array in the response as 
the *ids* argument. If `false` or `null`, no implicit call will be made.
+
+#### Filtering
+
+A **FilterOperator** object has the following properties:
+
+- **operator**: `String`
+  This MUST be one of the following strings: "AND"/"OR"/"NOT":
+  - **AND**: all of the conditions must match for the filter to match.
+  - **OR**: at least one of the conditions must match for the filter to match.
+  - **NOT**: none of the conditions must match for the filter to match.
+- **conditions**: `(FilterCondition|FilterOperator)[]`
+  The conditions to evaluate against each contact.
+
+A **FilterCondition** object has the following properties:
+
+- **inContactGroup**: `String[]|null`
+  A list of contact group ids. A contact must be in ANY of these groups to 
match the condition.
+- **isFlagged**: `Boolean|null`
+  The `isFlagged` property of the contact must be identical to the value given 
to match the condition.
+- **text**: `String|null`
+  Equivalent to ORing together a FilterCondition for each of the `String` 
typed conditions (prefix, firstName, etc.).
+- **prefix**: `String`
+  Looks for the text in the *prefix* property of the contact.
+- **firstName**: `String`
+  Looks for the text in the *firstName* property of the contact.
+- **lastName**: `String`
+  Looks for the text in the *lastName* property of the contact.
+- **suffix**: `String`
+  Looks for the text in the *suffix* property of the contact.
+- **nickname**: `String`
+  Looks for the text in the *nickname* property of the contact.
+- **company**: `String`
+  Looks for the text in the *company* property of the contact.
+- **department**: `String`
+  Looks for the text in the *department* property of the contact.
+- **jobTitle**: `String`
+  Looks for the text in the *jobTitle* property of the contact.
+- **email**: `String`
+  Looks for the text in the *value* property of any object in the *emails*
+  property of the contact.
+- **phone**: `String`
+  Looks for the text in the *value* property of any object in the *phones*
+  property of the contact.
+- **online**: `String`
+  Looks for the text in the *value* property of any object in the *online*
+  property of the contact.
+- **address**: `String`
+  Looks for the text in the *street*, *locality*, *region*, *postcode* or 
*country* property of any object in the *addresses* property of the contact.
+- **notes**: `String`
+  Looks for the text in the *notes* property of the contact.
+
+If zero properties are specified on the FilterCondition, the condition MUST 
always evaluate to `true`. If multiple properties are specified, ALL must apply 
for the condition to be `true` (it is equivalent to splitting the object into 
one-property conditions and making them all the child of an AND filter 
operator).
+
+The exact semantics for matching `String` fields is **deliberately not 
defined** to allow for flexibility in indexing implementation, subject to the 
following:
+
+- Text SHOULD be matched in a case-insensitive manner.
+- Text contained in either (but matched) single or double quotes SHOULD be 
treated as a **phrase search**, that is a match is required for that exact 
sequence of words, excluding the surrounding quotation marks. Use `\"`, `\'` 
and `\\` to match a literal `"`, `'` and `\` respectively in a phrase.
+- Outside of a phrase, white-space SHOULD be treated as dividing separate 
tokens that may be searched for separately in the contact, but MUST all be 
present for the contact to match the filter.
+- Tokens MAY be matched on a whole-word basis using stemming (so for example a 
text search for `bus` would match "buses" but not "business").
+
+#### Sorting
+
+Results MUST be sorted in a stable order so the client can load the full list 
in sections. The exact ordering to use is server dependent.
+
+#### Windowing
+
+To paginate the results the client MAY supply a *position* argument: this is 
the 0-based index of the first result to return in the list of contacts after 
filtering and sorting. If the index is greater than or equal to the total 
number of contacts in the list, then there are no results to return, but this 
DOES NOT generate an error. If `null`, this defaults to `0`.
+
+#### Response
+
+The response to a call to *getContactList* is called *contactList*. It has the 
following arguments:
+
+- **accountId**: `String`
+  The id of the account used for the call.
+- **filter**: `FilterCondition|FilterOperator|null`
+  The filter of the contact list. Echoed back from the call.
+- **state**: `String`
+  A string encoding the current state on the server. This string will change
+  if the results of the contact list MAY have changed (for example, there has 
been a change to the state of the set of Contacts; it does not guarantee that 
anything in the list has changed).
+- **position**: `Number`
+  The 0-based index of the first result in the `contactIds` array within the 
complete list.
+- **total**: `Number`
+  The total number of contacts in the list (given the *filter*).
+- **contactIds**: `String[]`
+  The list of Contact ids for each contact in the list after filtering and 
sorting, starting at the index given by the *position* argument of this 
response, and continuing until it hits the end of the list or reaches the 
`limit` number of ids.
+
+The following errors may be returned instead of the `contactList` response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the 
request, but it does not correspond to a valid account.
+
+`accountNoContacts`: Returned if the *accountId* given corresponds to a valid 
account, but does not support storing contact data.
+
+`invalidArguments`: Returned if the request does not include one of the 
required arguments, or one of the arguments is of the wrong type, or otherwise 
invalid. A `description` property MAY be present on the response object to help 
debug with an explanation of what the problem was.

Added: james/project/trunk/server/protocols/jmap/doc/spec/datamodel.mdwn
URL: 
http://svn.apache.org/viewvc/james/project/trunk/server/protocols/jmap/doc/spec/datamodel.mdwn?rev=1726757&view=auto
==============================================================================
--- james/project/trunk/server/protocols/jmap/doc/spec/datamodel.mdwn (added)
+++ james/project/trunk/server/protocols/jmap/doc/spec/datamodel.mdwn Tue Jan 
26 10:04:59 2016
@@ -0,0 +1,33 @@
+## Data model overview
+
+### Accounts
+
+All data belongs to an account. An account may provide access to mail, 
contacts and/or calendars. Most operations are isolated to a single account; 
there are a few explicit operations to copy data between them. A single login 
may provide access to multiple accounts, for example if another user is sharing 
data with the user.
+
+### Ids
+
+All ids for messages, contacts, etc. are assigned by the server and are 
immutable. They MUST be unique among all records of the **same type** within 
the **same account**. Ids may clash across accounts, or for two records of 
different types within the same account.
+
+### Mail
+
+As for all data types, each message has a unique, immutable id. This id does 
not change if the message changes mailboxes. A mailbox is a named, arbitrary 
set of emails. For compatibility with IMAP, a message MUST always belong to at 
least one mailbox at any time.
+
+Each message has 4 mutable boolean "flags" stored with it, each with a direct
+equivalent in IMAP. In JMAP these flags are called:
+
+* **isUnread**: Has the email not yet been read?
+* **isFlagged**: Has the email been flagged (starred, or pinned)?
+* **isDraft**: Is the email a draft?
+* **isAnswered**: Has the email been answered (replied to)?
+
+Messages are **immutable** other than these 4 flags and the set of mailboxes 
to which it belongs. To change anything else, the message must be deleted and a 
new one created (which will get a different id).
+
+Related messages are grouped into threads. When getting a message list you can 
collapse threads, which means the thread is only returned **once**, at the 
position of the first message in the thread in the non-collapsed list (given 
the sort order).
+
+### Contacts
+
+The contacts API is designed to be compatible with existing CardDAV systems. 
Each contact must have a unique, immutable id. A contact can be assigned to 
contact groups in a many-to-many relationship. A group is simply a named set of 
contacts. Contacts are completely mutable.
+
+### Calendars
+
+The calendars API is designed to be compatible with existing CalDAV systems. 
Each event must have a unique, immutable id. An event must belong to a single 
calendar. Events are completely mutable.



---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org
For additional commands, e-mail: server-dev-h...@james.apache.org

Reply via email to