JAVA-2336: Expose byte utility methods in the public API

olim7t · olim7t · commit b8474df3699d · 2019-07-26T09:49:11.000-07:00
diff --git a/changelog/README.md b/changelog/README.md
@@ -4,6 +4,7 @@
 
 ### 4.2.0 (in progress)
 
+- [improvement] JAVA-2336: Expose byte utility methods in the public API 
 - [improvement] JAVA-2338: Revisit toString() for data container types
 - [bug] JAVA-2367: Fix column names in EntityHelper.updateByPrimaryKey
 - [bug] JAVA-2358: Fix list of reserved CQL keywords
diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/data/ByteUtils.java b/core/src/main/java/com/datastax/oss/driver/api/core/data/ByteUtils.java
@@ -0,0 +1,89 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * 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.datastax.oss.driver.api.core.data;
+
+import com.datastax.oss.protocol.internal.util.Bytes;
+import java.nio.ByteBuffer;
+
+/**
+ * A set of static utility methods to work with byte buffers (associated with CQL type {@code
+ * blob}).
+ */
+public class ByteUtils {
+
+  // Implementation note: this is just a gateway to the internal `Bytes` class in native-protocol.
+  // The difference is that this one is part of the public API.
+
+  /**
+   * Converts a blob to its CQL hex string representation.
+   *
+   * <p>A CQL blob string representation consists of the hexadecimal representation of the blob
+   * bytes prefixed by "0x".
+   *
+   * @param bytes the blob/bytes to convert to a string.
+   * @return the CQL string representation of {@code bytes}. If {@code bytes} is {@code null}, this
+   *     method returns {@code null}.
+   */
+  public static String toHexString(ByteBuffer bytes) {
+    return Bytes.toHexString(bytes);
+  }
+
+  /**
+   * Converts a blob to its CQL hex string representation.
+   *
+   * <p>A CQL blob string representation consists of the hexadecimal representation of the blob
+   * bytes prefixed by "0x".
+   *
+   * @param byteArray the blob/bytes array to convert to a string.
+   * @return the CQL string representation of {@code bytes}. If {@code bytes} is {@code null}, this
+   *     method returns {@code null}.
+   */
+  public static String toHexString(byte[] byteArray) {
+    return Bytes.toHexString(byteArray);
+  }
+
+  /**
+   * Parses a hex string representing a CQL blob.
+   *
+   * <p>The input should be a valid representation of a CQL blob, i.e. it must start by "0x"
+   * followed by the hexadecimal representation of the blob bytes.
+   *
+   * @param str the CQL blob string representation to parse.
+   * @return the bytes corresponding to {@code str}. If {@code str} is {@code null}, this method
+   *     returns {@code null}.
+   * @throws IllegalArgumentException if {@code str} is not a valid CQL blob string.
+   */
+  public static ByteBuffer fromHexString(String str) {
+    return Bytes.fromHexString(str);
+  }
+
+  /**
+   * Extracts the content of the provided {@code ByteBuffer} as a byte array.
+   *
+   * <p>This method works with any type of {@code ByteBuffer} (direct and non-direct ones), but when
+   * the buffer is backed by an array, it will try to avoid copy when possible. As a consequence,
+   * changes to the returned byte array may or may not reflect into the initial buffer.
+   *
+   * @param bytes the buffer whose contents to extract.
+   * @return a byte array with the contents of {@code bytes}. That array may be the array backing
+   *     {@code bytes} if this can avoid a copy.
+   */
+  public static byte[] getArray(ByteBuffer bytes) {
+    return Bytes.getArray(bytes);
+  }
+
+  private ByteUtils() {}
+}
diff --git a/examples/src/main/java/com/datastax/oss/driver/examples/datatypes/Blobs.java b/examples/src/main/java/com/datastax/oss/driver/examples/datatypes/Blobs.java
@@ -19,7 +19,7 @@
 import com.datastax.oss.driver.api.core.cql.BoundStatement;
 import com.datastax.oss.driver.api.core.cql.PreparedStatement;
 import com.datastax.oss.driver.api.core.cql.Row;
-import com.datastax.oss.protocol.internal.util.Bytes;
+import com.datastax.oss.driver.api.core.data.ByteUtils;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
@@ -143,7 +143,7 @@ private static void retrieveSimpleColumn(CqlSession session) {
     // - even then, the backing array might be larger than the buffer's contents
     //
     // The driver provides a utility method that handles those details for you:
-    byte[] array = Bytes.getArray(buffer);
+    byte[] array = ByteUtils.getArray(buffer);
     assert array.length == 16;
     for (byte b : array) {
       assert b == (byte) 0xFF;
@@ -175,7 +175,7 @@ private static void insertConcurrent(CqlSession session) {
         session.prepare("INSERT INTO examples.blobs (k, b) VALUES (1, :b)");
 
     // This is another convenient utility provided by the driver. It's useful for tests.
-    ByteBuffer buffer = Bytes.fromHexString("0xffffff");
+    ByteBuffer buffer = ByteUtils.fromHexString("0xffffff");
 
     // When you pass a byte buffer to a bound statement, it creates a shallow copy internally with
     // the buffer.duplicate() method.
@@ -188,7 +188,7 @@ private static void insertConcurrent(CqlSession session) {
     session.execute(boundStatement);
     Row row = session.execute("SELECT b FROM examples.blobs WHERE k = 1").one();
     assert row != null;
-    assert Objects.equals(Bytes.toHexString(row.getByteBuffer("b")), "0xffffff");
+    assert Objects.equals(ByteUtils.toHexString(row.getByteBuffer("b")), "0xffffff");
 
     buffer.flip();
 
@@ -199,7 +199,7 @@ private static void insertConcurrent(CqlSession session) {
     session.execute(boundStatement);
     row = session.execute("SELECT b FROM examples.blobs WHERE k = 1").one();
     assert row != null;
-    assert Objects.equals(Bytes.toHexString(row.getByteBuffer("b")), "0xaaffff");
+    assert Objects.equals(ByteUtils.toHexString(row.getByteBuffer("b")), "0xaaffff");
 
     // This will also happen if you use the async API, e.g. create the bound statement, call
     // executeAsync() on it and reuse the buffer immediately.
