Documentation for retrying data providers

Closes #63

src/main/asciidoc/docs/parameters.adoc

@@ -254,6 +254,92 @@ Each of the parallel data providers running from an XML file runs with a thread
 
 If you want to run a few specific data providers in a different thread pool, you need to run them from a different XML file.
 
+==== Retries and data providers
+
+TestNG allows you to retry a data provider incase it has encountered any issues when calling it the first time.
+
+This is similar to how regular test methods can be retried as explained in xref:_rerunning_failed_tests[this section].
+
+To be able to retry a data provider, the following needs to be done.
+
+* First we would need to implement the interface `org.testng.IRetryDataProvider`.
+* Next you would need to tie this implementation to the data provider annotation using the attribute `retryUsing` of the `@DataProvider` annotation.
+* With that we can now retry a failed ata provider.
+
+Here's a sample retry implementation:
+
+[source, java]
+
+----
+import org.testng.IDataProviderMethod;
+import org.testng.IRetryDataProvider;
+import java.util.concurrent.atomic.AtomicInteger;
+public class RetryDataProvider implements IRetryDataProvider {
+
+    private final AtomicInteger counter = new AtomicInteger(1);
+
+    @Override
+    public boolean retry(IDataProviderMethod dataProvider) {
+        boolean status = counter.getAndIncrement() <= 2;
+        String clazz = dataProvider.getMethod().getDeclaringClass().getName();
+        String dataProviderMethodName = dataProvider.getMethod().getName();
+        String methodName = clazz + "." + dataProviderMethodName + "()";
+        System.err.println("Retry the data provider method " + methodName + " ? " + status);
+        return status;
+    }
+}
+----
+
+Here's how a test class that consumes this retry mechanism can look like:
+
+[source, java]
+
+----
+import org.testng.annotations.DataProvider;
+import org.testng.annotations.Test;
+
+public class RetriableDataProviderSample {
+
+    private boolean throwException = true;
+
+    @Test(dataProvider = "test-data")
+    public void sampleTestMethod(int input) {
+        System.err.println("Input value = " + input);
+    }
+
+    @DataProvider(retryUsing = RetryDataProvider.class, name = "test-data")
+    public Object[][] testDataSupplier() {
+        if (throwException) {
+            throwException = false;
+            System.err.println("Simulating a problem when invoking the data provider");
+            throw new IllegalStateException("Simulating a failure in data provider");
+        }
+        return new Object[][]{
+                {1}, {2}
+        };
+    }
+}
+----
+
+And when you run this sample, the output would look something like below:
+
+[source, bash]
+
+----
+SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
+SLF4J: Defaulting to no-operation (NOP) logger implementation
+SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
+Simulating a problem when invoking the data provider
+Retry the data provider method org.testng.demo.RetriableDataProviderSample.testDataSupplier() ? true
+Input value = 1
+Input value = 2
+
+===============================================
+Default Suite
+Total tests run: 2, Passes: 2, Failures: 0, Skips: 0
+===============================================
+----
+
 ==== Controlling ThreadPool Usage
 
 Starting from TestNG `7.9.0`, there are some additional ways in which the thread-pools that run the parallel tests can be controlled. For these new features to be consumed, update your suite file to use the `testng-1.1.dtd` (as seen below) so that your IDE can provide you with autocompletion: