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 <jorgebaygon...@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;