org.apache.avro.io
Class Encoder

java.lang.Object
  extended by 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
Encoder()
           
 
Method Summary
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.
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

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 © 2011 The Apache Software Foundation. All Rights Reserved.