Add tests and javadoc for Message and ByteArray (googleapis#1000)

* Add tests and javadoc for Message and ByteArray

* Add final on static ByteArray methods back

gcloud-java-core/src/main/java/com/google/cloud/ByteArray.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 Google Inc. All Rights Reserved.
+ * Copyright 2016 Google Inc. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,8 +20,6 @@
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.protobuf.ByteString;
 
-import java.io.BufferedInputStream;
-import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.Serializable;
@@ -35,6 +33,7 @@
 public class ByteArray implements Iterable<Byte>, Serializable {
 
   private static final long serialVersionUID = -1908809133893782840L;
+
   private final ByteString byteString;
 
   protected ByteArray(ByteString byteString) {
@@ -75,91 +74,91 @@ public final boolean equals(Object obj) {
   }
 
   /**
-   * Returns the size of this blob.
+   * Returns the number of bytes in this {@code ByteArray}.
    */
   public final int length() {
     return byteString.size();
   }
 
   /**
-   * Returns a copy as byte array.
+   * Returns a copy of this {@code ByteArray} as an array of bytes.
    */
   public final byte[] toByteArray() {
     return byteString.toByteArray();
   }
 
   /**
-   * Returns the content as {@code UTF-8} string.
+   * Returns a copy of this {@code ByteArray} as an {@code UTF-8} string.
    */
   public final String toStringUtf8() {
     return byteString.toStringUtf8();
   }
 
   /**
-   * Returns a read-only {@link ByteBuffer} for this blob content.
+   * Returns the content of this {@code ByteArray} as a read-only {@link ByteBuffer}.
    */
   public final ByteBuffer asReadOnlyByteBuffer() {
     return byteString.asReadOnlyByteBuffer();
   }
 
   /**
-   * Returns an {@link InputStream} for this blob content.
+   * Returns an {@link InputStream} for this {@code ByteArray} content.
    */
   public final InputStream asInputStream() {
-    final ByteBuffer byteBuffer = asReadOnlyByteBuffer();
-    return new InputStream() {
-      @Override public int read() {
-        return !byteBuffer.hasRemaining() ? -1 : byteBuffer.get() & 0xFF;
-      }
-    };
+    return byteString.newInput();
   }
 
   protected ByteString byteString() {
     return byteString;
   }
 
   /**
-   * Copies bytes into a ByteBuffer.
+   * Copies the content of this {@code ByteArray} into an existing {@code ByteBuffer}.
    *
    * @throws java.nio.ReadOnlyBufferException if the target is read-only
-   * @throws java.nio.BufferOverflowException if the target's remaining() space is not large
-   *        enough to hold the data
+   * @throws java.nio.BufferOverflowException if the target's {@link ByteBuffer#remaining()} space
+   *     is not large enough to hold the data
    */
   public final void copyTo(ByteBuffer target) {
     byteString.copyTo(target);
   }
 
   /**
-   * Copies bytes into a buffer.
+   * Copies the content of this {@code ByteArray} into an array of bytes.
    *
-   * @throws IndexOutOfBoundsException if an offset or size is negative or too large
+   * @throws IndexOutOfBoundsException if the target is not large enough to hold the data
    */
   public final void copyTo(byte[] target) {
     byteString.copyTo(target, 0, 0, length());
   }
 
-  public static final ByteArray copyFrom(byte[] bytes) {
+  /**
+   * Creates a {@code ByteArray} object given an array of bytes. The bytes are copied.
+   */
+  public final static ByteArray copyFrom(byte[] bytes) {
     return new ByteArray(ByteString.copyFrom(bytes));
   }
 
   /**
-   * Copy the bytes using {@code UTF-8} decoding.
+   * Creates a {@code ByteArray} object given a string. The string is encoded in {@code UTF-8}. The
+   * bytes are copied.
    */
-  public static final ByteArray copyFrom(String string) {
+  public final static ByteArray copyFrom(String string) {
     return new ByteArray(ByteString.copyFrom(string, StandardCharsets.UTF_8));
   }
 
-  public static final ByteArray copyFrom(ByteBuffer bytes) {
+  /**
+   * Creates a {@code ByteArray} object given a {@link ByteBuffer}. The bytes are copied.
+   */
+  public final static ByteArray copyFrom(ByteBuffer bytes) {
     return new ByteArray(ByteString.copyFrom(bytes));
   }
 
-  public static final ByteArray copyFrom(InputStream input) throws IOException {
-    BufferedInputStream bufferedInput = new BufferedInputStream(input);
-    ByteArrayOutputStream bytes = new ByteArrayOutputStream();
-    int value;
-    while ((value = bufferedInput.read()) != -1) {
-      bytes.write(value);
-    }
-    return copyFrom(bytes.toByteArray());
+  /**
+   * Creates a {@code ByteArray} object given an {@link InputStream}. The stream is read into the
+   * created object.
+   */
+  public final static ByteArray copyFrom(InputStream input) throws IOException {
+    return new ByteArray(ByteString.readFrom(input));
   }
 }

gcloud-java-core/src/test/java/com/google/cloud/ByteArrayTest.java

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+
+import com.google.common.io.ByteStreams;
+import com.google.protobuf.ByteString;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+
+public class ByteArrayTest {
+
+  private static final String STRING_CONTENT = "Hello, ByteArray!";
+  private static final byte[] BYTES_CONTENT = STRING_CONTENT.getBytes(StandardCharsets.UTF_8);
+  private static final ByteBuffer BYTE_BUFFER_CONTENT = ByteBuffer.wrap(BYTES_CONTENT);
+  private static final InputStream STREAM_CONTENT = new ByteArrayInputStream(BYTES_CONTENT);
+  private static final ByteArray STRING_ARRAY = ByteArray.copyFrom(STRING_CONTENT);
+  private static final ByteArray BYTES_ARRAY = ByteArray.copyFrom(BYTES_CONTENT);
+  private static final ByteArray BYTE_BUFFER_ARRAY = ByteArray.copyFrom(BYTE_BUFFER_CONTENT);
+  private static final ByteArray ARRAY = new ByteArray(ByteString.copyFrom(BYTES_CONTENT));
+
+  private static ByteArray streamArray;
+
+  @BeforeClass
+  public static void beforeClass() throws IOException {
+    streamArray = ByteArray.copyFrom(STREAM_CONTENT);
+    BYTE_BUFFER_CONTENT.flip();
+  }
+
+  @Test
+  public void testCopyFromString() throws IOException {
+    assertEquals(STRING_CONTENT, STRING_ARRAY.toStringUtf8());
+    assertArrayEquals(BYTES_CONTENT, STRING_ARRAY.toByteArray());
+    assertEquals(BYTE_BUFFER_CONTENT.asReadOnlyBuffer(), STRING_ARRAY.asReadOnlyByteBuffer());
+    assertArrayEquals(BYTES_CONTENT, ByteStreams.toByteArray(STRING_ARRAY.asInputStream()));
+  }
+
+  @Test
+  public void testCopyFromByteArray() throws IOException {
+    assertEquals(STRING_CONTENT, BYTES_ARRAY.toStringUtf8());
+    assertArrayEquals(BYTES_CONTENT, BYTES_ARRAY.toByteArray());
+    assertEquals(BYTE_BUFFER_CONTENT.asReadOnlyBuffer(), BYTES_ARRAY.asReadOnlyByteBuffer());
+    assertArrayEquals(BYTES_CONTENT, ByteStreams.toByteArray(BYTES_ARRAY.asInputStream()));
+  }
+
+  @Test
+  public void testCopyFromByteBuffer() throws IOException {
+    assertEquals(STRING_CONTENT, BYTE_BUFFER_ARRAY.toStringUtf8());
+    assertArrayEquals(BYTES_CONTENT, BYTE_BUFFER_ARRAY.toByteArray());
+    assertEquals(BYTE_BUFFER_CONTENT.asReadOnlyBuffer(), BYTE_BUFFER_ARRAY.asReadOnlyByteBuffer());
+    assertArrayEquals(BYTES_CONTENT, ByteStreams.toByteArray(BYTE_BUFFER_ARRAY.asInputStream()));
+  }
+
+  @Test
+  public void testCopyFromStream() throws IOException {
+    assertEquals(STRING_CONTENT, streamArray.toStringUtf8());
+    assertArrayEquals(BYTES_CONTENT, streamArray.toByteArray());
+    assertEquals(BYTE_BUFFER_CONTENT.asReadOnlyBuffer(), streamArray.asReadOnlyByteBuffer());
+    assertArrayEquals(BYTES_CONTENT, ByteStreams.toByteArray(streamArray.asInputStream()));
+  }
+
+  @Test
+  public void testLength() {
+    assertEquals(BYTES_CONTENT.length, ARRAY.length());
+  }
+
+  @Test
+  public void testToStringUtf8() {
+    assertEquals(STRING_CONTENT, ARRAY.toStringUtf8());
+  }
+
+  @Test
+  public void testToByteArray() {
+    assertArrayEquals(BYTES_CONTENT, ARRAY.toByteArray());
+  }
+
+  @Test
+  public void testAsReadOnlyByteBuffer() {
+    assertEquals(BYTE_BUFFER_CONTENT.asReadOnlyBuffer(), ARRAY.asReadOnlyByteBuffer());
+  }
+
+  @Test
+  public void testAsInputStream() throws IOException {
+    assertArrayEquals(BYTES_CONTENT, ByteStreams.toByteArray(ARRAY.asInputStream()));
+  }
+
+  @Test
+  public void testHashCode() {
+    assertEquals(STRING_ARRAY.hashCode(), BYTES_ARRAY.hashCode());
+    assertEquals(BYTES_ARRAY.hashCode(), BYTE_BUFFER_ARRAY.hashCode());
+    assertEquals(BYTE_BUFFER_ARRAY.hashCode(), streamArray.hashCode());
+  }
+}