lang/java/avro/src/main/java/org/apache/avro/io/Decoder.java

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

  /**
   * 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 {@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 {@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 {@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 {@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 {@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 {@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 {@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 {@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 {@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.
   * 
   * @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 <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.
   * 
   * @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.
   * 
   * @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 {@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
   */
  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 {@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
   * {@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 {@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 {@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 {@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;
}