Optimize samples and documentation for retry policies.

ChangeLog.md

@@ -3,6 +3,9 @@ be taken. This is a GA release and the changes described below indicate the chan
 
 2017.09 Version 2.5.0
 
+ALL 
+* Optimized samples and documentation for retry policies.
+
 FILE
 * Added support for File metrics.
 

README.md

@@ -96,7 +96,7 @@ var task = {
   PartitionKey: entGen.String('hometasks'),
   RowKey: entGen.String('1'),
   description: entGen.String('take out the trash'),
-  dueDate: entGen.DateTime(new Date(Date.UTC(2015, 6, 20))),
+  dueDate: entGen.DateTime(new Date(Date.UTC(2015, 6, 20)))
 };
 ```
 
@@ -190,7 +190,7 @@ var sharedAccessPolicy = {
     Permissions: azure.BlobUtilities.SharedAccessPermissions.READ,
     Start: startDate,
     Expiry: expiryDate
-  },
+  }
 };
 
 var token = blobService.generateSharedAccessSignature(containerName, blobName, sharedAccessPolicy);
@@ -432,6 +432,14 @@ blobService.getServiceProperties(function(error, result, response) {
 });
 ```
 
+### Retry Policies
+
+By default, no retry will be performed with service instances newly created by Azure storage client library for Node.js.
+Two pre-written retry polices [ExponentialRetryPolicyFilter](http://azure.github.io/azure-storage-node/ExponentialRetryPolicyFilter.html) and [LinearRetryPolicyFilter](http://azure.github.io/azure-storage-node/LinearRetryPolicyFilter.html) are available with modifiable settings, and can be used through associating filter.
+Any custom retry logic may be used by customizing RetryPolicyFilter instance.
+
+For how to use pre-writtern retry policies and how to define customized retry policy, please refer to **retrypolicysample** in samples directory. 
+
 ## Code Samples
 
 How-Tos focused around accomplishing specific tasks are available on the [Microsoft Azure Node.js Developer Center](http://azure.microsoft.com/en-us/develop/nodejs/).

examples/samples/retrypolicysample.js

@@ -15,11 +15,13 @@
 // 
 
 /**
-* Demonstrates how to define a customized retry policy.
-* 
-* In this sample, we define a customized retry policy which retries on the "The specified container is being deleted"
-* exception besides the server exceptions.
-* 
+* Demonstrates how to use pre-written retry policies and how to define a customized retry policy.
+*
+* In the sample for pre-written retry policies, we simply show how to use pre-written retry policies.
+*
+* In the sample for customized retry policy, we define a customized retry policy,
+* which retries on the "The specified container is being deleted" exception besides the server exceptions.
+*
 * Note that only in the cloud(not the storage emulator), "The specified container is being deleted" exceptions will be
 * sent if users immediately recreate a container after delete it.
 */
@@ -43,8 +45,48 @@ var container = 'customretrypolicysample';
 
 var blobService;
 
-function setRetryPolicy() {
-  console.log('Starting continuationSample.');
+/**
+ * Demonstrate how to use pre-written retry policies.
+ * By default, no retry will be performed with service instances newly created.
+ * Several pre-written retry policies are available with modifiable settings,
+ * and can be used through associating filter.
+ */
+function setRetries() {
+  console.log('Starting Sample 1 - setRetries.');
+
+  // By default, no retry will be performed with all kinds of services created
+  // by Azure storage client library for Node.js.
+  var blobServiceWithoutRetry = azure.createBlobService();
+  console.log('BlobService instance created, no retry will be performed by default.');
+
+  // There are two pre-written retry policies: ExponentialRetryPolicyFilter
+  // and LinearRetryPolicyFilter can be used with modifiable settings.
+  // Use an exponential retry with customized settings.
+  var fileServiceWithExponentialRetry = azure.createFileService().withFilter(
+    new azure.ExponentialRetryPolicyFilter(
+      3, // retryCount is set to 3 times.
+      4000, // retryInterval is set to 4 seconds.
+      3000, // minRetryInterval is set to 3 seconds.
+      120000 // maxRetryInterval is set to 120 seconds.
+    ));
+  console.log('FileService instance created and associated with ExponentialRetryPolicyFilter.');
+  console.log(' Retries will be performed with exponential back-off.');
+
+  // Use a default linear retry policy.
+  var tableServiceWithLinearRetry = azure.createTableService().withFilter(
+    new azure.LinearRetryPolicyFilter()); // By default, retryCount is set to 3 times and retryInterval is set to 30 seconds.
+  console.log('TableService instance created and associated with LinearRetryPolicyFilter,');
+  console.log(' Retries will be performed with linear back-off.');
+
+  console.log('Ending Sample 1 - setRetries.');
+}
+
+/**
+ * Demonstrate how to use custom retry policy.
+ * Any custom retry logic may be used by simply creating and setting RetryPolicyFilter instance.
+ */
+function setCustomRetryPolicy() {
+  console.log('Starting Sample 2 - setCustomRetryPolicy.');
 
   // Step 1 : Set the retry policy to customized retry policy which will
   // not retry on any failing status code other than the excepted one.
@@ -52,20 +94,20 @@ function setRetryPolicy() {
   retryOnContainerBeingDeleted.retryCount = 5;
   retryOnContainerBeingDeleted.retryInterval = 5000;
 
-  retryOnContainerBeingDeleted.shouldRetry = function(statusCode, retryData) {
+  retryOnContainerBeingDeleted.shouldRetry = function (statusCode, retryData) {
     console.log(' Made the request at ' + new Date().toUTCString() + ', received StatusCode: ' + statusCode);
 
-    retryInfo = {};
+    var retryInfo = {};
 
     // retries on any bad status code other than 409 
-    if (statusCode >= 300 && statusCode != 409 && statusCode != 500) {
+    if (statusCode >= 300 && statusCode !== 409 && statusCode !== 500) {
       retryInfo.retryable = false;
     } else {
       var currentCount = (retryData && retryData.retryCount) ? retryData.retryCount : 0;
 
-      var retryInfo = {
+      retryInfo = {
         retryInterval: this.retryInterval + 2000 * currentCount,
-        retryable: currentCount < this.retryCount,
+        retryable: currentCount < this.retryCount
       };
     }
 
@@ -82,7 +124,7 @@ function setRetryPolicy() {
   };
 
   blobService.setProxy(proxy);*/
-  
+
 
   // Step 2: Create the container
   createContainer(function () {
@@ -95,10 +137,10 @@ function setRetryPolicy() {
 
         // Step 5: Lease the container again, retrying until it succeeds
         leaseContainer(function () {
-          
+
           // Step 6: Delete the container
           deleteContainer(function () {
-            console.log('Ending continuationSample.');
+            console.log('Ending Sample 2 - setCustomRetryPolicy.');
           });
         });
       });
@@ -106,7 +148,7 @@ function setRetryPolicy() {
   });
 }
 
-function createContainer (callback) {
+function createContainer(callback) {
   console.log('Entering createContainer.');
 
   // Create the container.
@@ -122,15 +164,15 @@ function createContainer (callback) {
   });
 }
 
-function fetchAttributesContainer (callback) {
+function fetchAttributesContainer(callback) {
   console.log('Entering fetchAttributesContainer.');
-    
+
   var options = {
     locationMode: LocationMode.SECONDARY_THEN_PRIMARY
   };
 
   // Get the properties of the container.
-  blobService.getContainerProperties(container, options, function(error) {
+  blobService.getContainerProperties(container, options, function (error) {
     if (error) {
       console.log(error);
     } else {
@@ -155,7 +197,7 @@ function leaseContainer(callback) {
   });
 }
 
-function deleteContainer (callback) {
+function deleteContainer(callback) {
   console.log('Entering deleteContainer.');
 
   // Break the lease.
@@ -178,4 +220,11 @@ function deleteContainer (callback) {
   });
 }
 
-setRetryPolicy();
+function runAllSamples() {
+  console.log("Starting retrypolicySample.");
+  setRetries();
+  setCustomRetryPolicy();
+  console.log("Ending retrypolicySample.");
+}
+
+runAllSamples();