https://avro.apache.org: Avro core components (The Apache Software Foundation) 
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.avro.io;

import java.io.IOException;
import java.nio.ByteBuffer;

import org.apache.avro.util.Utf8;


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). 
 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.) 
 DecoderFactory contains Decoder construction and configuration facilities. 
See Also:
/**
 * Low-level support for de-serializing Avro values.
 * <p/>
 * This class has two types of methods. One type of methods support the reading
 * of leaf values (for example, {@link #readLong} and {@link #readString}).
 * <p/>
 * The other type of methods support the reading of maps and arrays. These
 * methods are {@link #readArrayStart}, {@link #arrayNext}, and similar methods
 * for maps). See {@link #readArrayStart} for details on these methods.)
 * <p/>
 * {@link DecoderFactory} contains Decoder construction and configuration
 * facilities.
 * 
 * @see DecoderFactory
 * @see Encoder
 */

public abstract class Decoder {

  
"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
/**
   * "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
   */
  public abstract void readNull() throws IOException;

  
Reads a boolean value written by Encoder.writeBoolean. 
Throws:
  • AvroTypeException – If this is a stateful reader and boolean is not the
                          type of the next value to be read
/**
   * Reads a boolean value written by {@link Encoder#writeBoolean}.
   * 
   * @throws AvroTypeException If this is a stateful reader and boolean is not the
   *                           type of the next value to be read
   */

