Package 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
Description
`Encoder()`

## Method Summary

Modifier and Type
Method
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 Details

### Encoder

public Encoder()

## Method Details

### 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.)

### writeBoolean

public abstract void writeBoolean(boolean b) throws IOException
Write a boolean value.

### writeInt

public abstract void writeInt(int n) throws IOException
Writes a 32-bit integer.

### writeLong

public abstract void writeLong(long n) throws IOException
Write a 64-bit integer.

### writeFloat

public abstract void writeFloat(float f) throws IOException
Write a float.

### writeDouble

public abstract void writeDouble(double d) throws IOException
Write a double.

### writeString

public abstract void writeString(Utf8 utf8) throws IOException
Write a Unicode character string.

### 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.

### 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.

### writeBytes

public abstract void writeBytes(ByteBuffer bytes) throws IOException
Write a byte string.

### writeBytes

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

### writeBytes

public void writeBytes(byte[] bytes) throws IOException
Writes a byte string. Equivalent to `writeBytes(bytes, 0, bytes.length)`

### 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.

### writeFixed

public void writeFixed(byte[] bytes) throws IOException
A shorthand for `writeFixed(bytes, 0, bytes.length)`

Parameters:
  `bytes` - the data
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` - the enumeration to write

### 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 a 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();

### 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.

### writeArrayEnd

public abstract void writeArrayEnd() throws IOException
Call this method to finish writing an array. See `writeArrayStart()` for usage information.

### 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 a Long field and a Boolean field. Your code would look something like this:

     out.writeMapStart();
     out.setItemCount(list.size());
     for (Map.Entryinvalid input: '<'String, Record> entry : map.entrySet()) {
       out.startItem();
       out.writeString(entry.getKey());
       out.writeLong(entry.getValue().longField);
       out.writeBoolean(entry.getValue().boolField);
     }
     out.writeMapEnd();

### writeMapEnd

public abstract void writeMapEnd() throws IOException
Call this method to terminate the inner-most, currently-opened map. See `writeArrayStart()` for more details.

### 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 a Long field and a Boolean field. Your code would look something like this:

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