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

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) A version of writeFixed for ByteBuffers.
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

A version of writeFixed for ByteBuffers.

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