diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 111 |
1 files changed, 96 insertions, 15 deletions
@@ -39,21 +39,102 @@ Usage: req.maxTries = 2; // try twice req.start('POST', 'http://example.com/path', headers, body); -Non-JSON Results: - - 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. - -Polling and Retries: - - Set the maxTries property to enable multiple request attempts, with - exponential backoff. Set maxTries to -1 to indicate infinite attempts. - Transport errors or HTTP responses in the 5xx range will cause a retry to - occur. Any other error will be returned to the application. Request objects - may be reused. If reused, a random delay is inserted before starting the - next request. By default this is a value between 0-1000ms. Set the maxDelay - property to change the upper bound. +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: |