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
`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<String, Record> 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`