aws-sdk 2.0.1 → 2.0.5

package/doc-src/guide/browser-examples.md

@@ -0,0 +1,220 @@
+# @title Examples in the Browser
+
+# Examples in the Browser
+
+All of these examples assume that the AWS library is loaded, configured,
+and authenticated with the correct credentials.
+
+The common preamble code can be summarized as follows:
+
+    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.0.5.min.js"></script>
+    <script type="text/javascript">
+      // See the Configuring section to configure credentials in the SDK
+      AWS.config.credentials = ...;
+
+      // Configure your region
+      AWS.config.region = 'us-west-2';
+    </script>
+
+## Basic Usage Example
+
+The following example shows basic usage of the SDK to list objects in an
+Amazon S3 bucket:
+
+    <div id="status"></div>
+    <ul id="objects"></ul>
+
+    <script type="text/javascript">
+      var bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
+      bucket.listObjects(function (err, data) {
+        if (err) {
+          document.getElementById('status').innerHTML =
+            'Could not load objects from S3';
+        } else {
+          document.getElementById('status').innerHTML =
+            'Loaded ' + data.Contents.length + ' items from S3';
+          for (var i = 0; i < data.Contents.length; i++) {
+            document.getElementById('objects').innerHTML +=
+              '<li>' + data.Contents[i].Key + '</li>';
+          }
+        }
+      });
+    </script>
+
+## Amazon S3
+
+### Uploading data into an object
+
+The following example will upload the contents of a `<textarea>` tag to an
+object in S3:
+
+    <textarea id="data"></textarea>
+    <button id="upload-button">Upload to S3</button>
+    <div id="results"></div>
+
+    <script type="text/javascript">
+      var bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
+
+      var textarea = document.getElementById('data');
+      var button = document.getElementById('upload-button');
+      var results = document.getElementById('results');
+      button.addEventListener('click', function() {
+        results.innerHTML = '';
+
+        var params = {Key: 'data.txt', Body: textarea.value};
+        s3.putObject(params, function (err, data) {
+          results.innerHTML = err ? 'ERROR!' : 'SAVED.';
+        });
+      }, false);
+    </script>
+
+### Uploading a local file using the File API
+
+The following example uses the [HTML5 File API](http://www.w3.org/TR/FileAPI/)
+to upload a file on disk to S3:
+
+    <input type="file" id="file-chooser" /> 
+    <button id="upload-button">Upload to S3</button>
+    <div id="results"></div>
+
+    <script type="text/javascript">
+      var bucket = new AWS.S3({params: {Bucket: 'myBucket'}});
+
+      var fileChooser = document.getElementById('file-chooser');
+      var button = document.getElementById('upload-button');
+      var results = document.getElementById('results');
+      button.addEventListener('click', function() {
+        var file = fileChooser.files[0];
+        if (file) {
+          results.innerHTML = '';
+
+          var params = {Key: file.name, ContentType: file.type, Body: file};
+          bucket.putObject(params, function (err, data) {
+            results.innerHTML = err ? 'ERROR!' : 'UPLOADED.';
+          });
+        } else {
+          results.innerHTML = 'Nothing to upload.';
+        }
+      }, false);
+    </script>
+
+### Getting a pre-signed URL for a getObject operation
+
+A pre-signed URL allows you to give one-off access to other users who may not
+have direct access to execute the operations. Pre-signing generates a valid
+URL signed with your credentials that any user can access. By default, the SDK
+sets all URLs to expire within 15 minutes, but this value can be adjusted.
+
+To generate a simple pre-signed URL that allows any user to view the contents
+of a private object in a bucket you own, you can use the following call to
+`getSignedUrl()`:
+
+```javascript
+var params = {Bucket: 'myBucket', Key: 'myKey'};
+s3.getSignedUrl('getObject', params, function (err, url) {
+  console.log("The URL is", url);
+});
+```
+
+### Controlling Expires time with pre-signed URLs
+
+As mentioned above, pre-signed URLs will expire in 15 minutes by default
+when generated by the SDK. This value is adjustable with the `Expires`
+parameter, an integer representing the number of seconds that the URL will be
+valid, and can be set with any call to `getSignedUrl()`:
+
+```javascript
+// This URL will expire in one minute (60 seconds)
+var params = {Bucket: 'myBucket', Key: 'myKey', Expires: 60};
+var url = s3.getSignedUrl('getObject', params, function (err, url) {
+  if (url) console.log("The URL is", url);
+});
+```
+
+## Amazon DynamoDB
+
+### Listing tables
+
+The following example will list all tables in a DynamoDB instance.
+
+```javascript
+var db = new AWS.DynamoDB();
+db.listTables(function(err, data) {
+  console.log(data.TableNames);
+});
+```
+
+### Reading and writing items in a table
+
+The following example puts an item in a DynamoDB table and then reads it back
+using the hash key.
+
+```javascript
+var table = new AWS.DynamoDB({params: {TableName: 'MY_TABLE'}});
+var key = 'UNIQUE_KEY_ID';
+
+// Write the item to the table
+var itemParams = {Item: {id: {S: key}, data: {S: 'data'}}};
+table.putItem(itemParams, function() {
+  // Read the item from the table
+  table.getItem({Key: {id: {S: key}}}, function(err, data) {
+    console.log(data.Item); // print the item data
+  });
+});
+```
+
+## Amazon SQS
+
+### Creating a queue
+
+The following example creates a queue resource in Amazon SQS.
+
+```javascript
+var sqs = new AWS.SQS();
+sqs.createQueue({QueueName: 'MY_QUEUE_NAME'}, function (err, data) {
+  if (data) {
+    var url = data.QueueUrl; // use this queue URL to operate on the queue
+  }
+});
+```
+
+### Sending a message
+
+The following example sends a message to the queue created in the previous
+example.
+
+```javascript
+// using Queue URL variable (`url`) from previous example
+var queue = new AWS.SQS({params: {QueueUrl: url}});
+queue.sendMessage({MessageBody: 'THE MESSAGE TO SEND'}, function (err, data) {
+  if (!err) console.log('Message sent.');
+});
+```
+
+### Receiving a message
+
+The following example receives the message from the queue sent in the
+previous example.
+
+```javascript
+var queue = new AWS.SQS({params: {QueueUrl: url}}); // using url to queue
+queue.receiveMessage(function (err, data) {
+  if (data) {
+    console.log(data.Messages); // message data in Messages structure
+  }
+});
+```
+
+## Amazon SNS
+
+### Publishing to a topic
+
+The following example publishes a message to an SNS topic resource. The topic
+can be identified with a topic ARN.
+
+```javascript
+var sns = new AWS.SNS({params: {TopicArn: 'ARN_FOR_SNS_TOPIC'}});
+sns.publish({Message: 'THE MESSAGE TO PUBLISH'}, function (err, data) {
+  if (!err) console.log('Message published');
+});
+```

package/doc-src/guide/browser-intro.md

@@ -0,0 +1,46 @@
+# @title AWS SDK for JavaScript in the Browser
+
+# Getting Started with the SDK in the Browser
+
+## Loading the SDK
+
+The quickest way to get started with the SDK is to load it using the hosted
+package directly from Amazon Web Services. To do this, simply add the following
+script tag to your HTML pages:
+
+    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.0.5.min.js"></script>
+
+You can also download this package by clicking the following link:
+[aws-sdk-2.0.5.min.js](https://sdk.amazonaws.com/js/aws-sdk-2.0.5.min.js)
+
+Once the SDK is loaded in your page, the module will be available from
+the global variable `AWS` (or `window.AWS`).
+
+## Browser Support
+
+The SDK supports all modern web browsers:
+
+<table>
+  <tr>
+    <td><strong>Google Chrome</strong></td><td>28.0+</td>
+    <td><strong>Microsoft Internet Explorer</strong></td><td>10.0+</td>
+  </tr>
+  <tr>
+    <td><strong>Mozilla Firefox</strong></td><td>23.0+</td>
+    <td><strong>Apple Safari</strong></td><td>5.1+</td>
+  <tr>
+    <td><strong>Opera</strong></td><td>17.0+</td>
+    <td><strong>Android Browser</strong></td><td>4.3+</td>
+  </tr>
+</table>
+
+## Next Steps
+
+Now that you have installed and loaded the SDK, continue on to learn how to
+configure and use the SDK to make requests to API operations on services.
+
+* {file:browser-configuring.md Configuring the SDK}
+* {file:browser-services.md Working with Services}
+* {file:browser-making-requests.md Making Requests}
+* {file:browser-examples.md Common Examples}
+* {file:browser-building.md Building the SDK}

package/doc-src/guide/browser-making-requests.md

@@ -0,0 +1,279 @@
+# @title Making Requests in the Browser
+
+# Making Requests in the Browser
+
+A "request" to an AWS service includes the full request and response lifecycle
+of a call to an operation on a service object, including any retries that are
+transparently attempted on your behalf. A request is encapsulated in the SDK by
+the `AWS.Request` object. The semantics of a request are described below,
+specifically, the support for callbacks, events, and streaming of raw HTTP
+response data.
+
+## Asynchronous Callbacks
+
+All requests made through the SDK are asynchronous and use a
+callback interface. Each service method that kicks off a request
+can accept a callback as the last parameter with the signature
+`function(error, data) { ... }`. This callback will be called when
+the response or error data is available.
+
+For example, the following service method can be called with
+a standard callback to retrieve the response data or error:
+
+```javascript
+new AWS.S3().listObjects({Bucket: 'myBucket'}, function(error, data) {
+  if (error) {
+    console.log(error); // an error occurred
+  } else {
+    console.log(data); // request succeeded
+  }
+});
+```
+
+The `error` and `data` parameters are described in the "Response Object"
+section below.
+
+Note that if you do not specify a callback, the operation will
+return an `AWS.Request` object that must be manually sent using
+the `send()` method:
+
+```javascript
+// create the AWS.Request object
+var request = new AWS.S3().listObjects({Bucket: 'myBucket'});
+
+// register a callback to report on the data
+request.on('success', function(resp) {
+  console.log(resp.data); // log the successful data response
+});
+
+// send the request
+request.send();
+```
+
+### The Response Object (`AWS.Response`)
+
+The response object is passed into each callback function so
+that you can access response data. The `AWS.Response` object that
+is passed in contains two important properties to get at this data:
+
+When using the standard callback mechanism, the two properties will
+be made available as parameters on the callback method in the form:
+`function(error, data) { ... }`
+
+#### The `data` property
+
+The `response.data` property contains the serialized object data
+retrieved from the service request. For instance, for an
+Amazon DynamoDB `listTables` method call, the response data might 
+look like this:
+
+```javascript
+> response.data
+{ TableNames: 
+   [ 'table1', 'table2', ... ] }
+```
+
+The `data` property can be null if an error occurs (see below).
+
+#### The `error` property
+
+In the event of a service error (or transfer error), the
+`response.error` property will be filled with the given
+error data in the form:
+
+```javascript
+{ code: 'SHORT_UNIQUE_ERROR_CODE',
+  message: 'Some human readable error message' }
+```
+
+In the case of an error, the `data` property will be null.
+Note that if you handle events that can be in a failure state,
+you should always check whether `response.error` is set
+before attempting to access the `response.data` property.
+
+#### The `request` property
+
+Access to the originating request object is available through this
+property. For example, to access the parameters that were sent
+with a request:
+
+```javascript
+s3.getObject({Bucket: 'bucket', Key: 'key'}).on('success', function(response) {
+  console.log("Key was", response.request.params.Key);
+}).send();
+```
+
+### Simplified Callback Method
+
+Each operation supports a simplified callback that can be passed as the last
+parameter to any service operation. The callback function should
+accept an `error` parameter, followed by the `data` from the response.
+
+For example:
+
+```javascript
+s3.listBuckets(function(error, data) {
+  if (err) {
+    console.log(error); // error is Response.error
+  } else {
+    console.log(data); // data is Response.data
+  }
+});
+```
+
+Prints (assuming the request succeeded):
+
+```javascript
+{ Owner: { ID: '...', DisplayName: '...' },
+  Buckets:
+   [ { Name: 'someBucketName', CreationDate: someCreationDate },
+     { Name: 'otherBucketName', CreationDate: otherCreationDate } ],
+  RequestId: '...' }
+```
+
+The error and data parameters accepted are equivalent to the `error` and
+`data` properties discussed in the `AWS.Response` response object section
+above.
+
+If you are passing parameters to the operation, the callback should be placed
+after the parameters:
+
+```
+s3.getObject({Bucket: 'bucket', Key: 'key'}, function(err, data) {
+  // ...
+});
+```
+
+### AWS.Request Events
+
+You can alternatively register callbacks on events provided by the
+`AWS.Request` object returned by each service operation method.
+This request object exposes the `success`, `error`, `complete`, and `httpData`
+events, each taking a callback that accepts the response object.
+
+Note that if you omit the simplified callback parameter on the operation
+method, you must call `send()` on the returned request object in order to
+kick off the request to the remote server.
+
+#### Event: 'success'
+
+```javascript
+req.on('success', function(response) { ... });
+```
+
+This event triggers when a successful response
+from the server is returned. The response contains a `.data` field
+with the serialized response data from the service.
+
+For example:
+
+```javascript
+s3.listBuckets().done(function(response) {
+  console.log(response.data);
+}).send();
+```
+
+Prints:
+
+```javascript
+{ Owner: { ID: '...', DisplayName: '...' },
+  Buckets: 
+   [ { Name: 'someBucketName', CreationDate: someCreationDate },
+     { Name: 'otherBucketName', CreationDate: otherCreationDate } ],
+  RequestId: '...' }
+```
+
+#### Event: 'error'
+
+```javascript
+req.on('error', function(error, response) { ... });
+```
+
+The `error` event works similarly to the `success` event, except that it
+triggers in the case of a request failure. In this case, `response.data`
+will be `null` and the `response.error` field will be filled with
+the error data. Note that the `error` object is also passed directly
+as the first parameter to the event:
+
+```javascript
+s3.config.credentials.accessKeyId = 'invalid';
+s3.listBuckets().fail(function(error, response) {
+  console.log(error);
+  // or:
+  console.log(response.error);
+}).send();
+```
+
+Prints:
+
+```javascript
+{ code: 'Forbidden', message: null }
+```
+
+#### Event: 'complete'
+
+```javascript
+req.on('complete', function(response) { ... });
+```
+
+The `complete` event triggers a callback in any final state of a request, i.e.,
+both `success` and `error`. Use this callback to handle any request cleanup
+that must be executed regardless of the success state. Note that if you
+do intend to use response data inside of this callback, you must check
+for the presence of `response.data` or `response.error` before attempting
+to access either property. For example:
+
+```javascript
+request.on('complete', function(response) {
+  if (response.error) {
+    // an error occurred, handle it
+  } else {
+    // we can use response.data here
+  }
+}).send();
+```
+
+#### Event: 'httpData'
+
+```javascript
+req.on('httpData', function(chunk, response) { ... });
+```
+
+<p class="note">If you register a <code>httpData</code> callback,
+  <code>response.data</code> will still contain serialized output
+  for the entire request. It will be your responsibility to remove
+  the default 'httpData' listener if you do not wish to have the
+  extra parsing and memory overhead from the built-in handlers.
+</p>
+
+The `httpData` event is used to stream response data from the
+service packet-by-packet. This event is mostly used for large responses,
+when it is inefficient (or impossible) to load the entire response into
+memory.
+
+Note that this event contains an extra `chunk` parameter containing the
+actual data passed on by the server.
+
+## Multiple Callbacks and Chaining
+
+You can register multiple callbacks on any request object. The
+callbacks can be registered for different events, or all for the
+same event. In addition, you can chain callback registration, for
+example:
+
+```javascript
+request.
+  on('success', function(response) {
+    console.log("Success!");
+  }).
+  on('error', function(response) {
+    console.log("Error!");
+  }).
+  on('complete', function() {
+    console.log("Always!");
+  }).
+  send();
+```
+
+The above example will print either "Success! Always!", or "Error! Always!",
+depending on whether the request succeeded or not.

package/doc-src/guide/browser-services.md

@@ -0,0 +1,75 @@
+# @title Working with Services in the Browser
+
+# Working with Services in the Browser
+
+## Supported Services
+
+By default, the SDK ships with support for 7 AWS services. Each service object
+in the SDK currently provides low-level access to every API call in the
+respective AWS service. The full list of methods and their parameters are
+documented in the complete API reference documentation (linked from each
+service name in the list below).
+
+The 5 services that come with the default hosted package of the SDK are:
+
+* [AWS.DynamoDB](/AWSJavaScriptSDK/latest/frames.html#!AWS/DynamoDB.html)
+* [AWS.S3](/AWSJavaScriptSDK/latest/frames.html#!AWS/S3.html)
+* [AWS.SNS](/AWSJavaScriptSDK/latest/frames.html#!AWS/SNS.html)
+* [AWS.SQS](/AWSJavaScriptSDK/latest/frames.html#!AWS/SQS.html)
+* [AWS.Kinesis](/AWSJavaScriptSDK/latest/frames.html#!AWS/Kinesis.html)
+* [AWS.CloudWatch](/AWSJavaScriptSDK/latest/frames.html#!AWS/CloudWatch.html)
+* [AWS.STS](/AWSJavaScriptSDK/latest/frames.html#!AWS/STS.html)
+
+<div class="clear"></div>
+
+It is possible to use the SDK with other services if [CORS](http://www.w3.org/TR/cors/)
+security checking is disabled in your environment. In this case, you can build
+your own custom version of the SDK. See the {file:browser-building.md Building the SDK}
+section of the guide for more information on how to create a custom build of
+the SDK.
+
+## Constructing a Service
+
+Each service can be constructed with runtime configuration data that is
+specific to that service object. The service-specific configuration data
+will be merged on top of global configuration, so there is no need to
+re-specify any global settings. For example, an DynamoDB object can be created
+for a specific region:
+
+```javascript
+var dynamodb = new AWS.DynamoDB({region: 'us-west-2'});
+```
+
+This object will continue to use the globally provided credentials.
+
+## Passing Parameters to a Service Operation
+
+When calling a method to a service, you should pass parameters in as
+option values, similar to the way configuration is passed.
+For example, to read an object for a given bucket and key in S3, you
+can pass the following parameters to the `getObject` method:
+
+```javascript
+s3.getObject({Bucket: 'bucketName', Key: 'keyName'});
+```
+
+Note that the full parameter documentation for each method is found
+in each service page in the complete API reference documentation.
+
+## Bound Parameters
+
+Parameters can be automatically passed to service operations by binding them
+directly when constructing the service object. To do this, pass the `params`
+parameter to your constructed service with the map of default parameter
+values like so:
+
+```javascript
+var s3bucket = new AWS.S3({ params: {Bucket: 'myBucket'} });
+```
+
+The `s3bucket` object will now represent an S3 service object bound to a bucket
+named 'myBucket'. Any operation that takes the `Bucket` parameter will now
+have it auto-filled with this value. This value can be overridden by passing
+a new value in the service operation. Additionally, operations that do not
+require a `Bucket` parameter will automatically ignore this bound parameter,
+so the `s3bucket` object can still be used to call `listBuckets`, for instance.

package/doc-src/guide/index.md

@@ -0,0 +1,41 @@
+# @title AWS SDK for JavaScript
+
+# AWS SDK for JavaScript
+
+<p class="subtitle">Available for browsers and mobile devices, or Node.js backends</p>
+
+## Developer Guide
+
+<p class="note">
+If you are upgrading from 1.x to 2.0 of the SDK, please see
+the {file:UPGRADING.md} notes for information on how to migrate existing code
+to work with the new major version.
+</p>
+
+The **AWS SDK for JavaScript** allows developers to build libraries or
+applications that make use of AWS services using a simple and easy-to-use
+API available both in the browser or inside of Node.js applications on the
+server.
+
+This guide will walk developers through many of the high level concepts
+that the SDK provides, as well as provide example code to get started with
+some services. For a more complete look at the classes and methods provided by
+the library, it is recommended to look at the SDK's
+[API reference documentation](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/frames.html).
+
+Depending on the platform you are developing for, the installation guide
+may be slightly different, but in both cases, usage of the SDK is the same.
+
+## Select a Platform
+
+<div class="buttons">
+{file:browser-intro.md JavaScript in the Browser}
+{file:node-intro.md JavaScript in Node.js}
+</div>
+<div class="clear"></div>
+
+If you are developing applications in the browser, please visit the
+{file:browser-intro.md AWS SDK for JavaScript in the Browser} section.
+
+If you are developing applications on the server side using Node.js, see the
+{file:node-intro.md AWS SDK for Node.js} section.