org.apache.avro.io
Class Decoder

java.lang.Object
  org.apache.avro.io.Decoder

Direct Known Subclasses:

BinaryDecoder, ParsingDecoder

public abstract class Decoder
extends Object

Low-level support for de-serializing Avro values.

This class has two types of methods. One type of methods support the reading of leaf values (for example, readLong() and readString(org.apache.avro.util.Utf8)). The other type of methods support the reading of maps and arrays. These methods are readArrayStart(), arrayNext(), and similar methods for maps). See readArrayStart() for details on these methods.)

See Also:

Encoder

Constructor Summary

Decoder()

Method Summary

abstract long	arrayNext() Processes the next block of an array andreturns the number of items in the block and let's the caller read those items.
abstract void	init(InputStream in) Start reading against a different input stream.
abstract long	mapNext() Processes the next block of map entries and returns the count of them.
abstract long	readArrayStart() Reads and returns the size of the first block of an array.
abstract boolean	readBoolean() Reads a boolean value written by Encoder.writeBoolean(boolean).
abstract ByteBuffer	readBytes(ByteBuffer old) Reads a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).
abstract double	readDouble() Reads a double written by Encoder.writeDouble(double).
abstract int	readEnum() Reads an enumeration.
void	readFixed(byte[] bytes) A shorthand for readFixed(bytes, 0, bytes.length).
abstract void	readFixed(byte[] bytes, int start, int length) Reads fixed sized binary object.
abstract float	readFloat() Reads a float written by Encoder.writeFloat(float).
abstract int	readIndex() Reads the tag of a union written by Encoder.writeIndex(int).
abstract int	readInt() Reads an integer written by Encoder.writeInt(int).
abstract long	readLong() Reads a long written by Encoder.writeLong(long).
abstract long	readMapStart() Reads and returns the size of the next block of map-entries.
abstract void	readNull() "Reads" a null value.
abstract Utf8	readString(Utf8 old) Reads a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).
abstract long	skipArray() Used for quickly skipping through an array.
abstract void	skipBytes() Discards a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).
abstract void	skipFixed(int length) Discards fixed sized binary object.
abstract long	skipMap() Support for quickly skipping through a map similar to skipArray().
abstract void	skipString() Discards a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Decoder

public Decoder()

Method Detail

init

public abstract void init(InputStream in)
                   throws IOException

Start reading against a different input stream. Stateful subclasses will reset their states to their initial state.

A Decoder may read ahead beyond the minimum bytes necessary, similar to a BufferedInputStream. In order to interleave reads on this stream's data between Decoder and another reader, the other reader must use the buffer-aware input stream returned by the Decoder implementation, if applicable.

Throws:

IOException

readNull

public abstract void readNull()
                       throws IOException

"Reads" a null value. (Doesn't actually read anything, but advances the state of the parser if the implementation is stateful.)

Throws:

AvroTypeException - If this is a stateful reader and null is not the type of the next value to be read

IOException

readBoolean

public abstract boolean readBoolean()
                             throws IOException

Reads a boolean value written by Encoder.writeBoolean(boolean).

Throws:

AvroTypeException - If this is a stateful reader and boolean is not the type of the next value to be read

IOException

readInt

public abstract int readInt()
                     throws IOException

Reads an integer written by Encoder.writeInt(int).

Throws:

AvroTypeException - If encoded value is larger than 32-bits

AvroTypeException - If this is a stateful reader and int is not the type of the next value to be read

IOException

readLong

public abstract long readLong()
                       throws IOException

Reads a long written by Encoder.writeLong(long).

Throws:

AvroTypeException - If this is a stateful reader and long is not the type of the next value to be read

IOException

readFloat

public abstract float readFloat()
                         throws IOException

Reads a float written by Encoder.writeFloat(float).

Throws:

AvroTypeException - If this is a stateful reader and is not the type of the next value to be read

IOException

readDouble

public abstract double readDouble()
                           throws IOException

Reads a double written by Encoder.writeDouble(double).

Throws:

AvroTypeException - If this is a stateful reader and is not the type of the next value to be read

IOException

readString

public abstract Utf8 readString(Utf8 old)
                         throws IOException

Reads a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).

Throws:

AvroTypeException - If this is a stateful reader and char-string is not the type of the next value to be read

IOException

skipString

public abstract void skipString()
                         throws IOException

Discards a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).

Throws:

AvroTypeException - If this is a stateful reader and char-string is not the type of the next value to be read

IOException

readBytes

public abstract ByteBuffer readBytes(ByteBuffer old)
                              throws IOException

Reads a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer). if old is not null and has sufficient capacity to take in the bytes being read, the bytes are returned in old.

Throws:

