diff --git a/lib/promise.js b/lib/promise.js index f59eb790d9..856263fb2c 100644 --- a/lib/promise.js +++ b/lib/promise.js @@ -17,12 +17,12 @@ var AWS = require('./core'); var inherit = AWS.util.inherit; /** - * == Asynchronous Promise Objects + * == Asynchronous Requests * - * All requests made through the SDK are asynchronous and use an - * event-based promise callback interface. Each service method - * that kicks off a request returns an +AWS.AWSRequest+ promise - * object that you can use to register callbacks. + * All requests made through the SDK are asynchronous and use a + * callback interface. Each service method that kicks off a request + * returns an +AWS.AWSRequest+ object that you can use to register + * callbacks. * * For example, the following service method returns the request * object as "request", which can be used to register callbacks: @@ -35,6 +35,11 @@ var inherit = AWS.util.inherit; * console.log(resp.data); * }); * + * When a request is ready to be sent, the {send} method should + * be called: + * + * request.send(); + * * == Multiple Callbacks and Chaining * * You can register multiple callbacks on any request object. The @@ -51,7 +56,8 @@ var inherit = AWS.util.inherit; * }). * always(function(response) { * console.log("Always!"); - * }); + * }). + * send(); * * The above example will print either "Success! Always!", or "Error! Always!", * depending on whether the request succeeded or not. @@ -68,7 +74,7 @@ var inherit = AWS.util.inherit; * var myContext = new Object(); * request.always(function(response) { * console.log(this === myContext); - * }, {bind: myContext}); + * }, {bind: myContext}).send(); * * The above callback will print +true+ when the callback function is executed. * @@ -88,10 +94,26 @@ AWS.AWSRequest = inherit({ this.callbacks = { data: [], done: [], fail: [], always: [] }; }, + /** + * @!group Sending a Request + */ + + /** + * Initiates sending of the given request object. + * + * @example Sending a request + * request = s3.client.putObject({Bucket: 'bucket', Key: 'key'}); + * request.done(function(resp) { ... }); // register a callback + * request.send(); + */ send: function send() { new AWS.RequestHandler(this).makeRequest(); }, + /** + * @!group Registering Callbacks + */ + /** * This event is used to stream response data from the * service packet-by-packet. This event is mostly used for large responses, @@ -102,7 +124,7 @@ AWS.AWSRequest = inherit({ * * s3.client.getObject({Bucket: b, Key: k}).data(function(resp) { * console.log(resp.data); - * }); + * }).send(); * * Prints: * @@ -139,7 +161,7 @@ AWS.AWSRequest = inherit({ * * s3.client.listBuckets().done(function(response) { * console.log(response.data); - * }); + * }).send(); * * Prints: * @@ -178,7 +200,7 @@ AWS.AWSRequest = inherit({ * s3.config.credentials.accessKeyId = 'invalid'; * s3.client.listBuckets().fail(function(response) { * console.log(response.error); - * }); + * }).send(); * * Prints: * @@ -217,7 +239,7 @@ AWS.AWSRequest = inherit({ * } else { * // we can use response.data here * } - * }); + * }).send(); * * @option options bind [Object] (response object) an object to bind * the callback function to. Defaults to the response object.