org.apache.avro.io
Class BinaryDecoder

java.lang.Object
  extended by org.apache.avro.io.Decoder
      extended by org.apache.avro.io.BinaryDecoder

public class BinaryDecoder
extends Decoder

An Decoder for binary-format data.

Instances are created using DecoderFactory.

This class may read-ahead and buffer bytes from the source beyond what is required to serve its read methods. See inputStream() and DecoderFactory.configureDirectDecoder(boolean). The number of unused bytes in the buffer can be accessed by inputStream().remaining(), if the BinaryDecoder is not 'direct'.

See Also:
Encoder

Constructor Summary
protected BinaryDecoder()
          protected constructor for child classes
  BinaryDecoder(InputStream in)
          Deprecated. Use DecoderFactory to create BinaryDecoder instances and reinitialize them
 
Method Summary
 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.
protected  void doReadBytes(byte[] bytes, int start, int length)
          Reads length bytes into bytes starting at start.
protected  long doReadItemCount()
          Returns the number of items to follow in the current array or map.
protected  void doSkipBytes(long length)
           
 void init(InputStream in)
          Deprecated. Use DecoderFactory to create BinaryDecoder instances and reinitialize them
 InputStream inputStream()
          Returns an InputStream that is aware of any buffering that may occur in this BinaryDecoder.
 boolean isEnd()
          Returns true if the current BinaryDecoder is at the end of its source data and cannot read any further without throwing an EOFException or other IOException.
 long mapNext()
          Processes the next block of map entries and returns the count of them.
 long readArrayStart()
          Reads and returns the size of the first block of an array.
 boolean readBoolean()
          Reads a boolean value written by Encoder.writeBoolean(boolean).
 ByteBuffer readBytes(ByteBuffer old)
          Reads a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).
 double readDouble()
          Reads a double written by Encoder.writeDouble(double).
 int readEnum()
          Reads an enumeration.
 void readFixed(byte[] bytes, int start, int length)
          Reads fixed sized binary object.
 float readFloat()
          Reads a float written by Encoder.writeFloat(float).
 int readIndex()
          Reads the tag of a union written by Encoder.writeIndex(int).
 int readInt()
          Reads an integer written by Encoder.writeInt(int).
 long readLong()
          Reads a long written by Encoder.writeLong(long).
 long readMapStart()
          Reads and returns the size of the next block of map-entries.
 void readNull()
          "Reads" a null value.
 Utf8 readString(Utf8 old)
          Reads a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).
 long skipArray()
          Used for quickly skipping through an array.
 void skipBytes()
          Discards a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).
 void skipFixed(int length)
          Discards fixed sized binary object.
 long skipMap()
          Support for quickly skipping through a map similar to Decoder.skipArray().
 void skipString()
          Discards a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).
 
Methods inherited from class org.apache.avro.io.Decoder
readFixed
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BinaryDecoder

protected BinaryDecoder()
protected constructor for child classes


BinaryDecoder

@Deprecated
public BinaryDecoder(InputStream in)
Deprecated. Use DecoderFactory to create BinaryDecoder instances and reinitialize them

Method Detail

init

@Deprecated
public void init(InputStream in)
Deprecated. Use DecoderFactory to create BinaryDecoder instances and reinitialize them

Description copied from class: Decoder
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.

Specified by:
init in class Decoder

readNull

public void readNull()
              throws IOException
Description copied from class: Decoder
"Reads" a null value. (Doesn't actually read anything, but advances the state of the parser if the implementation is stateful.)

Specified by:
readNull in class Decoder
Throws:
IOException

readBoolean

public boolean readBoolean()
                    throws IOException
Description copied from class: Decoder
Reads a boolean value written by Encoder.writeBoolean(boolean).

Specified by:
readBoolean in class Decoder
Throws:
IOException

readInt

public int readInt()
            throws IOException
Description copied from class: Decoder
Reads an integer written by Encoder.writeInt(int).

Specified by:
readInt in class Decoder
Throws:
IOException

readLong

public long readLong()
              throws IOException
Description copied from class: Decoder
Reads a long written by Encoder.writeLong(long).

Specified by:
readLong in class Decoder
Throws:
IOException

readFloat

public float readFloat()
                throws IOException
Description copied from class: Decoder
Reads a float written by Encoder.writeFloat(float).

Specified by:
readFloat in class Decoder
Throws:
IOException

readDouble

public double readDouble()
                  throws IOException
Description copied from class: Decoder
Reads a double written by Encoder.writeDouble(double).

Specified by:
readDouble in class Decoder
Throws:
IOException

readString

public Utf8 readString(Utf8 old)
                throws IOException
Description copied from class: Decoder
Reads a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).

