Repository: arrow Updated Branches: refs/heads/master da523ce72 -> 569426b91
ARROW-930: javadoc generation fails with java 8 Author: Julien Le Dem <jul...@apache.org> Closes #627 from julienledem/fix_javadoc and squashes the following commits: 4160d5b [Julien Le Dem] ARROW-930: javadoc generation fails with java 8 Project: http://git-wip-us.apache.org/repos/asf/arrow/repo Commit: http://git-wip-us.apache.org/repos/asf/arrow/commit/569426b9 Tree: http://git-wip-us.apache.org/repos/asf/arrow/tree/569426b9 Diff: http://git-wip-us.apache.org/repos/asf/arrow/diff/569426b9 Branch: refs/heads/master Commit: 569426b917007d7eb8f238d657184d5789527646 Parents: da523ce Author: Julien Le Dem <jul...@apache.org> Authored: Tue May 2 11:27:19 2017 -0400 Committer: Wes McKinney <wes.mckin...@twosigma.com> Committed: Tue May 2 11:27:19 2017 -0400 ---------------------------------------------------------------------- .../apache/arrow/memory/AllocationManager.java | 22 +++---- .../arrow/memory/AllocationReservation.java | 13 ++-- .../apache/arrow/memory/BufferAllocator.java | 10 +++- .../org/apache/arrow/memory/BufferManager.java | 8 --- .../apache/arrow/memory/util/HistoricalLog.java | 27 +++------ .../codegen/templates/AbstractFieldReader.java | 63 ++++++++++---------- .../AbstractPromotableFieldWriter.java | 7 +-- .../src/main/codegen/templates/ArrowType.java | 2 +- .../src/main/codegen/templates/BaseWriter.java | 6 +- .../main/codegen/templates/ComplexCopier.java | 4 +- .../codegen/templates/FixedValueVectors.java | 2 +- .../codegen/templates/NullableValueVectors.java | 7 +-- .../templates/VariableLengthVectors.java | 2 +- .../arrow/vector/SchemaChangeCallBack.java | 1 + .../org/apache/arrow/vector/ValueVector.java | 29 +++++---- .../arrow/vector/VariableWidthVector.java | 4 +- .../org/apache/arrow/vector/VectorLoader.java | 2 +- .../vector/complex/AbstractContainerVector.java | 2 + .../arrow/vector/complex/AbstractMapVector.java | 18 ++++-- .../vector/complex/BaseRepeatedValueVector.java | 11 ++-- .../vector/complex/FixedSizeListVector.java | 13 ++-- .../vector/complex/RepeatedValueVector.java | 15 ++--- .../RepeatedVariableWidthVectorLike.java | 2 +- .../apache/arrow/vector/file/ArrowWriter.java | 10 ++-- .../apache/arrow/vector/file/ReadChannel.java | 7 +++ .../arrow/vector/stream/ArrowStreamReader.java | 14 +++-- .../arrow/vector/stream/MessageSerializer.java | 47 ++++++++++++++- .../apache/arrow/vector/types/pojo/Schema.java | 2 +- .../arrow/vector/util/MapWithOrdinal.java | 14 +++-- .../util/OversizedAllocationException.java | 3 +- .../java/org/apache/arrow/vector/util/Text.java | 50 ++++++++++++---- .../org/apache/arrow/vector/util/Validator.java | 4 ++ 32 files changed, 253 insertions(+), 168 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/memory/src/main/java/org/apache/arrow/memory/AllocationManager.java ---------------------------------------------------------------------- diff --git a/java/memory/src/main/java/org/apache/arrow/memory/AllocationManager.java b/java/memory/src/main/java/org/apache/arrow/memory/AllocationManager.java index 683752e..70ca1dc 100644 --- a/java/memory/src/main/java/org/apache/arrow/memory/AllocationManager.java +++ b/java/memory/src/main/java/org/apache/arrow/memory/AllocationManager.java @@ -18,15 +18,7 @@ package org.apache.arrow.memory; -import com.google.common.base.Preconditions; - -import io.netty.buffer.ArrowBuf; -import io.netty.buffer.PooledByteBufAllocatorL; -import io.netty.buffer.UnsafeDirectLittleEndian; - -import org.apache.arrow.memory.BaseAllocator.Verbosity; -import org.apache.arrow.memory.util.AutoCloseableLock; -import org.apache.arrow.memory.util.HistoricalLog; +import static org.apache.arrow.memory.BaseAllocator.indent; import java.util.IdentityHashMap; import java.util.concurrent.atomic.AtomicInteger; @@ -34,7 +26,15 @@ import java.util.concurrent.atomic.AtomicLong; import java.util.concurrent.locks.ReadWriteLock; import java.util.concurrent.locks.ReentrantReadWriteLock; -import static org.apache.arrow.memory.BaseAllocator.indent; +import org.apache.arrow.memory.BaseAllocator.Verbosity; +import org.apache.arrow.memory.util.AutoCloseableLock; +import org.apache.arrow.memory.util.HistoricalLog; + +import com.google.common.base.Preconditions; + +import io.netty.buffer.ArrowBuf; +import io.netty.buffer.PooledByteBufAllocatorL; +import io.netty.buffer.UnsafeDirectLittleEndian; /** * Manages the relationship between one or more allocators and a particular UDLE. Ensures that @@ -328,6 +328,8 @@ public class AllocationManager { * Decrement the ledger's reference count. If the ledger is decremented to zero, this ledger * should release its * ownership back to the AllocationManager + * @param decrement amout to decrease the reference count by + * @return the new reference count */ public int decrement(int decrement) { allocator.assertOpen(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/memory/src/main/java/org/apache/arrow/memory/AllocationReservation.java ---------------------------------------------------------------------- diff --git a/java/memory/src/main/java/org/apache/arrow/memory/AllocationReservation.java b/java/memory/src/main/java/org/apache/arrow/memory/AllocationReservation.java index 7f5aa31..b0ce574 100644 --- a/java/memory/src/main/java/org/apache/arrow/memory/AllocationReservation.java +++ b/java/memory/src/main/java/org/apache/arrow/memory/AllocationReservation.java @@ -30,13 +30,14 @@ import io.netty.buffer.ArrowBuf; * For the purposes of airtight memory accounting, the reservation must be close()d whether it is * used or not. * This is not threadsafe. + * </p> */ public interface AllocationReservation extends AutoCloseable { /** * Add to the current reservation. - * <p> - * <p>Adding may fail if the allocator is not allowed to consume any more space. + * + * <p>Adding may fail if the allocator is not allowed to consume any more space.</p> * * @param nBytes the number of bytes to add * @return true if the addition is possible, false otherwise @@ -46,8 +47,8 @@ public interface AllocationReservation extends AutoCloseable { /** * Requests a reservation of additional space. - * <p> - * <p>The implementation of the allocator's inner class provides this. + * + * <p>The implementation of the allocator's inner class provides this.</p> * * @param nBytes the amount to reserve * @return true if the reservation can be satisfied, false otherwise @@ -56,9 +57,9 @@ public interface AllocationReservation extends AutoCloseable { /** * Allocate a buffer whose size is the total of all the add()s made. - * <p> + * * <p>The allocation request can still fail, even if the amount of space - * requested is available, if the allocation cannot be made contiguously. + * requested is available, if the allocation cannot be made contiguously.</p> * * @return the buffer, or null, if the request cannot be satisfied * @throws IllegalStateException if called called more than once http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/memory/src/main/java/org/apache/arrow/memory/BufferAllocator.java ---------------------------------------------------------------------- diff --git a/java/memory/src/main/java/org/apache/arrow/memory/BufferAllocator.java b/java/memory/src/main/java/org/apache/arrow/memory/BufferAllocator.java index c05e9ac..8a40441 100644 --- a/java/memory/src/main/java/org/apache/arrow/memory/BufferAllocator.java +++ b/java/memory/src/main/java/org/apache/arrow/memory/BufferAllocator.java @@ -70,9 +70,9 @@ public interface BufferAllocator extends AutoCloseable { /** * Close and release all buffers generated from this buffer pool. - * <p> + * * <p>When assertions are on, complains if there are any outstanding buffers; to avoid - * that, release all buffers before the allocator is closed. + * that, release all buffers before the allocator is closed.</p> */ @Override public void close(); @@ -116,7 +116,8 @@ public interface BufferAllocator extends AutoCloseable { /** * Create an allocation reservation. A reservation is a way of building up * a request for a buffer whose size is not known in advance. See - * {@see AllocationReservation}. + * + * @see AllocationReservation * * @return the newly created reservation */ @@ -127,6 +128,7 @@ public interface BufferAllocator extends AutoCloseable { * special because we don't * worry about them leaking or managing reference counts on them since they don't actually * point to any memory. + * @return the empty buffer */ public ArrowBuf getEmpty(); @@ -134,6 +136,7 @@ public interface BufferAllocator extends AutoCloseable { * Return the name of this allocator. This is a human readable name that can help debugging. * Typically provides * coordinates about where this allocator was created + * @return the name of the allocator */ public String getName(); @@ -142,6 +145,7 @@ public interface BufferAllocator extends AutoCloseable { * that an allocator is * over its limit, all consumers of that allocator should aggressively try to addrss the * overlimit situation. + * @return whether or not this allocator (or one if its parents) is over its limits */ public boolean isOverLimit(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/memory/src/main/java/org/apache/arrow/memory/BufferManager.java ---------------------------------------------------------------------- diff --git a/java/memory/src/main/java/org/apache/arrow/memory/BufferManager.java b/java/memory/src/main/java/org/apache/arrow/memory/BufferManager.java index 2fe763e..3075ebe 100644 --- a/java/memory/src/main/java/org/apache/arrow/memory/BufferManager.java +++ b/java/memory/src/main/java/org/apache/arrow/memory/BufferManager.java @@ -25,14 +25,6 @@ import io.netty.buffer.ArrowBuf; * re-allocation the old buffer will be freed. Managing a list of these buffers * prevents some parts of the system from needing to define a correct location * to place the final call to free them. - * <p> - * The current uses of these types of buffers are within the pluggable components of Drill. - * In UDFs, memory management should not be a concern. We provide access to re-allocatable - * ArrowBufs to give UDF writers general purpose buffers we can account for. To prevent the need - * for UDFs to contain boilerplate to close all of the buffers they request, this list - * is tracked at a higher level and all of the buffers are freed once we are sure that - * the code depending on them is done executing (currently {@link FragmentContext} - * and {@link QueryContext}. */ public interface BufferManager extends AutoCloseable { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/memory/src/main/java/org/apache/arrow/memory/util/HistoricalLog.java ---------------------------------------------------------------------- diff --git a/java/memory/src/main/java/org/apache/arrow/memory/util/HistoricalLog.java b/java/memory/src/main/java/org/apache/arrow/memory/util/HistoricalLog.java index c464598..0452dc9 100644 --- a/java/memory/src/main/java/org/apache/arrow/memory/util/HistoricalLog.java +++ b/java/memory/src/main/java/org/apache/arrow/memory/util/HistoricalLog.java @@ -18,11 +18,11 @@ package org.apache.arrow.memory.util; -import org.slf4j.Logger; - import java.util.Arrays; import java.util.LinkedList; +import org.slf4j.Logger; + /** * Utility class that can be used to log activity within a class * for later logging and debugging. Supports recording events and @@ -98,19 +98,20 @@ public class HistoricalLog { * events with their stack traces. * * @param sb {@link StringBuilder} to write to + * @param includeStackTrace whether to include the stacktrace of each event in the history */ public void buildHistory(final StringBuilder sb, boolean includeStackTrace) { buildHistory(sb, 0, includeStackTrace); } /** - * - * @param sb - * @param indent - * @param includeStackTrace + * build the history and write it to sb + * @param sb output + * @param indent starting indent (usually "") + * @param includeStackTrace whether to include the stacktrace of each event. */ - public synchronized void buildHistory(final StringBuilder sb, int indent, boolean - includeStackTrace) { + public synchronized void buildHistory( + final StringBuilder sb, int indent, boolean includeStackTrace) { final char[] indentation = new char[indent]; final char[] innerIndentation = new char[indent + 2]; Arrays.fill(indentation, ' '); @@ -151,16 +152,6 @@ public class HistoricalLog { } /** - * Write the history of this object to the given {@link StringBuilder}. The history - * includes the identifying string provided at construction time, and all the recorded - * events with their stack traces. - * - * @param sb {@link StringBuilder} to write to - * @param additional an extra string that will be written between the identifying - * information and the history; often used for a current piece of state - */ - - /** * Write the history of this object to the given {@link Logger}. The history * includes the identifying string provided at construction time, and all the recorded * events with their stack traces. http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/AbstractFieldReader.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/AbstractFieldReader.java b/java/vector/src/main/codegen/templates/AbstractFieldReader.java index e0d0fc9..79d4c12 100644 --- a/java/vector/src/main/codegen/templates/AbstractFieldReader.java +++ b/java/vector/src/main/codegen/templates/AbstractFieldReader.java @@ -26,16 +26,19 @@ package org.apache.arrow.vector.complex.impl; <#include "/@includes/vv_imports.ftl" /> +/* + * This class is generated using freemarker and the ${.template_name} template. + */ @SuppressWarnings("unused") abstract class AbstractFieldReader extends AbstractBaseReader implements FieldReader{ - + AbstractFieldReader(){ super(); } /** * Returns true if the current value of the reader is not null - * @return + * @return whether the current value is set */ public boolean isSet() { return true; @@ -52,78 +55,74 @@ abstract class AbstractFieldReader extends AbstractBaseReader implements FieldRe "Text", "String", "Byte", "Short", "byte[]"] as friendlyType> <#assign safeType=friendlyType /> <#if safeType=="byte[]"><#assign safeType="ByteArray" /></#if> - - public ${friendlyType} read${safeType}(int arrayIndex){ + public ${friendlyType} read${safeType}(int arrayIndex) { fail("read${safeType}(int arrayIndex)"); return null; } - - public ${friendlyType} read${safeType}(){ + + public ${friendlyType} read${safeType}() { fail("read${safeType}()"); return null; } - + </#list> - - public void copyAsValue(MapWriter writer){ + public void copyAsValue(MapWriter writer) { fail("CopyAsValue MapWriter"); } - public void copyAsField(String name, MapWriter writer){ + + public void copyAsField(String name, MapWriter writer) { fail("CopyAsField MapWriter"); } - public void copyAsField(String name, ListWriter writer){ + public void copyAsField(String name, ListWriter writer) { fail("CopyAsFieldList"); } - + <#list vv.types as type><#list type.minor as minor><#assign name = minor.class?cap_first /> <#assign boxedType = (minor.boxedType!type.boxedType) /> - - public void read(${name}Holder holder){ + public void read(${name}Holder holder) { fail("${name}"); } - public void read(Nullable${name}Holder holder){ + public void read(Nullable${name}Holder holder) { fail("${name}"); } - - public void read(int arrayIndex, ${name}Holder holder){ + + public void read(int arrayIndex, ${name}Holder holder) { fail("Repeated${name}"); } - - public void read(int arrayIndex, Nullable${name}Holder holder){ + + public void read(int arrayIndex, Nullable${name}Holder holder) { fail("Repeated${name}"); } - - public void copyAsValue(${name}Writer writer){ + + public void copyAsValue(${name}Writer writer) { fail("CopyAsValue${name}"); } - public void copyAsField(String name, ${name}Writer writer){ + + public void copyAsField(String name, ${name}Writer writer) { fail("CopyAsField${name}"); } + </#list></#list> - - public FieldReader reader(String name){ + public FieldReader reader(String name) { fail("reader(String name)"); return null; } - public FieldReader reader(){ + public FieldReader reader() { fail("reader()"); return null; - } - - public int size(){ + + public int size() { fail("size()"); return -1; } - - private void fail(String name){ + + private void fail(String name) { throw new IllegalArgumentException(String.format("You tried to read a [%s] type when you are using a field reader of type [%s].", name, this.getClass().getSimpleName())); } - - } http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/AbstractPromotableFieldWriter.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/AbstractPromotableFieldWriter.java b/java/vector/src/main/codegen/templates/AbstractPromotableFieldWriter.java index 60dd0c7..ada0b1d 100644 --- a/java/vector/src/main/codegen/templates/AbstractPromotableFieldWriter.java +++ b/java/vector/src/main/codegen/templates/AbstractPromotableFieldWriter.java @@ -39,14 +39,13 @@ package org.apache.arrow.vector.complex.impl; abstract class AbstractPromotableFieldWriter extends AbstractFieldWriter { /** * Retrieve the FieldWriter, promoting if it is not a FieldWriter of the specified type - * @param type - * @return + * @param type the type of the values we want to write + * @return the corresponding field writer */ abstract protected FieldWriter getWriter(MinorType type); /** - * Return the current FieldWriter - * @return + * @return the current FieldWriter */ abstract protected FieldWriter getWriter(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/ArrowType.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/ArrowType.java b/java/vector/src/main/codegen/templates/ArrowType.java index a9e875a..dc99aad 100644 --- a/java/vector/src/main/codegen/templates/ArrowType.java +++ b/java/vector/src/main/codegen/templates/ArrowType.java @@ -100,7 +100,7 @@ public abstract class ArrowType { /** * to visit the ArrowTypes * <code> - * type.accept(new ArrowTypeVisitor<Type>() { + * type.accept(new ArrowTypeVisitor<Type>() { * ... * }); * </code> http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/BaseWriter.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/BaseWriter.java b/java/vector/src/main/codegen/templates/BaseWriter.java index 08bd39e..3da02b0 100644 --- a/java/vector/src/main/codegen/templates/BaseWriter.java +++ b/java/vector/src/main/codegen/templates/BaseWriter.java @@ -30,7 +30,7 @@ package org.apache.arrow.vector.complex.writer; * File generated from ${.template_name} using FreeMarker. */ @SuppressWarnings("unused") - public interface BaseWriter extends AutoCloseable, Positionable { +public interface BaseWriter extends AutoCloseable, Positionable { int getValueCapacity(); public interface MapWriter extends BaseWriter { @@ -39,12 +39,12 @@ package org.apache.arrow.vector.complex.writer; /** * Whether this writer is a map writer and is empty (has no children). - * + * * <p> * Intended only for use in determining whether to add dummy vector to * avoid empty (zero-column) schema, as in JsonReader. * </p> - * + * @return whether the map is empty */ boolean isEmptyMap(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/ComplexCopier.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/ComplexCopier.java b/java/vector/src/main/codegen/templates/ComplexCopier.java index 89368ce..fb7ae0f 100644 --- a/java/vector/src/main/codegen/templates/ComplexCopier.java +++ b/java/vector/src/main/codegen/templates/ComplexCopier.java @@ -34,8 +34,8 @@ public class ComplexCopier { /** * Do a deep copy of the value in input into output - * @param in - * @param out + * @param input field to read from + * @param output field to write to */ public static void copy(FieldReader input, FieldWriter output) { writeValue(input, output); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/FixedValueVectors.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/FixedValueVectors.java b/java/vector/src/main/codegen/templates/FixedValueVectors.java index 5c09e30..05faaae 100644 --- a/java/vector/src/main/codegen/templates/FixedValueVectors.java +++ b/java/vector/src/main/codegen/templates/FixedValueVectors.java @@ -150,7 +150,7 @@ public final class ${minor.class}Vector extends BaseDataValueVector implements F * * Note that the maximum number of values a vector can allocate is Integer.MAX_VALUE / value width. * - * @param valueCount + * @param valueCount the number of values to allocate for * @throws org.apache.arrow.memory.OutOfMemoryException if it can't allocate the new buffer */ @Override http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/NullableValueVectors.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/NullableValueVectors.java b/java/vector/src/main/codegen/templates/NullableValueVectors.java index 31adc2b..76d2bad 100644 --- a/java/vector/src/main/codegen/templates/NullableValueVectors.java +++ b/java/vector/src/main/codegen/templates/NullableValueVectors.java @@ -421,9 +421,8 @@ public final class ${className} extends BaseDataValueVector implements <#if type /** * Get the element at the specified position. * - * @param index position of the value - * @return value of the element, if not null - * @throws NullValueException if the value is null + * @param index position of the value + * @return value of the element, if not null */ public <#if type.major == "VarLen">byte[]<#else>${minor.javaType!type.javaType}</#if> get(int index) { if (isNull(index)) { @@ -509,7 +508,7 @@ public final class ${className} extends BaseDataValueVector implements <#if type * Set the variable length element at the specified index to the supplied byte array. * * @param index position of the bit to set - * @param bytes array of bytes to write + * @param value array of bytes (or int if smaller than 4 bytes) to write */ public void set(int index, <#if type.major == "VarLen">byte[]<#elseif (type.width < 4)>int<#else>${minor.javaType!type.javaType}</#if> value) { setCount++; http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/codegen/templates/VariableLengthVectors.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/codegen/templates/VariableLengthVectors.java b/java/vector/src/main/codegen/templates/VariableLengthVectors.java index 11f0cc8..3d933ad 100644 --- a/java/vector/src/main/codegen/templates/VariableLengthVectors.java +++ b/java/vector/src/main/codegen/templates/VariableLengthVectors.java @@ -139,7 +139,7 @@ public final class ${minor.class}Vector extends BaseDataValueVector implements V /** * Return the number of bytes contained in the current var len byte vector. - * @return + * @return the number of bytes contained in the current var len byte vector */ public int getVarByteLength(){ final int valueCount = getAccessor().getValueCount(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/SchemaChangeCallBack.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/SchemaChangeCallBack.java b/java/vector/src/main/java/org/apache/arrow/vector/SchemaChangeCallBack.java index fc0a066..6fdcda2 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/SchemaChangeCallBack.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/SchemaChangeCallBack.java @@ -42,6 +42,7 @@ public class SchemaChangeCallBack implements CallBack { /** * Returns the value of schema-changed state, <strong>resetting</strong> the * schema-changed state to {@code false}. + * @return the previous schema-changed state */ public boolean getSchemaChangedAndReset() { final boolean current = schemaChanged; http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/ValueVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/ValueVector.java b/java/vector/src/main/java/org/apache/arrow/vector/ValueVector.java index 685b0be..2e83836 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/ValueVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/ValueVector.java @@ -52,7 +52,7 @@ import io.netty.buffer.ArrowBuf; * * This interface "should" strive to guarantee this order of operation: * <blockquote> - * allocate > mutate > setvaluecount > access > clear (or allocate to start the process over). + * allocate > mutate > setvaluecount > access > clear (or allocate to start the process over). * </blockquote> */ public interface ValueVector extends Closeable, Iterable<ValueVector> { @@ -84,6 +84,7 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> { /** * Returns the maximum number of values that can be stored in this vector instance. + * @return the maximum number of values that can be stored in this vector instance. */ int getValueCapacity(); @@ -100,13 +101,16 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> { /** * Get information about how this field is materialized. + * @return the field corresponding to this vector */ Field getField(); MinorType getMinorType(); /** - * Returns a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of + * to transfer quota responsibility + * @param allocator the target allocator + * @return a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of * the same type. */ TransferPair getTransferPair(BufferAllocator allocator); @@ -116,31 +120,33 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> { TransferPair getTransferPair(String ref, BufferAllocator allocator, CallBack callBack); /** - * Returns a new {@link org.apache.arrow.vector.util.TransferPair transfer pair} that is used to transfer underlying + * makes a new transfer pair used to transfer underlying buffers + * @param target the target for the transfer + * @return a new {@link org.apache.arrow.vector.util.TransferPair transfer pair} that is used to transfer underlying * buffers into the target vector. */ TransferPair makeTransferPair(ValueVector target); /** - * Returns an {@link org.apache.arrow.vector.ValueVector.Accessor accessor} that is used to read from this vector + * @return an {@link org.apache.arrow.vector.ValueVector.Accessor accessor} that is used to read from this vector * instance. */ Accessor getAccessor(); /** - * Returns an {@link org.apache.arrow.vector.ValueVector.Mutator mutator} that is used to write to this vector + * @return an {@link org.apache.arrow.vector.ValueVector.Mutator mutator} that is used to write to this vector * instance. */ Mutator getMutator(); /** - * Returns a {@link org.apache.arrow.vector.complex.reader.FieldReader field reader} that supports reading values + * @return a {@link org.apache.arrow.vector.complex.reader.FieldReader field reader} that supports reading values * from this vector. */ FieldReader getReader(); /** - * Returns the number of bytes that is used by this vector instance. + * @return the number of bytes that is used by this vector instance. */ int getBufferSize(); @@ -177,21 +183,23 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> { * * @param index * Index of the value to get + * @return the friendly java type */ Object getObject(int index); /** - * Returns the number of values that is stored in this vector. + * @return the number of values that is stored in this vector. */ int getValueCount(); /** - * Returns true if the value at the given index is null, false otherwise. + * @param index the index to check for nullity + * @return true if the value at the given index is null, false otherwise. */ boolean isNull(int index); /** - * Returns the number of null values + * @return the number of null values */ int getNullCount(); } @@ -214,6 +222,7 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> { /** * @deprecated this has nothing to do with value vector abstraction and should be removed. + * @param values the number of values to generate */ @Deprecated void generateTestData(int values); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/VariableWidthVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/VariableWidthVector.java b/java/vector/src/main/java/org/apache/arrow/vector/VariableWidthVector.java index 971a241..ed164b5 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/VariableWidthVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/VariableWidthVector.java @@ -17,8 +17,6 @@ */ package org.apache.arrow.vector; -import io.netty.buffer.ArrowBuf; - public interface VariableWidthVector extends ValueVector{ /** @@ -31,7 +29,7 @@ public interface VariableWidthVector extends ValueVector{ /** * Provide the maximum amount of variable width bytes that can be stored in this vector. - * @return + * @return the byte capacity of this vector */ int getByteCapacity(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/VectorLoader.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/VectorLoader.java b/java/vector/src/main/java/org/apache/arrow/vector/VectorLoader.java index 76de250..33a608c 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/VectorLoader.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/VectorLoader.java @@ -50,7 +50,7 @@ public class VectorLoader { /** * Loads the record batch in the vectors * will not close the record batch - * @param recordBatch + * @param recordBatch the batch to load */ public void load(ArrowRecordBatch recordBatch) { Iterator<ArrowBuf> buffers = recordBatch.getBuffers().iterator(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractContainerVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractContainerVector.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractContainerVector.java index 71f2bea..7f8e679 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractContainerVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractContainerVector.java @@ -58,6 +58,8 @@ public abstract class AbstractContainerVector implements ValueVector { /** * Returns a {@link org.apache.arrow.vector.ValueVector} corresponding to the given field name if exists or null. + * @param name the name of the child to return + * @return the corresponding FieldVector */ public FieldVector getChild(String name) { return getChild(name, FieldVector.class); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractMapVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractMapVector.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractMapVector.java index 15e8a5b..4b6d82c 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractMapVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/AbstractMapVector.java @@ -151,14 +151,19 @@ public abstract class AbstractMapVector extends AbstractContainerVector { /** * Returns a {@link org.apache.arrow.vector.ValueVector} corresponding to the given ordinal identifier. + * @param id the ordinal of the child to return + * @return the corresponding child */ public ValueVector getChildByOrdinal(int id) { return vectors.getByOrdinal(id); } /** - * Returns a {@link org.apache.arrow.vector.ValueVector} instance of subtype of <T> corresponding to the given + * Returns a {@link org.apache.arrow.vector.ValueVector} instance of subtype of T corresponding to the given * field name if exists or null. + * @param name the name of the child to return + * @param clazz the expected type of the child + * @return the child corresponding to this name */ @Override public <T extends FieldVector> T getChild(String name, Class<T> clazz) { @@ -186,6 +191,8 @@ public abstract class AbstractMapVector extends AbstractContainerVector { * Inserts the vector with the given name if it does not exist else replaces it with the new value. * * Note that this method does not enforce any vector type check nor throws a schema change exception. + * @param name the name of the child to add + * @param vector the vector to add as a child */ protected void putChild(String name, FieldVector vector) { putVector(name, vector); @@ -208,7 +215,7 @@ public abstract class AbstractMapVector extends AbstractContainerVector { } /** - * Returns a sequence of underlying child vectors. + * @return a sequence of underlying child vectors. */ protected List<FieldVector> getChildren() { int size = vectors.size(); @@ -228,7 +235,7 @@ public abstract class AbstractMapVector extends AbstractContainerVector { } /** - * Returns the number of underlying child vectors. + * @return the number of underlying child vectors. */ @Override public int size() { @@ -241,7 +248,7 @@ public abstract class AbstractMapVector extends AbstractContainerVector { } /** - * Returns a list of scalar child vectors recursing the entire vector hierarchy. + * @return a list of scalar child vectors recursing the entire vector hierarchy. */ public List<ValueVector> getPrimitiveVectors() { final List<ValueVector> primitiveVectors = Lists.newArrayList(); @@ -257,7 +264,8 @@ public abstract class AbstractMapVector extends AbstractContainerVector { } /** - * Returns a vector with its corresponding ordinal mapping if field exists or null. + * @param name the name of the child to return + * @return a vector with its corresponding ordinal mapping if field exists or null. */ @Override public VectorWithOrdinal getChildVectorWithOrdinal(String name) { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/BaseRepeatedValueVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/BaseRepeatedValueVector.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/BaseRepeatedValueVector.java index c9a9319..5ff4c2c 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/BaseRepeatedValueVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/BaseRepeatedValueVector.java @@ -20,10 +20,6 @@ package org.apache.arrow.vector.complex; import java.util.Collections; import java.util.Iterator; -import com.google.common.base.Preconditions; -import com.google.common.collect.ObjectArrays; - -import io.netty.buffer.ArrowBuf; import org.apache.arrow.memory.BufferAllocator; import org.apache.arrow.vector.AddOrGetResult; import org.apache.arrow.vector.BaseValueVector; @@ -35,6 +31,11 @@ import org.apache.arrow.vector.types.pojo.FieldType; import org.apache.arrow.vector.util.CallBack; import org.apache.arrow.vector.util.SchemaChangeRuntimeException; +import com.google.common.base.Preconditions; +import com.google.common.collect.ObjectArrays; + +import io.netty.buffer.ArrowBuf; + public abstract class BaseRepeatedValueVector extends BaseValueVector implements RepeatedValueVector { public final static FieldVector DEFAULT_DATA_VECTOR = ZeroVector.INSTANCE; @@ -151,7 +152,7 @@ public abstract class BaseRepeatedValueVector extends BaseValueVector implements } /** - * Returns 1 if inner vector is explicitly set via #addOrGetVector else 0 + * @return 1 if inner vector is explicitly set via #addOrGetVector else 0 */ public int size() { return vector == DEFAULT_DATA_VECTOR ? 0:1; http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/FixedSizeListVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/FixedSizeListVector.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/FixedSizeListVector.java index 7ac9f3b..0dceeed 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/FixedSizeListVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/FixedSizeListVector.java @@ -26,11 +26,6 @@ import java.util.Iterator; import java.util.List; import java.util.Objects; -import com.google.common.base.Preconditions; -import com.google.common.collect.ImmutableList; -import com.google.common.collect.ObjectArrays; - -import io.netty.buffer.ArrowBuf; import org.apache.arrow.memory.BufferAllocator; import org.apache.arrow.memory.OutOfMemoryException; import org.apache.arrow.vector.AddOrGetResult; @@ -53,6 +48,12 @@ import org.apache.arrow.vector.util.JsonStringArrayList; import org.apache.arrow.vector.util.SchemaChangeRuntimeException; import org.apache.arrow.vector.util.TransferPair; +import com.google.common.base.Preconditions; +import com.google.common.collect.ImmutableList; +import com.google.common.collect.ObjectArrays; + +import io.netty.buffer.ArrowBuf; + public class FixedSizeListVector extends BaseValueVector implements FieldVector, PromotableVector { private FieldVector vector; @@ -236,7 +237,7 @@ public class FixedSizeListVector extends BaseValueVector implements FieldVector, } /** - * Returns 1 if inner vector is explicitly set via #addOrGetVector else 0 + * @return 1 if inner vector is explicitly set via #addOrGetVector else 0 */ public int size() { return vector == ZeroVector.INSTANCE ? 0 : 1; http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedValueVector.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedValueVector.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedValueVector.java index b01a4e7..de58eda 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedValueVector.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedValueVector.java @@ -33,14 +33,12 @@ public interface RepeatedValueVector extends ValueVector { final static int DEFAULT_REPEAT_PER_RECORD = 5; /** - * Returns the underlying offset vector or null if none exists. - * - * TODO(DRILL-2995): eliminate exposing low-level interfaces. + * @return the underlying offset vector or null if none exists. */ UInt4Vector getOffsetVector(); /** - * Returns the underlying data vector or null if none exists. + * @return the underlying data vector or null if none exists. */ ValueVector getDataVector(); @@ -52,22 +50,21 @@ public interface RepeatedValueVector extends ValueVector { interface RepeatedAccessor extends ValueVector.Accessor { /** - * Returns total number of cells that vector contains. - * * The result includes empty, null valued cells. + * @return total number of cells that vector contains. */ int getInnerValueCount(); /** - * Returns number of cells that the value at the given index contains. + * @param index the index of the value for which we want the size + * @return number of cells that the value at the given index contains. */ int getInnerValueCountAt(int index); /** - * Returns true if the value at the given index is empty, false otherwise. - * * @param index value index + * @return true if the value at the given index is empty, false otherwise. */ boolean isEmpty(int index); } http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedVariableWidthVectorLike.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedVariableWidthVectorLike.java b/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedVariableWidthVectorLike.java index 93b744e..29f9d75 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedVariableWidthVectorLike.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/complex/RepeatedVariableWidthVectorLike.java @@ -29,7 +29,7 @@ public interface RepeatedVariableWidthVectorLike { /** * Provide the maximum amount of variable width bytes that can be stored int his vector. - * @return + * @return the byte capacity */ int getByteCapacity(); } http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/file/ArrowWriter.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/file/ArrowWriter.java b/java/vector/src/main/java/org/apache/arrow/vector/file/ArrowWriter.java index 60a6afb..1716287 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/file/ArrowWriter.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/file/ArrowWriter.java @@ -25,8 +25,6 @@ import java.util.HashMap; import java.util.List; import java.util.Map; -import com.google.common.collect.ImmutableList; - import org.apache.arrow.vector.FieldVector; import org.apache.arrow.vector.VectorSchemaRoot; import org.apache.arrow.vector.VectorUnloader; @@ -42,6 +40,8 @@ import org.apache.arrow.vector.types.pojo.Schema; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import com.google.common.collect.ImmutableList; + public abstract class ArrowWriter implements AutoCloseable { private static final Logger LOGGER = LoggerFactory.getLogger(ArrowWriter.class); @@ -62,9 +62,9 @@ public abstract class ArrowWriter implements AutoCloseable { /** * Note: fields are not closed when the writer is closed * - * @param root - * @param provider - * @param out + * @param root the vectors to write to the output + * @param provider where to find the dictionaries + * @param out the output where to write */ protected ArrowWriter(VectorSchemaRoot root, DictionaryProvider provider, WritableByteChannel out) { this.unloader = new VectorUnloader(root); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/file/ReadChannel.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/file/ReadChannel.java b/java/vector/src/main/java/org/apache/arrow/vector/file/ReadChannel.java index b062f38..87450e3 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/file/ReadChannel.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/file/ReadChannel.java @@ -42,6 +42,9 @@ public class ReadChannel implements AutoCloseable { /** * Reads bytes into buffer until it is full (buffer.remaining() == 0). Returns the * number of bytes read which can be less than full if there are no more. + * @param buffer The buffer to read to + * @return the number of byte read + * @throws IOException if nit enough bytes left to read */ public int readFully(ByteBuffer buffer) throws IOException { LOGGER.debug("Reading buffer with size: " + buffer.remaining()); @@ -58,6 +61,10 @@ public class ReadChannel implements AutoCloseable { /** * Reads up to len into buffer. Returns bytes read. + * @param buffer the buffer to read to + * @param l the amount of bytes to read + * @return the number of bytes read + * @throws IOException if nit enough bytes left to read */ public int readFully(ArrowBuf buffer, int l) throws IOException { int n = readFully(buffer.nioBuffer(buffer.writerIndex(), l)); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/stream/ArrowStreamReader.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/stream/ArrowStreamReader.java b/java/vector/src/main/java/org/apache/arrow/vector/stream/ArrowStreamReader.java index 2deef37..641978a 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/stream/ArrowStreamReader.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/stream/ArrowStreamReader.java @@ -17,17 +17,17 @@ */ package org.apache.arrow.vector.stream; +import java.io.IOException; +import java.io.InputStream; +import java.nio.channels.Channels; +import java.nio.channels.ReadableByteChannel; + import org.apache.arrow.memory.BufferAllocator; import org.apache.arrow.vector.file.ArrowReader; import org.apache.arrow.vector.file.ReadChannel; import org.apache.arrow.vector.schema.ArrowMessage; import org.apache.arrow.vector.types.pojo.Schema; -import java.io.IOException; -import java.io.InputStream; -import java.nio.channels.Channels; -import java.nio.channels.ReadableByteChannel; - /** * This classes reads from an input stream and produces ArrowRecordBatches. */ @@ -35,6 +35,8 @@ public class ArrowStreamReader extends ArrowReader<ReadChannel> { /** * Constructs a streaming read, reading bytes from 'in'. Non-blocking. + * @param in the stream to read from + * @param allocator to allocate new buffers */ public ArrowStreamReader(ReadableByteChannel in, BufferAllocator allocator) { super(new ReadChannel(in), allocator); @@ -46,6 +48,8 @@ public class ArrowStreamReader extends ArrowReader<ReadChannel> { /** * Reads the schema message from the beginning of the stream. + * @param in to allocate new buffers + * @return the deserialized arrow schema */ @Override protected Schema readSchema(ReadChannel in) throws IOException { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/stream/MessageSerializer.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/stream/MessageSerializer.java b/java/vector/src/main/java/org/apache/arrow/vector/stream/MessageSerializer.java index 228ab61..2fd9374 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/stream/MessageSerializer.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/stream/MessageSerializer.java @@ -22,9 +22,6 @@ import java.nio.ByteBuffer; import java.util.ArrayList; import java.util.List; -import com.google.flatbuffers.FlatBufferBuilder; - -import io.netty.buffer.ArrowBuf; import org.apache.arrow.flatbuf.Buffer; import org.apache.arrow.flatbuf.DictionaryBatch; import org.apache.arrow.flatbuf.FieldNode; @@ -43,6 +40,10 @@ import org.apache.arrow.vector.schema.ArrowMessage; import org.apache.arrow.vector.schema.ArrowRecordBatch; import org.apache.arrow.vector.types.pojo.Schema; +import com.google.flatbuffers.FlatBufferBuilder; + +import io.netty.buffer.ArrowBuf; + /** * Utility class for serializing Messages. Messages are all serialized a similar way. * 1. 4 byte little endian message header prefix @@ -69,6 +70,10 @@ public class MessageSerializer { /** * Serialize a schema object. + * @param out where to write the schema + * @param schema the object to serialize to out + * @return the resulting size of the serialized schema + * @throws IOException if something went wrong */ public static long serialize(WriteChannel out, Schema schema) throws IOException { FlatBufferBuilder builder = new FlatBufferBuilder(); @@ -81,6 +86,9 @@ public class MessageSerializer { /** * Deserializes a schema object. Format is from serialize(). + * @param in the channel to deserialize from + * @return the deserialized object + * @throws IOException if something went wrong */ public static Schema deserializeSchema(ReadChannel in) throws IOException { Message message = deserializeMessage(in); @@ -98,6 +106,10 @@ public class MessageSerializer { /** * Serializes an ArrowRecordBatch. Returns the offset and length of the written batch. + * @param out where to write the batch + * @param batch the object to serialize to out + * @return the serialized block metadata + * @throws IOException if something went wrong */ public static ArrowBlock serialize(WriteChannel out, ArrowRecordBatch batch) throws IOException { @@ -153,6 +165,11 @@ public class MessageSerializer { /** * Deserializes a RecordBatch + * @param in the channel to deserialize from + * @param message the object to derialize to + * @param alloc to allocate buffers + * @return the deserialized object + * @throws IOException if something went wrong */ private static ArrowRecordBatch deserializeRecordBatch(ReadChannel in, Message message, BufferAllocator alloc) throws IOException { @@ -171,6 +188,11 @@ public class MessageSerializer { /** * Deserializes a RecordBatch knowing the size of the entire message up front. This * minimizes the number of reads to the underlying stream. + * @param in the channel to deserialize from + * @param block the object to derialize to + * @param alloc to allocate buffers + * @return the deserialized object + * @throws IOException if something went wrong */ public static ArrowRecordBatch deserializeRecordBatch(ReadChannel in, ArrowBlock block, BufferAllocator alloc) throws IOException { @@ -231,6 +253,10 @@ public class MessageSerializer { /** * Serializes a dictionary ArrowRecordBatch. Returns the offset and length of the written batch. + * @param out where to serialize + * @param batch the batch to serialize + * @return the metadata of the serialized block + * @throws IOException if something went wrong */ public static ArrowBlock serialize(WriteChannel out, ArrowDictionaryBatch batch) throws IOException { long start = out.getCurrentPosition(); @@ -264,6 +290,11 @@ public class MessageSerializer { /** * Deserializes a DictionaryBatch + * @param in where to read from + * @param message the message message metadata to deserialize + * @param alloc the allocator for new buffers + * @return the corresponding dictionary batch + * @throws IOException if something went wrong */ private static ArrowDictionaryBatch deserializeDictionaryBatch(ReadChannel in, Message message, @@ -284,6 +315,11 @@ public class MessageSerializer { /** * Deserializes a DictionaryBatch knowing the size of the entire message up front. This * minimizes the number of reads to the underlying stream. + * @param in where to read from + * @param block block metadata for deserializing + * @param alloc to allocate new buffers + * @return the corresponding dictionary + * @throws IOException if something went wrong */ public static ArrowDictionaryBatch deserializeDictionaryBatch(ReadChannel in, ArrowBlock block, @@ -331,6 +367,11 @@ public class MessageSerializer { /** * Serializes a message header. + * @param builder to write the flatbuf to + * @param headerType headerType field + * @param headerOffset header offset field + * @param bodyLength body length field + * @return the corresponding ByteBuffer */ private static ByteBuffer serializeMessage(FlatBufferBuilder builder, byte headerType, int headerOffset, int bodyLength) { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/types/pojo/Schema.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/types/pojo/Schema.java b/java/vector/src/main/java/org/apache/arrow/vector/types/pojo/Schema.java index c33bd6e..cede3e8 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/types/pojo/Schema.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/types/pojo/Schema.java @@ -44,7 +44,7 @@ import com.google.flatbuffers.FlatBufferBuilder; public class Schema { /** - * @param the list of the fields + * @param fields the list of the fields * @param name the name of the field to return * @return the corresponding field * @throws IllegalArgumentException if the field was not found http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/util/MapWithOrdinal.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/util/MapWithOrdinal.java b/java/vector/src/main/java/org/apache/arrow/vector/util/MapWithOrdinal.java index d7f9d38..b35aaa4 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/util/MapWithOrdinal.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/util/MapWithOrdinal.java @@ -24,16 +24,18 @@ import java.util.List; import java.util.Map; import java.util.Set; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + import com.google.common.base.Function; import com.google.common.base.Preconditions; import com.google.common.collect.Iterables; import com.google.common.collect.Lists; import com.google.common.collect.Maps; import com.google.common.collect.Sets; + import io.netty.util.collection.IntObjectHashMap; import io.netty.util.collection.IntObjectMap; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; /** * An implementation of map that supports constant time look-up by a generic key or an ordinal. @@ -194,7 +196,7 @@ public class MapWithOrdinal<K, V> implements Map<K, V> { * assignment. A new ordinal is assigned if key does not exists. Otherwise the same ordinal is re-used but the value * is replaced. * - * {@see java.util.Map#put} + * @see java.util.Map#put */ @Override public V put(K key, V value) { @@ -217,11 +219,11 @@ public class MapWithOrdinal<K, V> implements Map<K, V> { } /** - * Removes the element corresponding to the key if exists extending the semantics of {@link Map#remove} with ordinal + * Removes the element corresponding to the key if exists extending the semantics of {@link java.util.Map#remove} with ordinal * re-cycling. The ordinal corresponding to the given key may be re-assigned to another tuple. It is important that - * consumer checks the ordinal value via {@link #getOrdinal(Object)} before attempting to look-up by ordinal. + * consumer checks the ordinal value via {@link org.apache.arrow.vector.util.MapWithOrdinal#getOrdinal(Object)} before attempting to look-up by ordinal. * - * {@see java.util.Map#remove} + * @see java.util.Map#remove */ @Override public V remove(Object key) { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/util/OversizedAllocationException.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/util/OversizedAllocationException.java b/java/vector/src/main/java/org/apache/arrow/vector/util/OversizedAllocationException.java index ec628b2..bd73962 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/util/OversizedAllocationException.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/util/OversizedAllocationException.java @@ -22,8 +22,7 @@ package org.apache.arrow.vector.util; * An exception that is used to signal that allocation request in bytes is greater than the maximum allowed by * {@link org.apache.arrow.memory.BufferAllocator#buffer(int) allocator}. * - * <p>Operators should handle this exception to split the batch and later resume the execution on the next - * {@link RecordBatch#next() iteration}.</p> + * <p>Operators should handle this exception to split the batch and later resume the execution on the next iteration.</p> * */ public class OversizedAllocationException extends RuntimeException { http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/util/Text.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/util/Text.java b/java/vector/src/main/java/org/apache/arrow/vector/util/Text.java index 3db4358..ce82f44 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/util/Text.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/util/Text.java @@ -74,18 +74,22 @@ public class Text { /** * Construct from a string. + * @param string initialize from that string */ public Text(String string) { set(string); } - /** Construct from another text. */ + /** Construct from another text. + * @param utf8 initialize from that Text + */ public Text(Text utf8) { set(utf8); } /** * Construct from a byte array. + * @param utf8 initialize from that byte array */ public Text(byte[] utf8) { set(utf8); @@ -94,6 +98,7 @@ public class Text { /** * Get a copy of the bytes that is exactly the length of the data. See {@link #getBytes()} for faster access to the * underlying array. + * @return a copy of the underlying array */ public byte[] copyBytes() { byte[] result = new byte[length]; @@ -104,12 +109,13 @@ public class Text { /** * Returns the raw bytes; however, only data up to {@link #getLength()} is valid. Please use {@link #copyBytes()} if * you need the returned array to be precisely the length of the data. + * @return the underlying array */ public byte[] getBytes() { return bytes; } - /** Returns the number of bytes in the byte array */ + /** @return the number of bytes in the byte array */ public int getLength() { return length; } @@ -118,6 +124,7 @@ public class Text { * Returns the Unicode Scalar Value (32-bit integer value) for the character at <code>position</code>. Note that this * method avoids using the converter or doing String instantiation * + * @param position the index of the char we want to retrieve * @return the Unicode scalar value at position or -1 if the position is invalid or points to a trailing byte */ public int charAt(int position) { @@ -143,6 +150,8 @@ public class Text { * starting position is measured in bytes and the return value is in terms of byte position in the buffer. The backing * buffer is not converted to a string for this operation. * + * @param what the string to search for + * @param start where to start from * @return byte position of the first occurence of the search string in the UTF-8 buffer or -1 if not found */ public int find(String what, int start) { @@ -187,6 +196,7 @@ public class Text { /** * Set to contain the contents of a string. + * @param string the string to initialize from */ public void set(String string) { try { @@ -200,12 +210,14 @@ public class Text { /** * Set to a utf8 byte array + * @param utf8 the byte array to initialize from */ public void set(byte[] utf8) { set(utf8, 0, utf8.length); } - /** copy a text. */ + /** copy a text. + * @param other the text to initialize from */ public void set(Text other) { set(other.getBytes(), 0, other.getLength()); } @@ -253,13 +265,12 @@ public class Text { length = 0; } - /* + /** * Sets the capacity of this Text object to <em>at least</em> <code>len</code> bytes. If the current buffer is longer, * then the capacity and existing content of the buffer are unchanged. If <code>len</code> is larger than the current * capacity, the Text object's capacity is increased to match. * * @param len the number of bytes we need - * * @param keepData should the old data be kept */ private void setCapacity(int len, boolean keepData) { @@ -272,11 +283,6 @@ public class Text { } } - /** - * Convert text back to string - * - * @see java.lang.Object#toString() - */ @Override public String toString() { try { @@ -289,6 +295,9 @@ public class Text { /** * Read a Text object whose length is already known. This allows creating Text from a stream which uses a different * serialization format. + * @param in the input to initialize from + * @param len how many bytes to read from in + * @throws IOException if something bad happens */ public void readWithKnownLength(DataInput in, int len) throws IOException { setCapacity(len, false); @@ -296,7 +305,6 @@ public class Text { length = len; } - /** Returns true iff <code>o</code> is a Text with the same contents. */ @Override public boolean equals(Object o) { if (o == this) { @@ -326,7 +334,7 @@ public class Text { /** * Copied from Arrays.hashCode so we don't have to copy the byte array * - * @return + * @return hashCode */ @Override public int hashCode() { @@ -346,6 +354,9 @@ public class Text { /** * Converts the provided byte array to a String using the UTF-8 encoding. If the input is malformed, replace by a * default value. + * @param utf8 bytes to decode + * @return the decoded string + * @throws CharacterCodingException if this is not valid UTF-8 */ public static String decode(byte[] utf8) throws CharacterCodingException { return decode(ByteBuffer.wrap(utf8), true); @@ -360,6 +371,12 @@ public class Text { * Converts the provided byte array to a String using the UTF-8 encoding. If <code>replace</code> is true, then * malformed input is replaced with the substitution character, which is U+FFFD. Otherwise the method throws a * MalformedInputException. + * @param utf8 the bytes to decode + * @param start where to start from + * @param length length of the bytes to decode + * @param replace whether to replace malformed characters with U+FFFD + * @return the decoded string + * @throws CharacterCodingException if the input could not be decoded */ public static String decode(byte[] utf8, int start, int length, boolean replace) throws CharacterCodingException { @@ -387,9 +404,10 @@ public class Text { * Converts the provided String to bytes using the UTF-8 encoding. If the input is malformed, invalid chars are * replaced by a default value. * + * @param string the string to encode * @return ByteBuffer: bytes stores at ByteBuffer.array() and length is ByteBuffer.limit() + * @throws CharacterCodingException if the string could not be encoded */ - public static ByteBuffer encode(String string) throws CharacterCodingException { return encode(string, true); @@ -400,7 +418,11 @@ public class Text { * input is replaced with the substitution character, which is U+FFFD. Otherwise the method throws a * MalformedInputException. * + + * @param string the string to encode + * @param replace whether to replace malformed characters with U+FFFD * @return ByteBuffer: bytes stores at ByteBuffer.array() and length is ByteBuffer.limit() + * @throws CharacterCodingException if the string could not be encoded */ public static ByteBuffer encode(String string, boolean replace) throws CharacterCodingException { @@ -553,6 +575,8 @@ public class Text { /** * Returns the next code point at the current position in the buffer. The buffer's position will be incremented. Any * mark set on this buffer will be changed by this method! + * @param bytes the incoming bytes + * @return the corresponding unicode codepoint */ public static int bytesToCodePoint(ByteBuffer bytes) { bytes.mark(); http://git-wip-us.apache.org/repos/asf/arrow/blob/569426b9/java/vector/src/main/java/org/apache/arrow/vector/util/Validator.java ---------------------------------------------------------------------- diff --git a/java/vector/src/main/java/org/apache/arrow/vector/util/Validator.java b/java/vector/src/main/java/org/apache/arrow/vector/util/Validator.java index f294e20..3035576 100644 --- a/java/vector/src/main/java/org/apache/arrow/vector/util/Validator.java +++ b/java/vector/src/main/java/org/apache/arrow/vector/util/Validator.java @@ -36,6 +36,8 @@ public class Validator { /** * Validate two arrow schemas are equal. * + * @param schema1 the 1st shema to compare + * @param schema2 the 2nd shema to compare * @throws IllegalArgumentException if they are different. */ public static void compareSchemas(Schema schema1, Schema schema2) { @@ -47,6 +49,8 @@ public class Validator { /** * Validate two arrow vectorSchemaRoot are equal. * + * @param root1 the 1st shema to compare + * @param root2 the 2nd shema to compare * @throws IllegalArgumentException if they are different. */ public static void compareVectorSchemaRoot(VectorSchemaRoot root1, VectorSchemaRoot root2) {
