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
 *
 *     http://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;
}