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