JAMES-1671 Annotate MessageLists
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/ea3aa656 Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/ea3aa656 Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/ea3aa656 Branch: refs/heads/master Commit: ea3aa656f0df2e9cf0aac3ab522006a8ca7da1b8 Parents: ae2af74 Author: Antoine Duprat <antdup...@gmail.com> Authored: Wed Jan 27 15:05:48 2016 +0100 Committer: Antoine Duprat <antdup...@gmail.com> Committed: Thu Feb 4 10:05:22 2016 +0100 ---------------------------------------------------------------------- .../jmap/doc/specs/spec/messagelist.mdwn | 69 ++++++++++++++++++++ 1 file changed, 69 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/ea3aa656/server/protocols/jmap/doc/specs/spec/messagelist.mdwn ---------------------------------------------------------------------- diff --git a/server/protocols/jmap/doc/specs/spec/messagelist.mdwn b/server/protocols/jmap/doc/specs/spec/messagelist.mdwn index a69b3c7..dc224e9 100644 --- a/server/protocols/jmap/doc/specs/spec/messagelist.mdwn +++ b/server/protocols/jmap/doc/specs/spec/messagelist.mdwn @@ -11,31 +11,61 @@ When the state changes on the server, a delta update can be requested to efficie To fetch a message list, make a call to *getMessageList*. It takes the following arguments: - **accountId**: `String|null` + <aside class="warning"> + Not implemented + </aside> The id of the account to use for this call. If `null`, the primary account will be used. - **filter**: `FilterCondition|FilterOperator|null` + <aside class="notice"> + Only filtering on a list of mailboxIds is supported + </aside> Determines the set of messages returned in the results. See the "Filtering" section below for allowed values and semantics. - **sort**: `String[]|null` A list of Message property names to sort by. See the "Sorting" section below for allowed values and semantics. - **collapseThreads**: `Boolean|null` + <aside class="warning"> + Not implemented + </aside> If true, each thread will only be returned once in the resulting list, at the position of the first message in the list (given the filter and sort order) belonging to the thread. If `false` or `null`, threads may be returned multiple times. - **position**: `Number|null` The 0-based index of the first result in the list to return. If a negative value is given, the call MUST be rejected with an `invalidArguments` error. If `null`, 0 is used. - **anchor**: `String|null` + <aside class="warning"> + Not implemented + </aside> A Message id. The index of this message id will be used in combination with the `anchorOffset` argument to determine the index of the first result to return (see the "Windowing" section below for more details). - **anchorOffset**: `Number|null` + <aside class="warning"> + Not implemented + </aside> The index of the anchor message relative to the index of the first result to return. This MAY be negative. For example, `-1` means the first message after the anchor message should be the first result in the results returned (see the "Windowing" section below for more details). - **limit**: `Number|null` The maximum number of results to return. If `null`, no limit is presumed. The server MAY choose to enforce a maximum `limit` argument. In this case, if a greater value is given, the limit should be clamped to the maximum; since the total number of results in the list is returned, the client should not be relying on how many results are returned to determine if it has reached the end of the list. If a negative value is given, the call MUST be rejected with an `invalidArguments` error. - **fetchThreads**: `Boolean|null` + <aside class="warning"> + Not implemented + </aside> If `true`, after outputting a *messageList* response, an implicit call will be made to *getThreads* with the *threadIds* array in the response as the *ids* argument, and the *fetchMessages* and *fetchMessageProperties* arguments passed straight through from the call to *getMessageList*. If `false` or `null`, no implicit call will be made. - **fetchMessages**: `Boolean|null` + <aside class="warning"> + Not implemented + </aside> If `true` and `fetchThreads == false`, then after outputting a *messageList* response, an implicit call will be made to *getMessages* with the `messageIds` array in the response as the *ids* argument, and the *fetchMessageProperties* argument as the *properties* argument. If `false` or `null`, no implicit call will be made. - **fetchMessageProperties**: `String[]|null` + <aside class="warning"> + Not implemented + </aside> The list of properties to fetch on any fetched messages. See *getMessages* for a full description. - **fetchSearchSnippets**: `Boolean|null` + <aside class="warning"> + Not implemented + </aside> If `true`, then after outputting a *messageList* and making any other implicit calls, an implicit call will be made to *getSearchSnippets*. The *messageIds* array from the response will be used as the *messageIds* argument, and the *filter* argument will be passed straight through. If `false` or `null`, no implicit call will be made. #### Filtering +<aside class="notice"> +Only filtering on a list of mailboxIds is supported +</aside> A **FilterOperator** object has the following properties: @@ -103,6 +133,9 @@ The exact semantics for matching `String` fields is **deliberately not defined** - When searching inside the *htmlBody* property, HTML tags and attributes SHOULD be ignored. #### Sorting +<aside class="notice"> +Only sorting on id and/or date is supported +</aside> The `sort` argument lists the properties to compare between two messages to determine which comes first in the sort. If two messages have an identical value for the first property, the next property will be considered and so on. If all properties are the same (this includes the case where an empty array or `null` is given as the argument), the sort order is server-dependent, but MUST be stable between calls to `getMessageList`. @@ -133,10 +166,16 @@ The method of comparison depends on the type of the property: - `Boolean`: If sorting in ascending order, a `false` value MUST come before a `true` value. #### Thread collapsing +<aside class="warning"> +Not implemented +</aside> When `collapseThreads == true`, then after filtering and sorting the message list, the list is further winnowed by removing any messages for a thread id that has already been seen (when passing through the list sequentially). A thread will therefore only appear **once** in the `threadIds` list of the result, at the position of the first message in the list that belongs to the thread. #### Windowing +<aside class="warning"> +Not implemented +</aside> If a *position* offset is supplied, then this is the 0-based index of the first result to return in the list of messages after filtering, sorting and collapsing threads. If the index is greater than or equal to the total number of messages in the list, then there are no results to return, but this DOES NOT generate an error. If *position* is `null` (or, equivalently, omitted) this MUST be interpreted as `position: 0`. @@ -149,24 +188,51 @@ If an *anchor* is specified, any position argument supplied by the client MUST b The response to a call to *getMessageList* is called *messageList*. It has the following arguments: - **accountId**: `String` + <aside class="warning"> + Not implemented + </aside> The id of the account used for the call. - **filter**: `FilterCondition|FilterOperator|null` + <aside class="warning"> + Not implemented + </aside> The filter of the message list. Echoed back from the call. - **sort**: `String[]` + <aside class="warning"> + Not implemented + </aside> A list of Message property names used to sort by. Echoed back from the call. - **collapseThreads**: `Boolean` + <aside class="warning"> + Not implemented + </aside> Echoed back from the call. - **state**: `String` + <aside class="warning"> + Not implemented + </aside> A string encoding the current state on the server. This string will change if the results of the message list MAY have changed (for example, there has been a change to the state of the set of Messages; it does not guarantee that anything in the list has changed). It may be passed to *getMessageListUpdates* to efficiently get the set of changes from the previous state. Should a client receive back a response with a different state string to a previous call, it MUST either throw away the currently cached list and fetch it again (note, this does not require fetching the messages again, just the list of ids) or, if the server supports it, call *getMessageListUpdates* to get the delta difference. - **canCalculateUpdates**: `Boolean` + <aside class="warning"> + Not implemented + </aside> This is `true` if the server supports calling `getMessageListUpdates` with these `filter`/`sort`/`collapseThreads` parameters. Note, this does not guarantee that the getMessageListUpdates call will succeed, as it may only be possible for a limited time afterwards due to server internal implementation details. - **position**: `Number` + <aside class="warning"> + Not implemented + </aside> The 0-based index of the first result in the `threadIds` array within the complete list. - **total**: `Number` + <aside class="warning"> + Not implemented + </aside> The total number of messages in the message list (given the *filter* and *collapseThreads* arguments). - **threadIds**: `String[]` + <aside class="warning"> + Not implemented + </aside> The list of Thread ids for each message in the list after filtering, sorting and collapsing threads, 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. - **messageIds**: `String[]` The list of Message ids for each message in the list after filtering, sorting and collapsing threads, 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. @@ -184,6 +250,9 @@ The following errors may be returned instead of the `messageList` response: `anchorNotFound`: Returned if an anchor argument was supplied, but it cannot be found in the message list. ### getMessageListUpdates +<aside class="warning"> +Not implemented +</aside> The `getMessageListUpdates` call allows a client to efficiently update the state of any cached message list to match the new state on the server. It takes the following arguments: --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
