Better javadoc, check contentType and metadata in integrationt tests

gcloud-java-storage/src/main/java/com/google/gcloud/storage/CopyWriter.java

@@ -32,10 +32,11 @@
 import java.util.concurrent.Callable;
 
 /**
- * Google Storage blob copy writer. This class holds the result of a copy request.
- * If source and destination blobs do not share the same location or storage class more than one
- * RPC request is needed to copy the blob otherwise one or more {@link #copyChunk()} calls are
- * necessary to complete the copy.
+ * Google Storage blob copy writer. This class holds the result of a copy request. If source and
+ * destination blobs share the same location and storage class the copy is completed in one RPC call
+ * otherwise one or more {@link #copyChunk} calls are necessary to complete the copy. In addition,
+ * {@link CopyWriter#result()} can be used to automatically complete the copy and return information
+ * on the newly created blob.
  *
  * @see <a href="https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite">Rewrite</a>
  */
@@ -52,20 +53,26 @@ public class CopyWriter implements Restorable<CopyWriter> {
   }
 
   /**
-   * Returns the updated information for the just written blob. This method might block and issue
-   * several RPC requests to complete blob copy.
+   * Returns the updated information for the written blob. Calling this method when {@code isDone()}
+   * is {@code false} will block until all pending chunks are copied.
+   * <p>
+   * This method has the same effect of doing:
+   * <pre>    {@code while (!copyWriter.isDone()) {
+   *        copyWriter.copyChunk();
+   *    }}
+   * </pre>
    *
    * @throws StorageException upon failure
    */
   public BlobInfo result() {
-    while(!isDone()) {
+    while (!isDone()) {
       copyChunk();
     }
     return BlobInfo.fromPb(rewriteResponse.result);
   }
 
   /**
-   * Size of the blob being copied.
+   * Returns the size of the blob being copied.
    */
   public long blobSize() {
     return rewriteResponse.blobSize;

gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java

@@ -839,6 +839,14 @@ public static Builder builder() {
    * Example usage of copy:
    * <pre>    {@code BlobInfo blob = service.copy(copyRequest).result();}
    * </pre>
+   * To explicitly issue chunk copy requests use {@link CopyWriter#copyChunk()} instead:
+   * <pre>    {@code CopyWriter copyWriter = service.copy(copyRequest);
+   *    while (!copyWriter.isDone()) {
+   *        copyWriter.copyChunk();
+   *    }
+   *    BlobInfo blob = copyWriter.result();
+   * }
+   * </pre>
    *
    * @return a {@link CopyWriter} object that can be used to get information on the newly created
    *     blob or to complete the copy if more than one RPC request is needed

gcloud-java-storage/src/test/java/com/google/gcloud/storage/ITStorageTest.java

@@ -318,12 +318,20 @@ public void testComposeBlobFail() {
   public void testCopyBlob() {
     String sourceBlobName = "test-copy-blob-source";
     BlobId source = BlobId.of(BUCKET, sourceBlobName);
-    assertNotNull(storage.create(BlobInfo.builder(source).build(), BLOB_BYTE_CONTENT));
+    ImmutableMap<String, String> metadata = ImmutableMap.of("k", "v");
+    BlobInfo blob = BlobInfo.builder(source)
+        .contentType(CONTENT_TYPE)
+        .metadata(metadata)
+        .build();
+    assertNotNull(storage.create(blob, BLOB_BYTE_CONTENT));
     String targetBlobName = "test-copy-blob-target";
-    BlobInfo target = BlobInfo.builder(BUCKET, targetBlobName).contentType(CONTENT_TYPE).build();
+    BlobInfo target = BlobInfo.builder(BUCKET, targetBlobName).build();
     Storage.CopyRequest req = Storage.CopyRequest.of(source, target);
     CopyWriter copyWriter = storage.copy(req);
-    assertEquals(copyWriter.result(), storage.get(BUCKET, targetBlobName));
+    assertEquals(BUCKET, copyWriter.result().bucket());
+    assertEquals(targetBlobName, copyWriter.result().name());
+    assertEquals(CONTENT_TYPE, copyWriter.result().contentType());
+    assertEquals(metadata, copyWriter.result().metadata());
     assertTrue(copyWriter.isDone());
     assertTrue(storage.delete(BUCKET, sourceBlobName));
     assertTrue(storage.delete(BUCKET, targetBlobName));
@@ -334,14 +342,18 @@ public void testCopyBlobUpdateMetadata() {
     String sourceBlobName = "test-copy-blob-update-metadata-source";
     BlobId source = BlobId.of(BUCKET, sourceBlobName);
     assertNotNull(storage.create(BlobInfo.builder(source).build(), BLOB_BYTE_CONTENT));
-    String targetBlobName = "test-copy-blob-target";
+    String targetBlobName = "test-copy-blob-update-metadata-target";
+    ImmutableMap<String, String> metadata = ImmutableMap.of("k", "v");
     BlobInfo target = BlobInfo.builder(BUCKET, targetBlobName)
         .contentType(CONTENT_TYPE)
-        .metadata(ImmutableMap.of("k", "v"))
+        .metadata(metadata)
         .build();
     Storage.CopyRequest req = Storage.CopyRequest.of(source, target);
     CopyWriter copyWriter = storage.copy(req);
-    assertEquals(copyWriter.result(), storage.get(BUCKET, targetBlobName));
+    assertEquals(BUCKET, copyWriter.result().bucket());
+    assertEquals(targetBlobName, copyWriter.result().name());
+    assertEquals(CONTENT_TYPE, copyWriter.result().contentType());
+    assertEquals(metadata, copyWriter.result().metadata());
     assertTrue(copyWriter.isDone());
     assertTrue(storage.delete(BUCKET, sourceBlobName));
     assertTrue(storage.delete(BUCKET, targetBlobName));