org.apache.avro.io

## Class Encoder

- java.lang.Object
- - org.apache.avro.io.Encoder

- All Implemented Interfaces:
    Flushable
  Direct Known Subclasses:
    BinaryEncoder, ParsingEncoder

      public abstract class Encoder
      extends Object
      implements Flushable

  Low-level support for serializing Avro values.

  This class has two types of methods. One type of methods support the writing of leaf values (for example, `writeLong(long)` and `writeString(org.apache.avro.util.Utf8)`). These methods have analogs in `Decoder`.

  The other type of methods support the writing of maps and arrays. These methods are `writeArrayStart()`, `startItem()`, and `writeArrayEnd()` (and similar methods for maps). Some implementations of `Encoder` handle the buffering required to break large maps and arrays into blocks, which is necessary for applications that want to do streaming. (See `writeArrayStart()` for details on these methods.)

  `EncoderFactory` contains Encoder construction and configuration facilities.
  See Also:
    `EncoderFactory`, `Decoder`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Encoder()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `setItemCount(long itemCount)` Call this method before writing a batch of items in an array or a map.
    `abstract void` | `startItem()` Start a new item of an array or map.
    `abstract void` | `writeArrayEnd()` Call this method to finish writing an array.
    `abstract void` | `writeArrayStart()` Call this method to start writing an array.
    `abstract void` | `writeBoolean(boolean b)` Write a boolean value.
    `void` | `writeBytes(byte[] bytes)` Writes a byte string.
    `abstract void` | `writeBytes(byte[] bytes, int start, int len)` Write a byte string.
    `abstract void` | `writeBytes(ByteBuffer bytes)` Write a byte string.
    `abstract void` | `writeDouble(double d)` Write a double.
    `abstract void` | `writeEnum(int e)` Writes an enumeration.
    `void` | `writeFixed(byte[] bytes)` A shorthand for `writeFixed(bytes, 0, bytes.length)`
    `abstract void` | `writeFixed(byte[] bytes, int start, int len)` Writes a fixed size binary object.
    `void` | `writeFixed(ByteBuffer bytes)` Writes a fixed from a ByteBuffer.
    `abstract void` | `writeFloat(float f)` Write a float.
    `abstract void` | `writeIndex(int unionIndex)` Call this method to write the tag of a union.
    `abstract void` | `writeInt(int n)` Writes a 32-bit integer.
    `abstract void` | `writeLong(long n)` Write a 64-bit integer.
    `abstract void` | `writeMapEnd()` Call this method to terminate the inner-most, currently-opened map.
    `abstract void` | `writeMapStart()` Call this to start a new map.
    `abstract void` | `writeNull()` "Writes" a null value.
    `void` | `writeString(CharSequence charSequence)` Write a Unicode character string.
    `void` | `writeString(String str)` Write a Unicode character string.
    `abstract void` | `writeString(Utf8 utf8)` Write a Unicode character string.

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

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

    - ### Methods inherited from interface java.io.Flushable

      `flush`

