update docs

Author: ryber

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 3.6.00 (pending)
+* issue #336 Add ProgressMonitor for file downloads.
+
 ## 3.5.00
 * Re-package the object mapper sub-modules to work with Java 11 per issue #324.
 * Update Jackson to 2.10.2

docs/index.md

@@ -394,6 +394,17 @@ File result = Unirest.get("http://some.file.location/file.zip")
                 .getBody();
 ```
 
+### Download Progress Monitoring
+If you are uploading large files you might want to provide some time of progress bar to a user. You can monitor this progress by providing a ProgresMonitor.
+
+```java
+          Unirest.get("http://httpbin.org")
+                .downLoadMonitor((b, fileName, bytesWritten, totalBytes) -> {
+                    updateProgressBarWithBytesLeft(totalBytes - bytesWritten);
+                })
+                .asFile("/disk/location/file.zip");
+```
+
 ## JSON responses
 Unirest offers a lightweight JSON response type when you don't need a full Object Mapper.
 

unirest/src/main/java/kong/unirest/ProgressMonitor.java

@@ -27,21 +27,24 @@
 
 /**
  * A ProgressMonitor is a functional interface which can be passed to unirest for the purposes of
- * monitoring file uploads. A common use case is for drawing upload progress bars.
- * If the upload contains multiple files each one is called individually and the file name is provided.
+ * monitoring file uploads and downloads. A common use case is for drawing progress bars.
+ *
+ * If an upload contains multiple files each one is called individually and the file name is provided.
  *
  * note that you will not receive a total for ALL files together at once.
- * If you wanted this you could keep track of the total bytes of files you planned to upload and then
+ * If you wanted this you can keep track of the total bytes of files you planned to upload and then
  * have your ProgressMonitor aggregate the results.
  */
 @FunctionalInterface
 public interface ProgressMonitor {
     /**
      * Accept stats about the current file upload chunk for a file.
-     * @param field the field name
+     * @param field the field name, or 'body' on file downloads
      * @param fileName the name of the file in question if available (InputStreams and byte arrays may not have file names)
-     * @param bytesWritten the number of bytes that have been uploaded so far
-     * @param totalBytes the total bytes that will be uploaded. Note this this may be an estimate if an InputStream was used
+     * @param bytesWritten the number of bytes that have been uploaded or downloaded so far
+     * @param totalBytes the total bytes that will be uploaded or downloaded.
+     *                    On downloads this depends on the Content-Length header be returned
+     *                    On uploads this this may be an estimate if an InputStream was used
      * */
     void accept(String field, String fileName, Long bytesWritten, Long totalBytes);
 }