| /* |
| * 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.Flushable; |
| import java.io.IOException; |
| import java.nio.ByteBuffer; |
| |
| import org.apache.avro.util.Utf8; |
| |
| /** |
| * Low-level support for serializing Avro values. |
| * <p/> |
| * This class has two types of methods. One type of methods support the writing |
| * of leaf values (for example, {@link #writeLong} and {@link #writeString}). |
| * These methods have analogs in {@link Decoder}. |
| * <p/> |
| * The other type of methods support the writing of maps and arrays. These |
| * methods are {@link #writeArrayStart}, {@link #startItem}, and |
| * {@link #writeArrayEnd} (and similar methods for maps). Some implementations |
| * of {@link Encoder} handle the buffering required to break large maps and |
| * arrays into blocks, which is necessary for applications that want to do |
| * streaming. (See {@link #writeArrayStart} for details on these methods.) |
| * <p/> |
| * {@link EncoderFactory} contains Encoder construction and configuration |
| * facilities. |
| * |
| * @see EncoderFactory |
| * @see Decoder |
| */ |
| public abstract class Encoder implements Flushable { |
| |
| /** |
| * "Writes" a null value. (Doesn't actually write anything, but advances the |
| * state of the parser if this class is stateful.) |
| * |
| * @throws AvroTypeException If this is a stateful writer and a null is not |
| * expected |
| */ |
| public abstract void writeNull() throws IOException; |
| |
| /** |
| * Write a boolean value. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a boolean is not |
| * expected |
| */ |
| public abstract void writeBoolean(boolean b) throws IOException; |
| |
| /** |
| * Writes a 32-bit integer. |
| * |
| * @throws AvroTypeException If this is a stateful writer and an integer is not |
| * expected |
| */ |
| public abstract void writeInt(int n) throws IOException; |
| |
| /** |
| * Write a 64-bit integer. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a long is not |
| * expected |
| */ |
| public abstract void writeLong(long n) throws IOException; |
| |
| /** |
| * Write a float. |
| * |
| * @throws IOException |
| * @throws AvroTypeException If this is a stateful writer and a float is not |
| * expected |
| */ |
| public abstract void writeFloat(float f) throws IOException; |
| |
| /** |
| * Write a double. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a double is not |
| * expected |
| */ |
| public abstract void writeDouble(double d) throws IOException; |
| |
| /** |
| * Write a Unicode character string. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a char-string is |
| * not expected |
| */ |
| public abstract void writeString(Utf8 utf8) throws IOException; |
| |
| /** |
| * Write a Unicode character string. The default implementation converts the |
| * String to a {@link org.apache.avro.util.Utf8}. Some Encoder implementations |
| * may want to do something different as a performance optimization. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a char-string is |
| * not expected |
| */ |
| public void writeString(String str) throws IOException { |
| writeString(new Utf8(str)); |
| } |
| |
| /** |
| * Write a Unicode character string. If the CharSequence is an |
| * {@link org.apache.avro.util.Utf8} it writes this directly, otherwise the |
| * CharSequence is converted to a String via toString() and written. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a char-string is |
| * not expected |
| */ |
| public void writeString(CharSequence charSequence) throws IOException { |
| if (charSequence instanceof Utf8) |
| writeString((Utf8) charSequence); |
| else |
| writeString(charSequence.toString()); |
| } |
| |
| /** |
| * Write a byte string. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a byte-string is |
| * not expected |
| */ |
| public abstract void writeBytes(ByteBuffer bytes) throws IOException; |
| |
| /** |
| * Write a byte string. |
| * |
| * @throws AvroTypeException If this is a stateful writer and a byte-string is |
| * not expected |
| */ |
| public abstract void writeBytes(byte[] bytes, int start, int len) throws IOException; |
| |
| /** |
| * Writes a byte string. Equivalent to |
| * <tt>writeBytes(bytes, 0, bytes.length)</tt> |
| * |
| * @throws IOException |
| * @throws AvroTypeException If this is a stateful writer and a byte-string is |
| * not expected |
| */ |
| public void writeBytes(byte[] bytes) throws IOException { |
| writeBytes(bytes, 0, bytes.length); |
| } |
| |
| /** |
| * Writes a fixed size binary object. |
| * |
| * @param bytes The contents to write |
| * @param start The position within <tt>bytes</tt> where the contents start. |
| * @param len The number of bytes to write. |
| * @throws AvroTypeException If this is a stateful writer and a byte-string is |
| * not expected |
| * @throws IOException |
| */ |
| public abstract void writeFixed(byte[] bytes, int start, int len) throws IOException; |
| |
| /** |
| * A shorthand for <tt>writeFixed(bytes, 0, bytes.length)</tt> |
| * |
| * @param bytes |
| */ |
| public void writeFixed(byte[] bytes) throws IOException { |
| writeFixed(bytes, 0, bytes.length); |
| } |
| |
| /** Writes a fixed from a ByteBuffer. */ |
| public void writeFixed(ByteBuffer bytes) throws IOException { |
| int pos = bytes.position(); |
| int len = bytes.limit() - pos; |
| if (bytes.hasArray()) { |
| writeFixed(bytes.array(), bytes.arrayOffset() + pos, len); |
| } else { |
| byte[] b = new byte[len]; |
| bytes.duplicate().get(b, 0, len); |
| writeFixed(b, 0, len); |
| } |
| } |
| |
| /** |
| * Writes an enumeration. |
| * |
| * @param e |
| * @throws AvroTypeException If this is a stateful writer and an enumeration is |
| * not expected or the <tt>e</tt> is out of range. |
| * @throws IOException |
| */ |
| public abstract void writeEnum(int e) throws IOException; |
| |
| /** |
| * Call this method to start writing an array. |
| * |
| * When starting to serialize an array, call {@link #writeArrayStart}. Then, |
| * before writing any data for any item call {@link #setItemCount} followed by a |
| * sequence of {@link #startItem()} and the item itself. The number of |
| * {@link #startItem()} should match the number specified in |
| * {@link #setItemCount}. When actually writing the data of the item, you can |
| * call any {@link Encoder} method (e.g., {@link #writeLong}). When all items of |
| * the array have been written, call {@link #writeArrayEnd}. |
| * |
| * As an example, let's say you want to write an array of records, the record |
| * consisting of an Long field and a Boolean field. Your code would look |
| * something like this: |
| * |
| * <pre> |
| * out.writeArrayStart(); |
| * out.setItemCount(list.size()); |
| * for (Record r : list) { |
| * out.startItem(); |
| * out.writeLong(r.longField); |
| * out.writeBoolean(r.boolField); |
| * } |
| * out.writeArrayEnd(); |
| * </pre> |
| * |
| * @throws AvroTypeException If this is a stateful writer and an array is not |
| * expected |
| */ |
| public abstract void writeArrayStart() throws IOException; |
| |
| /** |
| * Call this method before writing a batch of items in an array or a map. Then |
| * for each item, call {@link #startItem()} followed by any of the other write |
| * methods of {@link Encoder}. The number of calls to {@link #startItem()} must |
| * be equal to the count specified in {@link #setItemCount}. Once a batch is |
| * completed you can start another batch with {@link #setItemCount}. |
| * |
| * @param itemCount The number of {@link #startItem()} calls to follow. |
| * @throws IOException |
| */ |
| public abstract void setItemCount(long itemCount) throws IOException; |
| |
| /** |
| * Start a new item of an array or map. See {@link #writeArrayStart} for usage |
| * information. |
| * |
| * @throws AvroTypeException If called outside of an array or map context |
| */ |
| public abstract void startItem() throws IOException; |
| |
| /** |
| * Call this method to finish writing an array. See {@link #writeArrayStart} for |
| * usage information. |
| * |
| * @throws AvroTypeException If items written does not match count provided to |
| * {@link #writeArrayStart} |
| * @throws AvroTypeException If not currently inside an array |
| */ |
| public abstract void writeArrayEnd() throws IOException; |
| |
| /** |
| * Call this to start a new map. See {@link #writeArrayStart} for details on |
| * usage. |
| * |
| * As an example of usage, let's say you want to write a map of records, the |
| * record consisting of an Long field and a Boolean field. Your code would look |
| * something like this: |
| * |
| * <pre> |
| * out.writeMapStart(); |
| * out.setItemCount(list.size()); |
| * for (Map.Entry<String, Record> entry : map.entrySet()) { |
| * out.startItem(); |
| * out.writeString(entry.getKey()); |
| * out.writeLong(entry.getValue().longField); |
| * out.writeBoolean(entry.getValue().boolField); |
| * } |
| * out.writeMapEnd(); |
| * </pre> |
| * |
| * @throws AvroTypeException If this is a stateful writer and a map is not |
| * expected |
| */ |
| public abstract void writeMapStart() throws IOException; |
| |
| /** |
| * Call this method to terminate the inner-most, currently-opened map. See |
| * {@link #writeArrayStart} for more details. |
| * |
| * @throws AvroTypeException If items written does not match count provided to |
| * {@link #writeMapStart} |
| * @throws AvroTypeException If not currently inside a map |
| */ |
| public abstract void writeMapEnd() throws IOException; |
| |
| /** |
| * Call this method to write the tag of a union. |
| * |
| * As an example of usage, let's say you want to write a union, whose second |
| * branch is a record consisting of an Long field and a Boolean field. Your code |
| * would look something like this: |
| * |
| * <pre> |
| * out.writeIndex(1); |
| * out.writeLong(record.longField); |
| * out.writeBoolean(record.boolField); |
| * </pre> |
| * |
| * @throws AvroTypeException If this is a stateful writer and a map is not |
| * expected |
| */ |
| public abstract void writeIndex(int unionIndex) throws IOException; |
| } |