Adds note on environments to docs

README.md

@@ -65,7 +65,7 @@ public class GettingStarted {
         // Converts /tmp/example.docx to /tmp/example.pdf
         client
             .convert(new File("/tmp/example.docx"), "pdf") // uploads and converts your file
-            .store(new File("/tmp/example.zip")) // downloads the converted file
+            .store(new File("/tmp/")) // downloads the converted file
             .deleteAllFiles(); // removes your files (example.docx and example.pdf) from Zamzar's servers
     }
 }
@@ -74,6 +74,27 @@ public class GettingStarted {
 See the [examples](https://github.com/zamzar/zamzar-java/tree/main/src/test/java/com/zamzar/api/examples) to learn more
 about how to use the Zamzar Java library.
 
+### Using the sandbox environment
+
+Whilst developing your application, you can use the Zamzar sandbox environment to test your code without consuming
+production credits:
+
+```java
+import com.zamzar.api.ZamzarClient;
+import com.zamzar.api.ZamzarEnvironment;
+
+ZamzarClient client = new ZamzarClient("YOUR_API_KEY_GOES_HERE", ZamzarEnvironment.SANDBOX);
+```
+
+The Zamzar Java library uses the production environment by default, but you can also specify it explicitly:
+
+```java
+import com.zamzar.api.ZamzarClient;
+import com.zamzar.api.ZamzarEnvironment;
+
+ZamzarClient client = new ZamzarClient("YOUR_API_KEY_GOES_HERE", ZamzarEnvironment.PRODUCTION);
+```
+
 ### Logging
 
 By default, the Zamzar Java library does not log HTTP requests and responses. To enable logging, configure a

src/main/java/com/zamzar/api/ZamzarClient.java

@@ -22,10 +22,9 @@
  * <pre>
  *     ZamzarClient zamzar = new ZamzarClient("YOUR_API_KEY_GOES_HERE");
  *
- *     client
+ *     zamzar
  *      .convert(new File("path/to/source.pdf"), "jpg")
- *      .awaitOrThrow()
- *      .download(new File("path/to/destination.jpg"));
+ *      .store(new File("path/to/destination.jpg"));
  * </pre>
  *
  * @see <a href="https://developers.zamzar.com/docs">Zamzar API Documentation</a>
@@ -157,17 +156,15 @@ public ZamzarClient(String apiKey, URI baseUrl, OkHttpClient transport) {
     }
 
     /**
-     * Converts a local file to the specified format. Call {@link JobManager#awaitOrThrow()} on the result
-     * to wait for the conversion to complete.
+     * Converts a local file to the specified format, blocking until the conversion is complete.
      * <p>
      * Example usage:
      * <pre>
      *     ZamzarClient zamzar = new ZamzarClient("YOUR_API_KEY_GOES_HERE");
      *
      *     zamzar
      *       .convert(new File("path/to/source.pdf"), "jpg")
-     *       .awaitOrThrow()
-     *       .download(new File("path/to/destination.jpg"))
+     *       .store(new File("path/to/destination.jpg"))
      *       .deleteAllFiles();
      * </pre>
      */
@@ -176,8 +173,8 @@ public JobManager convert(File source, String targetFormat) throws ApiException
     }
 
     /**
-     * Converts a local file to the specified format using a custom job builder. Call {@link JobManager#awaitOrThrow()}
-     * on the result to wait for the conversion to complete.
+     * Converts a local file to the specified format using a custom job builder, blocking until the conversion is
+     * complete.
      * <p>
      * Example usage:
      * <pre>
@@ -189,7 +186,6 @@ public JobManager convert(File source, String targetFormat) throws ApiException
      *         "jpg",
      *         builder -> builder.exportingTo("s3://my-bucket/path/to/destination.jpg")
      *       )
-     *       .awaitOrThrow()
      *       .deleteAllFiles();
      * </pre>
      */
@@ -198,17 +194,15 @@ public JobManager convert(File source, String targetFormat, JobBuilder.Modifier
     }
 
     /**
-     * Converts a file already present on Zamzar's API servers to the specified format. Call {@link JobManager#awaitOrThrow()}
-     * on the result to wait for the conversion to complete.
+     * Converts a file already present on Zamzar's API servers to the specified format.
      * <p>
      * Example usage:
      * <pre>
      *     ZamzarClient zamzar = new ZamzarClient("YOUR_API_KEY_GOES_HERE");
      *
      *     zamzar
      *       .convert(123, "jpg")
-     *       .awaitOrThrow()
-     *       .download(new File("path/to/destination.jpg"))
+     *       .store(new File("path/to/destination.jpg"))
      *       .deleteTargetFiles();
      * </pre>
      */
@@ -218,7 +212,6 @@ public JobManager convert(Integer sourceId, String targetFormat) throws ApiExcep
 
     /**
      * Converts a file already present on Zamzar's API servers to the specified format using a custom job builder.
-     * Call {@link JobManager#awaitOrThrow()} on the result to wait for the conversion to complete.
      * <p>
      * Example usage:
      * <pre>
@@ -230,7 +223,6 @@ public JobManager convert(Integer sourceId, String targetFormat) throws ApiExcep
      *         "jpg",
      *         builder -> builder.exportingTo("s3://my-bucket/path/to/destination.jpg")
      *       )
-     *       .awaitOrThrow()
      *       .deleteTargetFiles();
      * </pre>
      */
@@ -239,17 +231,15 @@ public JobManager convert(Integer sourceId, String targetFormat, JobBuilder.Modi
     }
 
     /**
-     * Converts a file at the given URL to the specified format. Call {@link JobManager#awaitOrThrow()} on the result
-     * to wait for the conversion to complete.
+     * Converts a file at the given URL to the specified format.
      * <p>
      * Example usage:
      * <pre>
      *     ZamzarClient zamzar = new ZamzarClient("YOUR_API_KEY_GOES_HERE");
      *
      *     zamzar
      *       .convert(new URL("https://example.com/source.pdf"), "jpg")
-     *       .awaitOrThrow()
-     *       .download(new File("path/to/destination.jpg"))
+     *       .store(new File("path/to/destination.jpg"))
      *       .deleteAllFiles();
      * </pre>
      */
@@ -258,8 +248,7 @@ public JobManager convert(URI source, String targetFormat) throws ApiException {
     }
 
     /**
-     * Converts a file at the given URL to the specified format using a custom job builder. Call {@link JobManager#awaitOrThrow()}
-     * on the result to wait for the conversion to complete.
+     * Converts a file at the given URL to the specified format using a custom job builder.
      * <p>
      * Example usage:
      * <pre>
@@ -271,7 +260,6 @@ public JobManager convert(URI source, String targetFormat) throws ApiException {
      *         "jpg",
      *         builder -> builder.exportingTo("s3://my-bucket/path/to/destination.jpg")
      *       )
-     *       .awaitOrThrow()
      *       .deleteAllFiles();
      * </pre>
      */

src/test/java/com/zamzar/api/examples/GettingStarted.java

@@ -13,7 +13,7 @@ public static void main(String[] args) throws ApiException {
         // Converts /tmp/example.docx to /tmp/example.pdf
         zamzar
             .convert(new File("/tmp/example.docx"), "pdf") // uploads and converts your file
-            .store(new File("/tmp/example.zip")) // downloads the converted file
+            .store(new File("/tmp/")) // downloads the converted file
             .deleteAllFiles(); // removes your files (example.docx and example.pdf) from Zamzar's servers
     }
 }