org.apache.avro.io

## Class BlockingBinaryEncoder

- java.lang.Object
- - org.apache.avro.io.Encoder
  - - org.apache.avro.io.BinaryEncoder
    - - org.apache.avro.io.BufferedBinaryEncoder
      - - org.apache.avro.io.BlockingBinaryEncoder

- All Implemented Interfaces:
    Flushable

      public class BlockingBinaryEncoder
      extends BufferedBinaryEncoder

  A `BinaryEncoder` implementation that writes large arrays and maps as a sequence of blocks. So long as individual primitive values fit in memory, arbitrarily long arrays and maps may be written and subsequently read without exhausting memory. Values are buffered until the specified block size would be exceeded, minimizing block overhead.

  Use `EncoderFactory.blockingBinaryEncoder(OutputStream, BinaryEncoder)` to construct and configure.

  BlockingBinaryEncoder buffers writes, data may not appear on the output until `flush()` is called.

  BlockingBinaryEncoder is not thread-safe
  See Also:
    `BinaryEncoder`, `EncoderFactory`, `Encoder`

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `bytesBuffered()` Returns the number of bytes currently buffered by this encoder.
    `void` | `flush()`
    `void` | `setItemCount(long itemCount)` Call this method before writing a batch of items in an array or a map.
    `void` | `startItem()` Start a new item of an array or map.
    `void` | `writeArrayEnd()` Call this method to finish writing an array.
    `void` | `writeArrayStart()` Call this method to start writing an array.
    `void` | `writeBoolean(boolean b)` Write a boolean value.
    `void` | `writeDouble(double d)` Write a double.
    `void` | `writeFixed(byte[] bytes, int start, int len)` Writes a fixed size binary object.
    `void` | `writeFixed(ByteBuffer bytes)` Writes a fixed from a ByteBuffer.
    `void` | `writeFloat(float f)` Write a float.
    `void` | `writeIndex(int unionIndex)` Call this method to write the tag of a union.
    `void` | `writeInt(int n)` Writes a 32-bit integer.
    `void` | `writeLong(long n)` Write a 64-bit integer.
    `void` | `writeMapEnd()` Call this method to terminate the inner-most, currently-opened map.
    `void` | `writeMapStart()` Call this to start a new map.
    `protected void` | `writeZero()` Write a zero byte to the underlying output.

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

      `writeBytes, writeBytes, writeEnum, writeNull, writeString, writeString`

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

      `writeBytes, writeFixed, writeString`

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

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

