org.apache.avro.io
Class Decoder

java.lang.Object
  extended by 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


Copyright © 2010 The Apache Software Foundation