  public abstract boolean readBoolean() throws IOException;

  
Reads an integer written by Encoder.writeInt. 
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
/**
   * Reads an integer written by {@link Encoder#writeInt}.
   * 
   * @throws AvroTypeException If encoded value is larger than 32-bits
   * @throws AvroTypeException If this is a stateful reader and int is not the
   *                           type of the next value to be read
   */
  public abstract int readInt() throws IOException;

  
Reads a long written by Encoder.writeLong. 
Throws:
  • AvroTypeException – If this is a stateful reader and long is not the
                          type of the next value to be read
/**
   * Reads a long written by {@link Encoder#writeLong}.
   * 
   * @throws AvroTypeException If this is a stateful reader and long is not the
   *                           type of the next value to be read
   */
  public abstract long readLong() throws IOException;

  
Reads a float written by Encoder.writeFloat. 
Throws:
  • AvroTypeException – If this is a stateful reader and is not the type of
                          the next value to be read
/**
   * Reads a float written by {@link Encoder#writeFloat}.
   * 
   * @throws AvroTypeException If this is a stateful reader and is not the type of
   *                           the next value to be read
   */
  public abstract float readFloat() throws IOException;

  
Reads a double written by Encoder.writeDouble. 
Throws:
  • AvroTypeException – If this is a stateful reader and is not the type of
                          the next value to be read
/**
   * Reads a double written by {@link Encoder#writeDouble}.
   * 
   * @throws AvroTypeException If this is a stateful reader and is not the type of
   *                           the next value to be read
   */
  public abstract double readDouble() throws IOException;

  
Reads a char-string written by Encoder.writeString. 
Throws:
  • AvroTypeException – If this is a stateful reader and char-string is not
                          the type of the next value to be read
/**
   * Reads a char-string written by {@link Encoder#writeString}.
   * 
   * @throws AvroTypeException If this is a stateful reader and char-string is not
   *                           the type of the next value to be read
   */
  public abstract Utf8 readString(Utf8 old) throws IOException;

  
Reads a char-string written by Encoder.writeString. 
Throws:
  • AvroTypeException – If this is a stateful reader and char-string is not
                          the type of the next value to be read
/**
   * Reads a char-string written by {@link Encoder#writeString}.
   * 
   * @throws AvroTypeException If this is a stateful reader and char-string is not
   *                           the type of the next value to be read
   */
  public abstract String readString() throws IOException;

  
Discards a char-string written by Encoder.writeString. 
Throws:
  • AvroTypeException – If this is a stateful reader and char-string is not
                          the type of the next value to be read
/**
   * Discards a char-string written by {@link Encoder#writeString}.
   * 
   * @throws AvroTypeException If this is a stateful reader and char-string is not
   *                           the type of the next value to be read
   */
  public abstract void skipString() throws IOException;

  
Reads a byte-string written by Encoder.writeBytes. 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
/**
   * Reads a byte-string written by {@link Encoder#writeBytes}. if <tt>old</tt> is
   * not null and has sufficient capacity to take in the bytes being read, the
   * bytes are returned in <tt>old</tt>.
   * 
   * @throws AvroTypeException If this is a stateful reader and byte-string is not
   *                           the type of the next value to be read
   */
  public abstract ByteBuffer readBytes(ByteBuffer old) throws IOException;

  
Discards a byte-string written by Encoder.writeBytes. 
Throws:
  • AvroTypeException – If this is a stateful reader and byte-string is not
                          the type of the next value to be read
/**
   * Discards a byte-string written by {@link Encoder#writeBytes}.
   * 
   * @throws AvroTypeException If this is a stateful reader and byte-string is not
   *                           the type of the next value to be read
   */
  public abstract void skipBytes() throws IOException;

  
Reads fixed sized binary object.

Params:
  • 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 – 
/**
   * Reads fixed sized binary object.
   * 
   * @param bytes  The buffer to store the contents being read.
   * @param start  The position where the data needs to be written.
   * @param 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.
   * @throws IOException
   */
  public abstract void readFixed(byte[] bytes, int start, int length) 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 – 
/**
   * A shorthand for <tt>readFixed(bytes, 0, bytes.length)</tt>.
   * 
   * @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.
   * @throws IOException
   */
  public void readFixed(byte[] bytes) throws IOException {
    readFixed(bytes, 0, bytes.length);
  }

  
Discards fixed sized binary object.

Params:
  • 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 – 
/**
   * Discards fixed sized binary object.
   * 
   * @param 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.
   * @throws IOException
   */
  public abstract void skipFixed(int length) throws IOException;

  
Reads an enumeration.

Throws:
  • AvroTypeException – If this is a stateful reader and enumeration is not
                          the type of the next value to be read.
  • IOException – 
Returns:The enumeration's value.
/**
   * Reads an enumeration.
   * 
   * @return 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.
   * @throws IOException
   */
  public abstract int readEnum() 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
/**
   * 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 {@link #arrayNext} to find out the number of items in the next
   * block. The typical pattern for consuming an array looks like:
   * 
   * <pre>
   *   for(long i = in.readArrayStart(); i != 0; i = in.arrayNext()) {
   *     for (long j = 0; j < i; j++) {
   *       read next element of the array;
   *     }
   *   }
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful reader and array is not the
   *                           type of the next value to be read
   */
  public abstract long readArrayStart() throws IOException;

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

Throws:
  • AvroTypeException – When called outside of an array context
/**
   * Processes the next block of an array and returns the number of items in the
   * block and let's the caller read those items.
   * 
   * @throws AvroTypeException When called outside of an array context
   */
  public abstract long arrayNext() 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
/**
   * Used for quickly skipping through an array. Note you can either skip the
   * entire array, or read the entire array (with {@link #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:
   * 
   * <pre>
   *   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;
   *     }
   *   }
   * </pre>
   * 
   * 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
   */
  public abstract long skipArray() 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
/**
   * Reads and returns the size of the next block of map-entries. Similar to
   * {@link #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:
   * 
   * <pre>
   * Map<String, Record> m = new HashMap<String, Record>();
   * 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);
   *   }
   * }
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful reader and map is not the
   *                           type of the next value to be read
   */
  public abstract long readMapStart() 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
/**
   * Processes the next block of map entries and returns the count of them.
   * Similar to {@link #arrayNext}. See {@link #readMapStart} for details.
   * 
   * @throws AvroTypeException When called outside of a map context
   */
  public abstract long mapNext() 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
/**
   * Support for quickly skipping through a map similar to {@link #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:
   * 
   * <pre>
   * 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
   *   }
   * }
   * </pre>
   * 
   * @throws AvroTypeException If this is a stateful reader and array is not the
   *                           type of the next value to be read
   */

  public abstract long skipMap() throws IOException;

  
Reads the tag of a union written by Encoder.writeIndex. 
Throws:
  • AvroTypeException – If this is a stateful reader and union is not the
                          type of the next value to be read
/**
   * Reads the tag of a union written by {@link Encoder#writeIndex}.
   * 
   * @throws AvroTypeException If this is a stateful reader and union is not the
   *                           type of the next value to be read
   */
  public abstract int readIndex() throws IOException;
}