Specified by:
readString in class Decoder
Throws:
IOException

skipString

public void skipString()
                throws IOException
Description copied from class: Decoder
Discards a char-string written by Encoder.writeString(org.apache.avro.util.Utf8).

Specified by:
skipString in class Decoder
Throws:
IOException

readBytes

public ByteBuffer readBytes(ByteBuffer old)
                     throws IOException
Description copied from class: Decoder
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.

Specified by:
readBytes in class Decoder
Throws:
IOException

skipBytes

public void skipBytes()
               throws IOException
Description copied from class: Decoder
Discards a byte-string written by Encoder.writeBytes(java.nio.ByteBuffer).

Specified by:
skipBytes in class Decoder
Throws:
IOException

readFixed

public void readFixed(byte[] bytes,
                      int start,
                      int length)
               throws IOException
Description copied from class: Decoder
Reads fixed sized binary object.

Specified by:
readFixed in class Decoder
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:
IOException

skipFixed

public void skipFixed(int length)
               throws IOException
Description copied from class: Decoder
Discards fixed sized binary object.

Specified by:
skipFixed in class Decoder
Parameters:
length - The size of the binary object to be skipped.
Throws:
IOException

readEnum

public int readEnum()
             throws IOException
Description copied from class: Decoder
Reads an enumeration.

Specified by:
readEnum in class Decoder
Returns:
The enumeration's value.
Throws:
IOException

doSkipBytes

protected void doSkipBytes(long length)
                    throws IOException
Throws:
IOException

doReadBytes

protected void doReadBytes(byte[] bytes,
                           int start,
                           int length)
                    throws IOException
Reads length bytes into bytes starting at start.

Throws:
EOFException - If there are not enough number of bytes in the source.
IOException

doReadItemCount

protected long doReadItemCount()
                        throws IOException
Returns the number of items to follow in the current array or map. Returns 0 if there are no more items in the current array and the array/map has ended.

Throws:
IOException

readArrayStart

public long readArrayStart()
                    throws IOException
Description copied from class: Decoder
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 Decoder.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;
     }
   }
 

Specified by:
readArrayStart in class Decoder
Throws:
IOException

arrayNext

public long arrayNext()
               throws IOException
Description copied from class: Decoder
Processes the next block of an array andreturns the number of items in the block and let's the caller read those items.

Specified by:
arrayNext in class Decoder
Throws:
IOException

skipArray

public long skipArray()
               throws IOException
Description copied from class: Decoder
Used for quickly skipping through an array. Note you can either skip the entire array, or read the entire array (with Decoder.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.

Specified by:
skipArray in class Decoder
Throws:
IOException

readMapStart

public long readMapStart()
                  throws IOException
Description copied from class: Decoder
Reads and returns the size of the next block of map-entries. Similar to Decoder.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);
     }
   }
 

Specified by:
readMapStart in class Decoder
Throws:
IOException

mapNext

public long mapNext()
             throws IOException
Description copied from class: Decoder
Processes the next block of map entries and returns the count of them. Similar to Decoder.arrayNext(). See Decoder.readMapStart() for details.

Specified by:
mapNext in class Decoder
Throws:
IOException

skipMap

public long skipMap()
             throws IOException
Description copied from class: Decoder
Support for quickly skipping through a map similar to Decoder.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
     }
   }
 

Specified by:
skipMap in class Decoder
Throws:
IOException

readIndex

public int readIndex()
              throws IOException
Description copied from class: Decoder
Reads the tag of a union written by Encoder.writeIndex(int).

Specified by:
readIndex in class Decoder
Throws:
IOException

isEnd

public boolean isEnd()
              throws IOException
Returns true if the current BinaryDecoder is at the end of its source data and cannot read any further without throwing an EOFException or other IOException.

Not all implementations of BinaryDecoder support isEnd(). Implementations that do not support isEnd() will throw a UnsupportedOperationException.

Throws:
IOException

inputStream

public InputStream inputStream()
Returns an InputStream that is aware of any buffering that may occur in this BinaryDecoder. Readers that need to interleave decoding Avro data with other reads must access this InputStream to do so unless the implementation is 'direct' and does not read beyond the minimum bytes necessary from the source.

See DecoderFactory.configureDirectDecoder(boolean)



Copyright © 2010 The Apache Software Foundation