AvroTypeException - If this is a stateful reader and byte-string is not the type of the next value to be read

IOException

skipBytes

public abstract void skipBytes()
                        throws IOException

Discards a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).

Throws:

AvroTypeException - If this is a stateful reader and byte-string is not the type of the next value to be read

IOException

readFixed

public abstract void readFixed(byte[] bytes,
                               int start,
                               int length)
                        throws IOException

Reads fixed sized binary object.

Parameters:

bytes - The buffer to store the contents being read.

start - The position where the data needs to be written.

length - The size of the binary object.

Throws:

AvroTypeException - If this is a stateful reader and fixed sized binary object is not the type of the next value to be read or the length is incorrect.

IOException

readFixed

public void readFixed(byte[] bytes)
               throws IOException

A shorthand for readFixed(bytes, 0, bytes.length).

Throws:

AvroTypeException - If this is a stateful reader and fixed sized binary object is not the type of the next value to be read or the length is incorrect.

IOException

skipFixed

public abstract void skipFixed(int length)
                        throws IOException

Discards fixed sized binary object.

Parameters:

length - The size of the binary object to be skipped.

Throws:

AvroTypeException - If this is a stateful reader and fixed sized binary object is not the type of the next value to be read or the length is incorrect.

IOException

readEnum

public abstract int readEnum()
                      throws IOException

Reads an enumeration.

Returns:

The enumeration's value.

Throws:

AvroTypeException - If this is a stateful reader and enumeration is not the type of the next value to be read.

IOException

readArrayStart

public abstract long readArrayStart()
                             throws IOException

Reads and returns the size of the first block of an array. If this method returns non-zero, then the caller should read the indicated number of items, and then call arrayNext() to find out the number of items in the next block. The typical pattern for consuming an array looks like:

   for(long i = in.readArrayStart(); i != 0; i = in.arrayNext()) {
     for (long j = 0; j < i; j++) {
       read next element of the array;
     }
   }
 

Throws:

AvroTypeException - If this is a stateful reader and array is not the type of the next value to be read

IOException

arrayNext

public abstract long arrayNext()
                        throws IOException

Processes the next block of an array andreturns the number of items in the block and let's the caller read those items.

Throws:

AvroTypeException - When called outside of an array context

IOException

skipArray

public abstract long skipArray()
                        throws IOException

Used for quickly skipping through an array. Note you can either skip the entire array, or read the entire array (with readArrayStart()), but you can't mix the two on the same array. This method will skip through as many items as it can, all of them if possible. It will return zero if there are no more items to skip through, or an item count if it needs the client's help in skipping. The typical usage pattern is:

   for(long i = in.skipArray(); i != 0; i = i.skipArray()) {
     for (long j = 0; j < i; j++) {
       read and discard the next element of the array;
     }
   }
 

Note that this method can automatically skip through items if a byte-count is found in the underlying data, or if a schema has been provided to the implementation, but otherwise the client will have to skip through items itself.

Throws:

AvroTypeException - If this is a stateful reader and array is not the type of the next value to be read

IOException

readMapStart

public abstract long readMapStart()
                           throws IOException

Reads and returns the size of the next block of map-entries. Similar to readArrayStart(). As an example, let's say you want to read a map of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

   Map m = new HashMap();
   Record reuse = new Record();
   for(long i = in.readMapStart(); i != 0; i = in.readMapNext()) {
     for (long j = 0; j < i; j++) {
       String key = in.readString();
       reuse.intField = in.readInt();
       reuse.boolField = in.readBoolean();
       m.put(key, reuse);
     }
   }
 

Throws:

AvroTypeException - If this is a stateful reader and map is not the type of the next value to be read

IOException

mapNext

public abstract long mapNext()
                      throws IOException

Processes the next block of map entries and returns the count of them. Similar to arrayNext(). See readMapStart() for details.

Throws:

AvroTypeException - When called outside of a map context

IOException

skipMap

public abstract long skipMap()
                      throws IOException

Support for quickly skipping through a map similar to skipArray(). As an example, let's say you want to skip a map of records, the record consisting of an Long field and a Boolean field. Your code would look something like this:

   for(long i = in.skipMap(); i != 0; i = in.skipMap()) {
     for (long j = 0; j < i; j++) {
       in.skipString();  // Discard key
       in.readInt(); // Discard int-field of value
       in.readBoolean(); // Discard boolean-field of value
     }
   }
 

Throws:

AvroTypeException - If this is a stateful reader and array is not the type of the next value to be read

IOException

readIndex

public abstract int readIndex()
                       throws IOException

Reads the tag of a union written by Encoder.writeIndex(int).

Throws:

AvroTypeException - If this is a stateful reader and union is not the type of the next value to be read

IOException