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