- - ### Constructor Detail

    - #### Encoder

          public Encoder()

  - ### Method Detail

    - #### writeNull

          public abstract void writeNull()
                                  throws IOException

      "Writes" a null value. (Doesn't actually write anything, but advances the state of the parser if this class is stateful.)
      Throws:
        `AvroTypeException` - If this is a stateful writer and a null is not expected
        `IOException`

    - #### writeBoolean

          public abstract void writeBoolean(boolean b)
                                     throws IOException

      Write a boolean value.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a boolean is not expected
        `IOException`

    - #### writeInt

          public abstract void writeInt(int n)
                                 throws IOException

      Writes a 32-bit integer.
      Throws:
        `AvroTypeException` - If this is a stateful writer and an integer is not expected
        `IOException`

    - #### writeLong

          public abstract void writeLong(long n)
                                  throws IOException

      Write a 64-bit integer.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a long is not expected
        `IOException`

    - #### writeFloat

          public abstract void writeFloat(float f)
                                   throws IOException

      Write a float.
      Throws:
        `IOException`
        `AvroTypeException` - If this is a stateful writer and a float is not expected

    - #### writeDouble

          public abstract void writeDouble(double d)
                                    throws IOException

      Write a double.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a double is not expected
        `IOException`

    - #### writeString

          public abstract void writeString(Utf8 utf8)
                                    throws IOException

      Write a Unicode character string.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a char-string is not expected
        `IOException`

    - #### writeString

          public void writeString(String str)
                           throws IOException

      Write a Unicode character string. The default implementation converts the String to a `Utf8`. Some Encoder implementations may want to do something different as a performance optimization.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a char-string is not expected
        `IOException`

    - #### writeString

          public void writeString(CharSequence charSequence)
                           throws IOException

      Write a Unicode character string. If the CharSequence is an `Utf8` it writes this directly, otherwise the CharSequence is converted to a String via toString() and written.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a char-string is not expected
        `IOException`

    - #### writeBytes

          public abstract void writeBytes(ByteBuffer bytes)
                                   throws IOException

      Write a byte string.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a byte-string is not expected
        `IOException`

    - #### writeBytes

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

      Write a byte string.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a byte-string is not expected
        `IOException`

    - #### writeBytes

          public void writeBytes(byte[] bytes)
                          throws IOException

      Writes a byte string. Equivalent to `writeBytes(bytes, 0, bytes.length)`
      Throws:
        `IOException`
        `AvroTypeException` - If this is a stateful writer and a byte-string is not expected

    - #### writeFixed

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

      Writes a fixed size binary object.
      Parameters:
        `bytes` - The contents to write
        `start` - The position within `bytes` where the contents start.
        `len` - The number of bytes to write.
      Throws:
        `AvroTypeException` - If this is a stateful writer and a byte-string is not expected
        `IOException`

    - #### writeFixed

          public void writeFixed(byte[] bytes)
                          throws IOException

      A shorthand for `writeFixed(bytes, 0, bytes.length)`
      Parameters:
        `bytes` -
      Throws:
        `IOException`

    - #### writeFixed

          public void writeFixed(ByteBuffer bytes)
                          throws IOException

      Writes a fixed from a ByteBuffer.
      Throws:
        `IOException`

    - #### writeEnum

          public abstract void writeEnum(int e)
                                  throws IOException

      Writes an enumeration.
      Parameters:
        `e` -
      Throws:
        `AvroTypeException` - If this is a stateful writer and an enumeration is not expected or the `e` is out of range.
        `IOException`

    - #### writeArrayStart

          public abstract void writeArrayStart()
                                        throws IOException

      Call this method to start writing an array. When starting to serialize an array, call `writeArrayStart()`. Then, before writing any data for any item call `setItemCount(long)` followed by a sequence of `startItem()` and the item itself. The number of `startItem()` should match the number specified in `setItemCount(long)`. When actually writing the data of the item, you can call any `Encoder` method (e.g., `writeLong(long)`). When all items of the array have been written, call `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();

      Throws:
        `AvroTypeException` - If this is a stateful writer and an array is not expected
        `IOException`

    - #### setItemCount

          public abstract void setItemCount(long itemCount)
                                     throws IOException

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

    - #### startItem

          public abstract void startItem()
                                  throws IOException

      Start a new item of an array or map. See `writeArrayStart()` for usage information.
      Throws:
        `AvroTypeException` - If called outside of an array or map context
        `IOException`

    - #### writeArrayEnd

          public abstract void writeArrayEnd()
                                      throws IOException

      Call this method to finish writing an array. See `writeArrayStart()` for usage information.
      Throws:
        `AvroTypeException` - If items written does not match count provided to `writeArrayStart()`
        `AvroTypeException` - If not currently inside an array
        `IOException`

    - #### writeMapStart

          public abstract void writeMapStart()
                                      throws IOException

      Call this to start a new map. See `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();

      Throws:
        `AvroTypeException` - If this is a stateful writer and a map is not expected
        `IOException`

    - #### writeMapEnd

          public abstract void writeMapEnd()
                                    throws IOException

      Call this method to terminate the inner-most, currently-opened map. See `writeArrayStart()` for more details.
      Throws:
        `AvroTypeException` - If items written does not match count provided to `writeMapStart()`
        `AvroTypeException` - If not currently inside a map
        `IOException`

    - #### writeIndex

          public abstract void writeIndex(int unionIndex)
                                   throws IOException

      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);

      Throws:
        `AvroTypeException` - If this is a stateful writer and a map is not expected
        `IOException`

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