votorola.s.wap

Class DiffWAP

java.lang.Object

Call

DiffWAP

@ThreadRestricted(value="constructor")
public final class DiffWAP
extends Call

A web API for the difference cache. Calls are conventionally prefixed by 'd' (wCall=dDiff). If you choose another prefix, then adjust the parameter names below accordingly. An example request is:

http://reluk.ca:8080/v/wap?wCall=dDiff&dAnchor=Frank-FlippityNet&dA=Georgina-BeenaCom(Mike-ZeleaCom&dB=Test-a-ZeleaCom&wPretty

Difference specification parameters

Specify which difference (or differences) to return using one or more of the following parameters.

Key	Value
dA	Specifies the differences between the latest revisions of the anchor (draft b) and each of the named authors (draft a). Authors are named by mailish username. Multiple names are separated by left parentheses '(', as for example 'dA=NAME1(NAME2(NAME3'. Depends on 'dAnchor' and 'dPoll'.
dB	Specifies the differences between the latest revisions of the anchor (draft a) and each of the named authors (draft b). Authors are named by mailish username. Multiple names are separated by left parentheses '(', as for example 'dB=NAME1(NAME2(NAME3'. Depends on 'dAnchor' and 'dPoll'.

Other query parameters

These parameters are specific to the difference cache API. See also the general WAP parameters.

Key	Value	Default
dAnchor	The anchor specified by mailish username. The anchor is the refererence author for relative difference specifiers such as 'dA' and 'dB'.	Null, optional item.
dPoll	The poll of the anchor draft specified by poll name.	"Sys/p/sandbox"
dPairData	Specify 'dPairData' or 'dPairData=y' to include additional data that depends on fetching and constructing the draft pair for each difference record. Such fetches are required in any case for 'dA' and 'dB' differences, so this merely controls whether the data is included in the response.	'n'

Response

The response includes the following components. These are shown in JSON format with explanatory comments:

 {
    "d": { // or other prefix, per wCall query parameter

       "error": [ // only if a client-actionable error was detected.

          "MESSAGE",
          "MESSAGE"
          // and so on
       ],

       "diff": {

          // Difference records each indexed by difference key.

          "KEY": {

              // Difference record.

             "aUserMnemonic": "USER MNEMONIC",
               // A short abbreviation of the username of the first draft's author.
               // Depends on query parameter 'dPairData'.
             "aUsername": "USERNAME",
               // The mailish username of the first draft's author.  Depends on query
               // parameter 'dPairData'.

             "bUserMnemonic": "USER MNEMONIC",
               // A short abbreviation of the username of the second draft's author.
               // Depends on query parameter 'dPairData'.
             "bUsername": "USERNAME",
               // The mailish username of the second draft's author.  Depends on query
               // parameter 'dPairData'.

             "text": "TEXT"
               // Text of 'diff' output.
          }
          // and so on, for each difference record
       },

       "diffX": {

          // Index into difference records.  Only entries specifically requested are
          // included here.

          "A": [

             // Results for requested 'dA' differences in the order requested.  Each
             // entry is either a difference key, or null if the difference is unknown.

             "KEY",
             null,
             "KEY"
             // and so on
          ],
          "B": [

             // Results for requested 'dB' differences in the order requested.  Each
             // entry is either a difference key, or null if the difference is unknown.

             "KEY",
             null,
             "KEY"
             // and so on
          ]
       },

       "anchorMnemonic": "USER MNEMONIC",
         // A short abbreviation of the anchor's username.  Depends on query
         // parameters 'dAnchor' and 'dPairData'.
    }
 }

For a baseline reference, here is a minimal pretty request together with the corresponding response: http://reluk.ca:8080/v/wap?wCall=dDiff&wPretty

 {
    "d": {
       "diff": {},
       "diffX": {}
    }
 }

Responses are intended to be uncached when requesting relative differences such as dA or dB.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CALL_TYPE The name to use in the wCall query parameter, which is "Diff".
(package private) static Pattern	USERNAME_QUERY_ITEM_PATTERN The pattern of a single mailish username in a list-form query value, such as "Jack-ThisOrg(Jill-ThatNet(Up HillCom".

Constructor Summary

Constructors

Constructor and Description
DiffWAP(String prefix, Requesting req, ResponseConfiguration resConfig) Constructs a DiffWAP.

Method Summary

Methods

Modifier and Type	Method and Description
void	respond(Responding res) Responds to the call.

Methods inherited from class Call

init, prefix, req

Methods inherited from class java.lang.Object

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

Field Detail

CALL_TYPE

public static final String CALL_TYPE

The name to use in the wCall query parameter, which is "Diff". For example: wCall=dDiff.

See Also:

Constant Field Values

USERNAME_QUERY_ITEM_PATTERN

static final Pattern USERNAME_QUERY_ITEM_PATTERN

The pattern of a single mailish username in a list-form query value, such as "Jack-ThisOrg(Jill-ThatNet(Up HillCom". Use matcher.find() to scan the list; it will set group 1 to each username in turn.

Constructor Detail

DiffWAP

public DiffWAP(String prefix,
       Requesting req,
       ResponseConfiguration resConfig)
        throws HTTPRequestException

Constructs a DiffWAP.

Throws:

HTTPRequestException

See Also:

Call.prefix(), Call.req()

Method Detail

respond

public void respond(Responding res)
             throws IOException

Description copied from class: Call

Responds to the call.

Specified by:

respond in class Call

Throws:

IOException