You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by ma...@apache.org on 2016/01/26 08:45:38 UTC
svn commit: r1726745 [3/4] - in /james/project/trunk: ./ client-guide/ home/
server-guide/ software/ spec/
Added: james/project/trunk/spec/contact.mdwn
URL: http://svn.apache.org/viewvc/james/project/trunk/spec/contact.mdwn?rev=1726745&view=auto
==============================================================================
--- james/project/trunk/spec/contact.mdwn (added)
+++ james/project/trunk/spec/contact.mdwn Tue Jan 26 07:45:37 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/spec/contactgroup.mdwn
URL: http://svn.apache.org/viewvc/james/project/trunk/spec/contactgroup.mdwn?rev=1726745&view=auto
==============================================================================
--- james/project/trunk/spec/contactgroup.mdwn (added)
+++ james/project/trunk/spec/contactgroup.mdwn Tue Jan 26 07:45:37 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/spec/contactlist.mdwn
URL: http://svn.apache.org/viewvc/james/project/trunk/spec/contactlist.mdwn?rev=1726745&view=auto
==============================================================================
--- james/project/trunk/spec/contactlist.mdwn (added)
+++ james/project/trunk/spec/contactlist.mdwn Tue Jan 26 07:45:37 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/spec/datamodel.mdwn
URL: http://svn.apache.org/viewvc/james/project/trunk/spec/datamodel.mdwn?rev=1726745&view=auto
==============================================================================
--- james/project/trunk/spec/datamodel.mdwn (added)
+++ james/project/trunk/spec/datamodel.mdwn Tue Jan 26 07:45:37 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.
Added: james/project/trunk/spec/mailbox.mdwn
URL: http://svn.apache.org/viewvc/james/project/trunk/spec/mailbox.mdwn?rev=1726745&view=auto
==============================================================================
--- james/project/trunk/spec/mailbox.mdwn (added)
+++ james/project/trunk/spec/mailbox.mdwn Tue Jan 26 07:45:37 2016
@@ -0,0 +1,270 @@
+## Mailboxes
+
+A mailbox represents a named set of emails. This is the primary mechanism for organising messages within an account. It is analogous to a folder in IMAP or a label in other systems. A mailbox may perform a certain role in the system.
+
+A **Mailbox** object has the following properties:
+
+- **id**: `String`
+ The id of the mailbox. This property is immutable.
+- **name**: `String`
+ User-visible name for the mailbox, e.g. "Inbox". This may be any UTF-8 string of at least 1 character in length and maximum 256 bytes in size. Mailboxes MAY have the same name as a sibling Mailbox.
+- **parentId**: `String|null`
+ The mailbox id for the parent of this mailbox, or `null` if this mailbox is at the top level. Mailboxes form acyclic graphs (forests) directed by the child-to-parent relationship. There MUST NOT be a loop.
+- **role**: `String|null`
+ Identifies system mailboxes. This property is immutable.
+
+ The following values SHOULD be used for the relevant mailboxes:
+
+ - `inbox` â the mailbox to which new mail is delivered by default, unless diverted by a rule or spam filter etc.
+ - `archive` â messages the user does not need right now, but does not wish to delete.
+ - `drafts` â messages the user is currently writing and are not yet sent.
+ - `outbox` â messages the user has finished writing and wishes to send (see the `setMessages` method description for more information). A mailbox with this role MUST be present if the user is allowed to send mail through an account. If not present, the user MAY NOT send mail with that account.
+ - `sent` â messages the user has sent.
+ - `trash` â messages the user has deleted.
+ - `spam` â messages considered spam by the server.
+ - `templates` â drafts which should be used as templates (i.e. used as the basis for creating new drafts).
+
+ No two mailboxes may have the same role. Mailboxes without a known purpose MUST have a role of `null`.
+
+ An account is not required to have mailboxes with any of the above roles. A client MAY create new mailboxes with a role property to help them keep track of a use-case not covered by the above list. To avoid potential conflict with any special behaviour a server might apply to mailboxes with certain roles in the future, any roles not in the above list created by the client must begin with `"x-"`. The client MAY attempt to create mailboxes with the standard roles if not already present, but the server MAY reject these.
+- **sortOrder**: `Number`
+ Defines the sort order of mailboxes when presented in the UI, so it is
+ consistent between devices. The number MUST be an integer in the range
+ 0 <= sortOrder < 2^31.
+
+ A mailbox with a lower order should be displayed before a mailbox with
+ a higher order (but the same parent) in any mailbox listing in the
+ client's UI. Mailboxes with equal order should be sorted in
+ alphabetical order by name. The sorting should take into locale-specific
+ character order convention.
+- **mustBeOnlyMailbox**: `Boolean`
+ If true, messages in this mailbox may not also be in any other mailbox.
+- **mayReadItems**: `Boolean`
+ If true, may use this mailbox as part of a filter in a *getMessageList* call.
+ If a submailbox is shared but not the parent mailbox, this may be `false`.
+- **mayAddItems**: `Boolean`
+ The user may add messages to this mailbox (by either creating a new message or modifying an existing one).
+- **mayRemoveItems**: `Boolean`
+ The user may remove messages from this mailbox (by either changing the mailboxes of a message or deleting it).
+- **mayCreateChild**: `Boolean`
+ The user may create a mailbox with this mailbox as its parent.
+- **mayRename**: `Boolean`
+ The user may rename the mailbox or make it a child of another mailbox.
+- **mayDelete**: `Boolean`
+ The user may delete the mailbox itself.
+- **totalMessages**: `Number`
+ The number of messages in this mailbox.
+- **unreadMessages**: `Number`
+ The number of messages in this mailbox where the *isUnread* property of the message is `true` and the *isDraft* property is `false`.
+- **totalThreads**: `Number`
+ The number of threads where at least one message in the thread is in this mailbox (but see below for special case handling of Trash).
+- **unreadThreads**: `Number`
+ The number of threads where at least one message in the thread has `isUnread == true` and `isDraft == false` AND at least one message in the thread is in this mailbox (but see below for special case handling of Trash). Note, the unread message does not need to be the one in this mailbox.
+
+The Trash mailbox (that is a mailbox with `role == "trash"`) MUST be treated specially:
+
+* Messages in the Trash are ignored when calculating the `unreadThreads` and `totalThreads` count of other mailboxes.
+* Messages not in the Trash are ignored when calculating the `unreadThreads` and `totalThreads` count for the Trash folder.
+
+The result of this is that messages in the Trash are treated as though they are in a separate thread for the purposes of mailbox counts. It is expected that clients will hide messages in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single message to the Trash out of a thread.
+
+For example, suppose you have an account where the entire contents is a single conversation with 2 messages: an unread message in the Trash and a read message in the Inbox. The `unreadThreads` count would be `1` for the Trash and `0` for the Inbox.
+
+### getMailboxes
+
+Mailboxes can either be fetched explicitly by id, or all of them at once. To fetch mailboxes, make a call to `getMailboxes`. It takes the following arguments:
+
+- **accountId**: `String|null`
+ The Account to fetch the mailboxes for. If `null`, the primary account is used.
+- **ids**: `String[]|null`
+ The ids of the mailboxes to fetch. If `null`, all mailboxes in the account are returned.
+- **properties**: `String[]|null`
+ The properties of each mailbox to fetch. If `null`, all properties are returned. The id of the mailbox will **always** be returned, even if not explicitly requested.
+
+The response to *getMailboxes* is called *mailboxes*. 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** mailboxes. If the state of a mailbox changes, or a new mailbox is created, or a mailbox is destroyed, this string will change. It is used to get delta updates.
+- **list**: `Mailbox[]`
+ An array of the Mailbox objects requested. This will be the **empty array** if the *ids* argument was the empty array, or contained only ids for mailboxes that could not be found.
+- **notFound**: `String[]|null`
+ This array contains the ids passed to the method for mailboxes 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 *mailboxes* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.
+
+`accountNoMail`: Returned if the *accountId* given corresponds to a valid account, but does not contain any mail 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.
+
+### getMailboxUpdates
+
+The *getMailboxUpdates* call allows a client to efficiently update the state of its cached mailboxes 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 *mailboxes* response. The server will return the changes made since this state.
+- **fetchRecords**: `Boolean|null`
+ If `true`, after outputting a *mailboxUpdates* response, an implicit call will be made to *getMailboxes* 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`
+ If `null`, all Mailbox properties will be fetched unless *onlyCountsChanged* in the *mailboxUpdates* response is `true`, in which case only the 4 counts properties will be returned (*totalMessages*, *unreadMessages*, *totalThreads* and *unreadThreads*). If not `null`, this value will be passed through to the *getMailboxes* call regardless of the *onlyCountsChanged* value in the *mailboxUpdates* response.
+
+The response to *getMailboxUpdates* is called *mailboxUpdates*. 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 Mailbox ids where a property of the mailbox has changed between the old state and the new state, or the mailbox has been created, and the mailbox has not been destroyed.
+- **removed**: `String[]`
+ An array of Mailbox ids for mailboxes which have been destroyed since the old state.
+- **onlyCountsChanged**: `Boolean`
+ Indicates that only the folder counts (unread/total messages/threads) have changed since the old state. The client can then use this to optimise its data transfer and only fetch the counts. If the server is unable to tell if only counts have changed, it should just always return `false`.
+
+If a mailbox 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 mailbox has been created AND deleted since the oldState, the server SHOULD remove the mailbox 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 `mailboxUpdates` response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.
+
+`accountNoMail`: Returned if the *accountId* given corresponds to a valid account, but does not contain any mail 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 Mailbox cache. The error object MUST also include a `newState: String` property with the current state for the type.
+
+### setMailboxes
+
+Mailboxes can be created, updated and destroyed using the *setMailboxes* method. The method takes the following arguments:
+
+- **accountId**: `String|null`
+ The id of the account to use for this call. If `null`, defaults to the primary account.
+- **ifInState**: `String|null`
+ This is a state string as returned by the *getMailboxes* method. If supplied, the string must match the current state, otherwise the method will be aborted and a `stateMismatch` error returned.
+- **create**: `String[Mailbox]|null`
+ A map of *creation id* (an arbitrary string set by the client) to Mailbox objects. If `null`, no objects will be created.
+- **update**: `String[Mailbox]|null`
+ A map of id to a an object containing the properties to update for that Mailbox. If `null`, no objects will be updated.
+- **destroy**: `String[]|null`
+ A list of ids for Mailboxes to permanently delete. If `null`, no objects will be deleted.
+
+Each create, update or destroy is considered an atomic unit. The server MAY commit some of the changes but not others, however MAY NOT only commit part of an update to a single record (e.g. update the *name* field but not the *parentId* field, 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.
+
+#### Creating mailboxes
+
+The properties of the Mailbox object submitted for creation MUST conform to the following conditions:
+
+- The *id* property MUST NOT be present.
+- The *parentId* property MUST be either `null` or be a valid id for a mailbox for which the `mayCreateChild` property is `true`.
+- The *role* property MUST be either `null`, a valid role as listed in the Mailbox object specification, or prefixed by `"x-"`.
+- The *mustBeOnlyMailbox* property MUST NOT be present. This is server dependent and will be set by the server.
+- The *mayXXX* properties MUST NOT be present. Restrictions may only be set by the server for system mailboxes, or when sharing mailboxes with other users (setting sharing is not defined yet in this spec).
+- The *totalMessages*, *unreadMessages*, *totalThreads* and *unreadThreads* properties MUST NOT be present.
+
+If any of the properties are invalid, the server MUST reject the create with an `invalidProperties` error. The Error 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.
+
+There may be a maximum number of mailboxes allowed on the server. If this is reached, any attempt at creation will be rejected with a `maxQuotaReached` error.
+
+#### Updating mailboxes
+
+If the *id* given does not correspond to a Mailbox in the given account, the update MUST be rejected with a `notFound` error.
+
+All properties being updated must be of the correct type, not immutable or server-set-only, and the new value must obey all conditions of the property. In particular, note the following conditions:
+
+- The *name* property MUST be valid UTF-8, between 1 and 256 bytes in size.
+- The *parentId* property MUST be either `null` or be a valid id for *another* mailbox that is **not a descendant** of this mailbox, and for which the `mayCreateChild` property is `true`.
+- These properties are immutable or may only be set by the server:
+ - id
+ - role
+ - mustBeOnlyMailbox
+ - mayReadMessageList
+ - mayAddMessages
+ - mayRemoveMessages
+ - mayCreateChild
+ - mayRenameMailbox
+ - mayDeleteMailbox
+ - totalMessages
+ - unreadMessages
+ - totalThreads
+ - unreadThreads
+
+If any of the properties are invalid, the server MUST reject the update with an `invalidProperties` error. The Error 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.
+
+#### Destroying mailboxes
+
+If the *id* given does not correspond to a Mailbox in the given account, the destruction MUST be rejected with a `notFound` error.
+
+If the mailbox has `mayDeleteMailbox == false`, the destruction MUST be rejected with a `forbidden` error.
+
+A mailbox MAY NOT be destroyed if it still has any child mailboxes. Attempting to do so will result in the destruction being rejected with a `mailboxHasChild` error.
+
+Destroying a mailbox MUST NOT delete any messages still contained within it. It only removes them from the mailbox. Since messages MUST always be in at least one mailbox, if the last mailbox they are in is deleted the messages must be added to the mailbox with `role == "inbox"`. If no Inbox exists, the messages must be moved to any other mailbox; this is server dependent.
+
+There MUST always be **at least one** mailbox. It is expected that the server will enforce this by setting `mayDeleteMailbox == false` on at least the Inbox, if not all system mailboxes. However, if this is not the case, an attempt to destroy the last mailbox MUST still be rejected with a `mailboxRequired` error.
+
+#### Ordering of changes
+
+Each individual create, update or destroy MUST take the server from one valid state to another valid state, so the changes can be processed linearly without need to undo or backtrack. However the order of the changes may affect the validity of the change. The server MUST process the changes in a manner which is indistinguishable from an order following these rules:
+
+1. Creates comes before any other changes.
+2. Creates with a parentId that is not a *creation id* reference come before those that reference another newly created mailbox.
+3. Creation of a mailbox X comes before creation of a mailbox Y if Y will be a descendent of X.
+4. Updates come before destroying mailboxes.
+5. Update/Destroy X comes before update/destroy Y if X is a descendent of Y.
+
+#### Response
+
+The response to *setMailboxes* is called *mailboxesSet*. 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 `getMailboxes` 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 `getMailboxes`.
+- **created**: `String[Mailbox]`
+ A map of the creation id to an object containing the **id** and **mustBeOnlyMailbox** properties for each successfully created Mailbox.
+- **updated**: `String[]`
+ A list of ids for Mailboxes that were successfully updated.
+- **destroyed**: `String[]`
+ A list of ids for Mailboxes that were successfully destroyed.
+- **notCreated**: `String[SetError]`
+ A map of creation id to a SetError object for each Mailbox that failed to be created. The possible errors are defined above.
+- **notUpdated**: `String[SetError]`
+ A map of Mailbox id to a SetError object for each Mailbox that failed to be updated. The possible errors are defined above.
+- **notDestroyed**: `String[SetError]`
+ A map of Mailbox id to a SetError object for each Mailbox that failed to be destroyed. The possible errors are defined above.
+
+The following errors may be returned instead of the *mailboxesSet* response:
+
+`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.
+
+`accountNoMail`: Returned if the *accountId* given corresponds to a valid account, but does not contain any mail 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.
+
+Example request:
+
+ [ "setMailboxes", {
+ "ifInState": "ms4123",
+ "update": {
+ "f3": {
+ "name": "The new name"
+ }
+ },
+ "destroy": [ "f5" ]
+ }, "#0" ]
+
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org