- - ### Method Detail

    - #### flush

          public void flush()
                     throws IOException

      Specified by:
        `flush` in interface `Flushable`
      Overrides:
        `flush` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeBoolean

          public void writeBoolean(boolean b)
                            throws IOException

      Description copied from class: `Encoder`
      Write a boolean value.
      Overrides:
        `writeBoolean` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeInt

          public void writeInt(int n)
                        throws IOException

      Description copied from class: `Encoder`
      Writes a 32-bit integer.
      Overrides:
        `writeInt` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeLong

          public void writeLong(long n)
                         throws IOException

      Description copied from class: `Encoder`
      Write a 64-bit integer.
      Overrides:
        `writeLong` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeFloat

          public void writeFloat(float f)
                          throws IOException

      Description copied from class: `Encoder`
      Write a float.
      Overrides:
        `writeFloat` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeDouble

          public void writeDouble(double d)
                           throws IOException

      Description copied from class: `Encoder`
      Write a double.
      Overrides:
        `writeDouble` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeFixed

          public void writeFixed(byte[] bytes,
                                 int start,
                                 int len)
                          throws IOException

      Description copied from class: `Encoder`
      Writes a fixed size binary object.
      Overrides:
        `writeFixed` in class `BufferedBinaryEncoder`
      Parameters:
        `bytes` - The contents to write
        `start` - The position within `bytes` where the contents start.
        `len` - The number of bytes to write.
      Throws:
        `IOException`

    - #### writeFixed

          public void writeFixed(ByteBuffer bytes)
                          throws IOException

      Description copied from class: `Encoder`
      Writes a fixed from a ByteBuffer.
      Overrides:
        `writeFixed` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeZero

          protected void writeZero()
                            throws IOException

      Description copied from class: `BinaryEncoder`
      Write a zero byte to the underlying output.
      Overrides:
        `writeZero` in class `BufferedBinaryEncoder`
      Throws:
        `IOException`

    - #### writeArrayStart

          public void writeArrayStart()
                               throws IOException

      Description copied from class: `Encoder`
      Call this method to start writing an array. When starting to serialize an array, call `Encoder.writeArrayStart()`. Then, before writing any data for any item call `Encoder.setItemCount(long)` followed by a sequence of `Encoder.startItem()` and the item itself. The number of `Encoder.startItem()` should match the number specified in `Encoder.setItemCount(long)`. When actually writing the data of the item, you can call any `Encoder` method (e.g., `Encoder.writeLong(long)`). When all items of the array have been written, call `Encoder.writeArrayEnd()`. As an example, let's say you want to write an array of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

           out.writeArrayStart();
           out.setItemCount(list.size());
           for (Record r : list) {
             out.startItem();
             out.writeLong(r.longField);
             out.writeBoolean(r.boolField);
           }
           out.writeArrayEnd();

      Overrides:
        `writeArrayStart` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### setItemCount

          public void setItemCount(long itemCount)
                            throws IOException

      Description copied from class: `Encoder`
      Call this method before writing a batch of items in an array or a map. Then for each item, call `Encoder.startItem()` followed by any of the other write methods of `Encoder`. The number of calls to `Encoder.startItem()` must be equal to the count specified in `Encoder.setItemCount(long)`. Once a batch is completed you can start another batch with `Encoder.setItemCount(long)`.
      Overrides:
        `setItemCount` in class `BinaryEncoder`
      Parameters:
        `itemCount` - The number of `Encoder.startItem()` calls to follow.
      Throws:
        `IOException`

    - #### startItem

          public void startItem()
                         throws IOException

      Description copied from class: `Encoder`
      Start a new item of an array or map. See `Encoder.writeArrayStart()` for usage information.
      Overrides:
        `startItem` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### writeArrayEnd

          public void writeArrayEnd()
                             throws IOException

      Description copied from class: `Encoder`
      Call this method to finish writing an array. See `Encoder.writeArrayStart()` for usage information.
      Overrides:
        `writeArrayEnd` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### writeMapStart

          public void writeMapStart()
                             throws IOException

      Description copied from class: `Encoder`
      Call this to start a new map. See `Encoder.writeArrayStart()` for details on usage. As an example of usage, let's say you want to write a map of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

           out.writeMapStart();
           out.setItemCount(list.size());
           for (Map.Entry entry : map.entrySet()) {
             out.startItem();
             out.writeString(entry.getKey());
             out.writeLong(entry.getValue().longField);
             out.writeBoolean(entry.getValue().boolField);
           }
           out.writeMapEnd();

      Overrides:
        `writeMapStart` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### writeMapEnd

          public void writeMapEnd()
                           throws IOException

      Description copied from class: `Encoder`
      Call this method to terminate the inner-most, currently-opened map. See `Encoder.writeArrayStart()` for more details.
      Overrides:
        `writeMapEnd` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### writeIndex

          public void writeIndex(int unionIndex)
                          throws IOException

      Description copied from class: `Encoder`
      Call this method to write the tag of a union. As an example of usage, let's say you want to write a union, whose second branch is a record consisting of an Long field and a Boolean field. Your code would look something like this:

           out.writeIndex(1);
           out.writeLong(record.longField);
           out.writeBoolean(record.boolField);

      Overrides:
        `writeIndex` in class `BinaryEncoder`
      Throws:
        `IOException`

    - #### bytesBuffered

          public int bytesBuffered()

      Description copied from class: `BinaryEncoder`
      Returns the number of bytes currently buffered by this encoder. If this Encoder does not buffer, this will always return zero.

      Call `Flushable.flush()` to empty the buffer to the underlying output.
      Overrides:
        `bytesBuffered` in class `BufferedBinaryEncoder`

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