1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
PollDance
---------
Date: January 31st, 2013
Authors: Justin Karneges <justin@fanout.io>
Katsuyuki Ohmuro <harmony7@pex2.jp>
PollDance is a general-purpose AJAX library that provides conveniences for
long-polling applications, such as request retries, exponential backoff
between requests, randomized request delaying, and workarounds for browser
"busy" indications. It also implements multiple transports to ensure
cross-domain access works in all major browsers.
Dependencies:
json2.js
Available Transports:
XmlHttpRequest - for same-origin requests on all browsers, and cross-origin
requests on modern CORS browsers
JSON-P - for cross-origin requests on older non-CORS browsers such as IE7,
IE8, IE9, and Opera < 12.00
Limitations:
- If the JSON-P transport is used, the request headers and body are subject
to URI length limitations of the browser and server.
- If the JSON-P transport is used, it may not be possible to inspect all of
the response headers. At most, the server may provide "noteworthy" headers
within the JSON-P encoding.
Usage:
var req = new PollDance.Request();
req.on('finished', function(code, result, headers) { ... });
req.on('error', function(reason) { ... });
var headers = { ... };
var body = 'some data';
req.maxTries = 2; // try twice
req.start('POST', 'http://example.com/path', headers, body);
Methods of Request Object:
on(event_name, callback) - Add callback for event:
event_name: name of event
callback: method to call when event occurs
available events:
'finished': function(code, result, headers)
code: HTTP status code
result: JSON object or string
headers: hash of key/value strings
'error': function(reason)
reason: PollDance.errorType
off(event_name) - Remove callback for event
start(method, url, headers, body) - start request
method: name of method (e.g. 'GET')
url: string url, or function that returns a string url if called
headers: hash of key/value strings (optional)
body: string body data (optional)
Sometime after the request has been started, a finished or error event
will be raised and the object will return to inactive state (unless the
recurring flag is set, see below).
The start method may be called again once the request has completed
(unless the recurring flag is set, see below). If called again on the same
object, a short random delay will be added before performing the request.
retry() - Attempt the exact same request again. Normally, PollDance will
automatically retry a request that it considers to be a failure, but this
method may be used if the application needs to retry the request for any
another reason. Retries have an exponentially increasing delay between
them. Do not use retry() if the previous request attempt was considered to
be successful, as it will add penalizing delays that you probably don't
want in that case.
abort() - Stop any current request and return the object to inactive state.
Properties of Request Object:
Properties are simple members of the object. They can be set directly:
req.rawResponse = true;
or passed in a hash during construction:
var req = new PollDance.Request({rawResponse: true});
rawResponse: boolean
By default, this library will parse response body data as JSON and return
an object to the application. Set the rawResponse property to true to
disable this behavior and have a string returned instead.
maxTries: int
The number of tries a request should be attempted with temporary failure
before raising an error event. Set to -1 to indicate infinite attempts.
Default is 1.
maxDelay: int
The maximum amount of random milliseconds to delay between requests.
Default 1000.
recurring: boolean
If set to true, then after a request finishes with a code between 200 and
299, and the finished event has been raised, the same request will be
started again. This allows PollDance to automatically poll a resource
endlessly. Pass a function as the url argument in order to be able to
change the url between polls.
transport: PollDance.transportType
Explicitly set the transport to use. Default is transportType.Auto, which
automatically chooses the best transport when the request is started.
Retries:
When a request fails at the transport level, or the request succeeds with an
error code between 500 and 599, and maxTries has not been reached, then
PollDance will retry the request silently, with an exponentially increasing
delay between attempts. In any other case, the request will succeed and
the finished event will be raised. If the application determines that the
response indicates a temporary error and should be retried with the same
backoff delay that PollDance normally uses, the retry() method may be used.
Request Reuse:
If start() is called on an object that has completed a request and is now
inactive, then a random delay will be added before performing the next
request. This is ideal behavior when repeatedly polling a resource, so do
try to reuse the request object rather than throwing it away and creating a
new one every time. When the recurring flag is used, the effect is the same
as if you had called start() again yourself after a request finished.
Be sure to recognize the difference between a retry and a reuse of the
object. A retry implies that the previous request attempt was a failure,
whereas reusing the object means the previous request attempt was
successful. This distinction is important because it changes the way the
delaying works.
JSON-P Protocol:
This library supports JSON-P by supplying the following query string
parameters in the request:
callback: the JavaScript function to call in the response script
_method: the method name (default GET)
_headers: additional headers encoded as JSON (default none)
_body: request body (default empty)
This protocol dictates that the presence of the "callback" parameter
signifies the request as a JSON-P request. The remaining parameters are
optional.
The server is expected to reply with a JSON object with fields:
code: the HTTP response status code
reason: the HTTP response reason phrase
headers: any noteworthy HTTP response headers (default none)
body: response body
All fields are required except for "headers". Example response:
{
"code": 200,
"reason": "OK",
"headers": {
"Content-Type": "application/json"
},
"body": "{ \"foo\": \"bar\" }"
}
|