[tinkerpop] branch master updated: Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR

[jo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jorgebg pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/master by this push:
     new 6538c9e  Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR
6538c9e is described below

commit 6538c9e15e183decf55e30b73cfff13ded0d2dfc
Author: Jorge Bay Gondra <jo...@gmail.com>
AuthorDate: Wed May 8 11:45:41 2019 +0200

    Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR
---
 .../driver/ser/binary/GraphBinaryReader.java       | 30 ++++++++++++++++++++++
 .../driver/ser/binary/GraphBinaryWriter.java       | 17 ++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java
index ee012fe..e88c752 100644
--- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java
+++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java
@@ -21,6 +21,30 @@ package org.apache.tinkerpop.gremlin.driver.ser.binary;
 import io.netty.buffer.ByteBuf;
 import org.apache.tinkerpop.gremlin.driver.ser.SerializationException;
 
+/**
+ * Reads a value from a buffer using the {@link TypeSerializer} instances configured in the
+ * {@link TypeSerializerRegistry}.
+ *
+ * <p>
+ *     This class exposes two different methods to read a value from a buffer: {@link GraphBinaryReader#read(ByteBuf)}
+ *     and {@link GraphBinaryReader#readValue(ByteBuf, Class, boolean)}:
+ *     <ul>
+ *         <li>{@code read()} method expects a value in fully-qualified format, composed of
+ *         <code>{type_code}{type_info}{value_flag}{value}</code>.</li>
+ *         <li>{@code readValue()} method expects a <code>{value_flag}{value}</code> when a value is nullable and
+ *         only <code>{value}</code> when a value is not nullable.
+ *         </li>
+ *     </ul>
+ * </p>
+ *
+ * <p>
+ *     The {@link GraphBinaryReader} should be used to read a nested known type from a {@link TypeSerializer}.
+ *     For example, if a POINT type is composed by two doubles representing the position in the x and y axes, a
+ *     {@link TypeSerializer} for POINT type should use the provided {@link GraphBinaryReader} instance to read those
+ *     two double values. As x and y values are expected to be provided as non-nullable doubles, the method
+ *     {@code readValue()} should be used: {@code readValue(buffer, Double.class, false)}
+ * </p>
+ */
 public class GraphBinaryReader {
     private final TypeSerializerRegistry registry;
 
@@ -34,6 +58,12 @@ public class GraphBinaryReader {
 
     /**
      * Reads a value for an specific type.
+     *
+     * <p>When the value is nullable, the reader expects the <code>{value_flag}{value}</code> to be contained in the
+     * buffer.</p>
+     *
+     * <p>When the value is not nullable, the reader expects only the <code>{value}</code> to be contained in the
+     * buffer.</p>
      */
     public <T> T readValue(final ByteBuf buffer, final Class<T> type, final boolean nullable) throws SerializationException {
         if (buffer == null) {
diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java
index 68ccc7a..ac22e05 100644
--- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java
+++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java
@@ -24,6 +24,23 @@ import org.apache.tinkerpop.gremlin.driver.ser.SerializationException;
 import org.apache.tinkerpop.gremlin.driver.ser.binary.types.CustomTypeSerializer;
 import org.apache.tinkerpop.gremlin.driver.ser.binary.types.TransformSerializer;
 
+/**
+ * Writes a value to a buffer using the {@link TypeSerializer} instances configured in the
+ * {@link TypeSerializerRegistry}.
+ *
+ * <p>
+ *     This class exposes two different methods to write a value to a buffer:
+ *     {@link GraphBinaryWriter#write(Object, ByteBuf)} and
+ *     {@link GraphBinaryWriter#writeValue(Object, ByteBuf, boolean)}:
+ *     <ul>
+ *         <li>{@code write()} method writes the binary representation of the
+ *         <code>{type_code}{type_info}{value_flag}{value}</code> components.</li>
+ *         <li>{@code writeValue()} method writes the <code>{value_flag}{value}</code> when a value is nullable and
+ *         only <code>{value}</code> when a value is not nullable.
+ *         </li>
+ *     </ul>
+ * </p>
+ */
 public class GraphBinaryWriter {
     private final TypeSerializerRegistry registry;
     private final static byte VALUE_FLAG_NULL = 1;