org.apache.avro.io

## Class BinaryDecoder

- java.lang.Object
- - org.apache.avro.io.Decoder
  - - org.apache.avro.io.BinaryDecoder

-     public class BinaryDecoder
      extends Decoder

  An `Decoder` for binary-format data.

  Instances are created using `DecoderFactory`.

  This class may read-ahead and buffer bytes from the source beyond what is required to serve its read methods. The number of unused bytes in the buffer can be accessed by inputStream().remaining(), if the BinaryDecoder is not 'direct'.

  See Also:
    `Encoder`, `SystemLimitException`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BinaryDecoder()` protected constructor for child classes

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `arrayNext()` Processes the next block of an array and returns the number of items in the block and let's the caller read those items.
    `protected void` | `doReadBytes(byte[] bytes, int start, int length)` Reads `length` bytes into `bytes` starting at `start`.
    `protected long` | `doReadItemCount()` Returns the number of items to follow in the current array or map.
    `protected void` | `doSkipBytes(long length)`
    `InputStream` | `inputStream()` Returns an `InputStream` that is aware of any buffering that may occur in this BinaryDecoder.
    `boolean` | `isEnd()` Returns true if the current BinaryDecoder is at the end of its source data and cannot read any further without throwing an EOFException or other IOException.
    `long` | `mapNext()` Processes the next block of map entries and returns the count of them.
    `long` | `readArrayStart()` Reads and returns the size of the first block of an array.
    `boolean` | `readBoolean()` Reads a boolean value written by `Encoder.writeBoolean(boolean)`.
    `ByteBuffer` | `readBytes(ByteBuffer old)` Reads a byte-string written by `Encoder.writeBytes(java.nio.ByteBuffer)`.
    `double` | `readDouble()` Reads a double written by `Encoder.writeDouble(double)`.
    `int` | `readEnum()` Reads an enumeration.
    `void` | `readFixed(byte[] bytes, int start, int length)` Reads fixed sized binary object.
    `float` | `readFloat()` Reads a float written by `Encoder.writeFloat(float)`.
    `int` | `readIndex()` Reads the tag of a union written by `Encoder.writeIndex(int)`.
    `int` | `readInt()` Reads an integer written by `Encoder.writeInt(int)`.
    `long` | `readLong()` Reads a long written by `Encoder.writeLong(long)`.
    `long` | `readMapStart()` Reads and returns the size of the next block of map-entries.
    `void` | `readNull()` "Reads" a null value.
    `String` | `readString()` Reads a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.
    `Utf8` | `readString(Utf8 old)` Reads a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.
    `long` | `skipArray()` Used for quickly skipping through an array.
    `void` | `skipBytes()` Discards a byte-string written by `Encoder.writeBytes(java.nio.ByteBuffer)`.
    `void` | `skipFixed(int length)` Discards fixed sized binary object.
    `long` | `skipMap()` Support for quickly skipping through a map similar to `Decoder.skipArray()`.
    `void` | `skipString()` Discards a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.

    - ### Methods inherited from class org.apache.avro.io.Decoder

      `readFixed`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### BinaryDecoder

          protected BinaryDecoder()

      protected constructor for child classes

  - ### Method Detail

    - #### readNull

          public void readNull()
                        throws IOException

      Description copied from class: `Decoder`
      "Reads" a null value. (Doesn't actually read anything, but advances the state of the parser if the implementation is stateful.)
      Specified by:
        `readNull` in class `Decoder`
      Throws:
        `IOException`

    - #### readBoolean

          public boolean readBoolean()
                              throws IOException

      Description copied from class: `Decoder`
      Reads a boolean value written by `Encoder.writeBoolean(boolean)`.
      Specified by:
        `readBoolean` in class `Decoder`
      Throws:
        `IOException`

    - #### readInt

          public int readInt()
                      throws IOException

      Description copied from class: `Decoder`
      Reads an integer written by `Encoder.writeInt(int)`.
      Specified by:
        `readInt` in class `Decoder`
      Throws:
        `IOException`

    - #### readLong

          public long readLong()
                        throws IOException

      Description copied from class: `Decoder`
      Reads a long written by `Encoder.writeLong(long)`.
      Specified by:
        `readLong` in class `Decoder`
      Throws:
        `IOException`

    - #### readFloat

          public float readFloat()
                          throws IOException

      Description copied from class: `Decoder`
      Reads a float written by `Encoder.writeFloat(float)`.
      Specified by:
        `readFloat` in class `Decoder`
      Throws:
        `IOException`

    - #### readDouble

          public double readDouble()
                            throws IOException

      Description copied from class: `Decoder`
      Reads a double written by `Encoder.writeDouble(double)`.
      Specified by:
        `readDouble` in class `Decoder`
      Throws:
        `IOException`

    - #### readString

          public Utf8 readString(Utf8 old)
                          throws IOException

      Description copied from class: `Decoder`
      Reads a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.
      Specified by:
        `readString` in class `Decoder`
      Throws:
        `IOException`

    - #### readString

          public String readString()
                            throws IOException

      Description copied from class: `Decoder`
      Reads a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.
      Specified by:
        `readString` in class `Decoder`
      Throws:
        `IOException`

    - #### skipString

          public void skipString()
                          throws IOException

      Description copied from class: `Decoder`
      Discards a char-string written by `Encoder.writeString(org.apache.avro.util.Utf8)`.
      Specified by:
        `skipString` in class `Decoder`
      Throws:
        `IOException`

    - #### readBytes

          public ByteBuffer readBytes(ByteBuffer old)
                               throws IOException

      Description copied from class: `Decoder`
      Reads a byte-string written by `Encoder.writeBytes(java.nio.ByteBuffer)`. if `old` is not null and has sufficient capacity to take in the bytes being read, the bytes are returned in `old`.
      Specified by:
        `readBytes` in class `Decoder`
      Throws:
        `IOException`

    - #### skipBytes

          public void skipBytes()
                         throws IOException

      Description copied from class: `Decoder`
      Discards a byte-string written by `Encoder.writeBytes(java.nio.ByteBuffer)`.
      Specified by:
        `skipBytes` in class `Decoder`
      Throws:
        `IOException`

    - #### readFixed

          public void readFixed(byte[] bytes,
                                int start,
                                int length)
                         throws IOException

      Description copied from class: `Decoder`
      Reads fixed sized binary object.
      Specified by:
        `readFixed` in class `Decoder`
      Parameters:
        `bytes` - The buffer to store the contents being read.
        `start` - The position where the data needs to be written.
        `length` - The size of the binary object.
      Throws:
        `IOException`

    - #### skipFixed

          public void skipFixed(int length)
                         throws IOException

      Description copied from class: `Decoder`
      Discards fixed sized binary object.
      Specified by:
        `skipFixed` in class `Decoder`
      Parameters:
        `length` - The size of the binary object to be skipped.
      Throws:
        `IOException`

    - #### readEnum

          public int readEnum()
                       throws IOException

      Description copied from class: `Decoder`
      Reads an enumeration.
      Specified by:
        `readEnum` in class `Decoder`
      Returns:
        The enumeration's value.
      Throws:
        `IOException`

    - #### doSkipBytes

          protected void doSkipBytes(long length)
                              throws IOException

      Throws:
        `IOException`

    - #### doReadBytes

          protected void doReadBytes(byte[] bytes,
                                     int start,
                                     int length)
                              throws IOException

      Reads `length` bytes into `bytes` starting at `start`.
      Throws:
        `EOFException` - If there are not enough number of bytes in the source.
        `IOException`

    - #### doReadItemCount

          protected long doReadItemCount()
                                  throws IOException

      Returns the number of items to follow in the current array or map. Returns 0 if there are no more items in the current array and the array/map has ended. Arrays are encoded as a series of blocks. Each block consists of a long count value, followed by that many array items. A block with count zero indicates the end of the array. If a block's count is negative, its absolute value is used, and the count is followed immediately by a long block size indicating the number of bytes in the block.
      Throws:
        `IOException` - If the first byte cannot be read for any reason other than the end of the file, if the input stream has been closed, or if some other I/O error occurs.

    - #### readArrayStart

          public long readArrayStart()
                              throws IOException

      Description copied from class: `Decoder`
      Reads and returns the size of the first block of an array. If this method returns non-zero, then the caller should read the indicated number of items, and then call `Decoder.arrayNext()` to find out the number of items in the next block. The typical pattern for consuming an array looks like:

             for(long i = in.readArrayStart(); i != 0; i = in.arrayNext()) {
               for (long j = 0; j < i; j++) {
                 read next element of the array;
               }
             }

      Specified by:
        `readArrayStart` in class `Decoder`
      Throws:
        `IOException`

    - #### arrayNext

          public long arrayNext()
                         throws IOException

      Description copied from class: `Decoder`
      Processes the next block of an array and returns the number of items in the block and let's the caller read those items.
      Specified by:
        `arrayNext` in class `Decoder`
      Throws:
        `IOException`

    - #### skipArray

          public long skipArray()
                         throws IOException

      Description copied from class: `Decoder`
      Used for quickly skipping through an array. Note you can either skip the entire array, or read the entire array (with `Decoder.readArrayStart()`), but you can't mix the two on the same array. This method will skip through as many items as it can, all of them if possible. It will return zero if there are no more items to skip through, or an item count if it needs the client's help in skipping. The typical usage pattern is:

             for(long i = in.skipArray(); i != 0; i = i.skipArray()) {
               for (long j = 0; j < i; j++) {
                 read and discard the next element of the array;
               }
             }

      Note that this method can automatically skip through items if a byte-count is found in the underlying data, or if a schema has been provided to the implementation, but otherwise the client will have to skip through items itself.
      Specified by:
        `skipArray` in class `Decoder`
      Throws:
        `IOException`

    - #### readMapStart

          public long readMapStart()
                            throws IOException

      Description copied from class: `Decoder`
      Reads and returns the size of the next block of map-entries. Similar to `Decoder.readArrayStart()`. As an example, let's say you want to read a map of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

           Map m = new HashMap();
           Record reuse = new Record();
           for (long i = in.readMapStart(); i != 0; i = in.readMapNext()) {
             for (long j = 0; j < i; j++) {
               String key = in.readString();
               reuse.intField = in.readInt();
               reuse.boolField = in.readBoolean();
               m.put(key, reuse);
             }
           }

      Specified by:
        `readMapStart` in class `Decoder`
      Throws:
        `IOException`

    - #### mapNext

          public long mapNext()
                       throws IOException

      Description copied from class: `Decoder`
      Processes the next block of map entries and returns the count of them. Similar to `Decoder.arrayNext()`. See `Decoder.readMapStart()` for details.
      Specified by:
        `mapNext` in class `Decoder`
      Throws:
        `IOException`

    - #### skipMap

          public long skipMap()
                       throws IOException

      Description copied from class: `Decoder`
      Support for quickly skipping through a map similar to `Decoder.skipArray()`. As an example, let's say you want to skip a map of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

           for (long i = in.skipMap(); i != 0; i = in.skipMap()) {
             for (long j = 0; j < i; j++) {
               in.skipString(); // Discard key
               in.readInt(); // Discard int-field of value
               in.readBoolean(); // Discard boolean-field of value
             }
           }

      Specified by:
        `skipMap` in class `Decoder`
      Throws:
        `IOException`

    - #### readIndex

          public int readIndex()
                        throws IOException

      Description copied from class: `Decoder`
      Reads the tag of a union written by `Encoder.writeIndex(int)`.
      Specified by:
        `readIndex` in class `Decoder`
      Throws:
        `IOException`

    - #### isEnd

          public boolean isEnd()
                        throws IOException

      Returns true if the current BinaryDecoder is at the end of its source data and cannot read any further without throwing an EOFException or other IOException.

      Not all implementations of BinaryDecoder support isEnd(). Implementations that do not support isEnd() will throw a `UnsupportedOperationException`.
      Throws:
        `IOException` - If the first byte cannot be read for any reason other than the end of the file, if the input stream has been closed, or if some other I/O error occurs.

    - #### inputStream

          public InputStream inputStream()

      Returns an `InputStream` that is aware of any buffering that may occur in this BinaryDecoder. Readers that need to interleave decoding Avro data with other reads must access this InputStream to do so unless the implementation is 'direct' and does not read beyond the minimum bytes necessary from the source.

Copyright © 2009–2024 The Apache Software Foundation. All rights reserved.