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 -

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 -

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

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