org.apache.avro.io
Class EncoderFactory

java.lang.Object
  org.apache.avro.io.EncoderFactory

public class EncoderFactory
extends Object

A factory for creating and configuring Encoder instances.

Factory methods that create Encoder instances are thread-safe. Multiple instances with different configurations can be cached by an application.

See Also:

Encoder, BinaryEncoder, JsonEncoder, ValidatingEncoder, BufferedBinaryEncoder, BlockingBinaryEncoder, DirectBinaryEncoder

Field Summary

protected int	binaryBlockSize
protected int	binaryBufferSize

Constructor Summary

EncoderFactory()

Method Summary

BinaryEncoder	binaryEncoder(OutputStream out, BinaryEncoder reuse) Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data.
BinaryEncoder	blockingBinaryEncoder(OutputStream out, BinaryEncoder reuse) Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data.
EncoderFactory	configureBlockSize(int size) Configures this factory to construct blocking BinaryEncoders with the specified block buffer size.
EncoderFactory	configureBufferSize(int size) Configures this factory to use the specified buffer size when creating Encoder instances that buffer their output.
BinaryEncoder	directBinaryEncoder(OutputStream out, BinaryEncoder reuse) Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data.
static EncoderFactory	get() Returns an immutable static DecoderFactory with default configuration.
int	getBlockSize() Returns this factory's configured default block buffer size.
int	getBufferSize() Returns this factory's configured default buffer size.
JsonEncoder	jsonEncoder(Schema schema, JsonGenerator gen) Creates a JsonEncoder using the JsonGenerator provided for output of data conforming to the Schema provided.
JsonEncoder	jsonEncoder(Schema schema, OutputStream out) Creates a JsonEncoder using the OutputStream provided for writing data conforming to the Schema provided.
ValidatingEncoder	validatingEncoder(Schema schema, Encoder encoder) Creates a ValidatingEncoder that wraps the Encoder provided.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

binaryBufferSize

protected int binaryBufferSize

binaryBlockSize

protected int binaryBlockSize

Constructor Detail

EncoderFactory

public EncoderFactory()

Method Detail

get

public static EncoderFactory get()

Returns an immutable static DecoderFactory with default configuration. All configuration methods throw AvroRuntimeExceptions if called.

configureBufferSize

public EncoderFactory configureBufferSize(int size)

Configures this factory to use the specified buffer size when creating Encoder instances that buffer their output. The default buffer size is 2048 bytes.

Parameters:

size - The buffer size to configure new instances with. Valid values are in the range [32, 16*1024*1024]. Values outside this range are set to the nearest value in the range. Values less than 256 will limit performance but will consume less memory if the BinaryEncoder is short-lived, values greater than 8*1024 are not likely to improve performance but may be useful for the downstream OutputStream.

Returns:

This factory, to enable method chaining:

 EncoderFactory factory = new EncoderFactory().configureBufferSize(4096);
 

See Also:

binaryEncoder(OutputStream, BinaryEncoder)

getBufferSize

public int getBufferSize()

Returns this factory's configured default buffer size. Used when creating Encoder instances that buffer writes.

Returns:

The preferred buffer size, in bytes.

See Also:

configureBufferSize(int), binaryEncoder(OutputStream, BinaryEncoder)

configureBlockSize

public EncoderFactory configureBlockSize(int size)

Configures this factory to construct blocking BinaryEncoders with the specified block buffer size. The default buffer size is 64 * 1024 bytes.

Parameters:

size - The preferred block size for array blocking. Arrays larger than this size will be segmented into blocks according to the Avro spec. Valid values are in the range [64, 1024*1024*1024] Values outside this range are set to the nearest value in the range. The encoder will require at least this amount of memory.

Returns:

This factory, to enable method chaining:

 EncoderFactory factory = new EncoderFactory().configureBlockSize(8000);
 

See Also:

blockingBinaryEncoder(OutputStream, BinaryEncoder)

getBlockSize

public int getBlockSize()

Returns this factory's configured default block buffer size. BinaryEncoder instances created with #blockingBinaryEncoder(OutputStream, BinaryEncoder) will have block buffers of this size.

Returns:

The preferred block size, in bytes.

See Also:

configureBlockSize(int), blockingBinaryEncoder(OutputStream, BinaryEncoder)

binaryEncoder

public BinaryEncoder binaryEncoder(OutputStream out,
                                   BinaryEncoder reuse)

Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data. If reuse is provided, an attempt will be made to reconfigure reuse rather than construct a new instance, but this is not guaranteed, a new instance may be returned.

The BinaryEncoder implementation returned may buffer its output. Data may not appear on the underlying OutputStream until Flushable.flush() is called. The buffer size is configured with configureBufferSize(int).

If buffering is not desired, and lower performance is acceptable, use directBinaryEncoder(OutputStream, BinaryEncoder)

BinaryEncoder instances returned by this method are not thread-safe

Parameters:

out - The OutputStream to write to. Cannot be null.

reuse - The BinaryEncoder to attempt to reuse given the factory configuration. A BinaryEncoder implementation may not be compatible with reuse, causing a new instance to be returned. If null, a new instance is returned.

Returns:

A BinaryEncoder that uses out as its data output. If reuse is null, this will be a new instance. If reuse is not null, then the returned instance may be a new instance or reuse reconfigured to use out.

Throws:

IOException

See Also:

BufferedBinaryEncoder, Encoder

directBinaryEncoder

public BinaryEncoder directBinaryEncoder(OutputStream out,
                                         BinaryEncoder reuse)

Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data. If reuse is provided, an attempt will be made to reconfigure reuse rather than construct a new instance, but this is not guaranteed, a new instance may be returned.

The BinaryEncoder implementation returned does not buffer its output, calling Flushable.flush() will simply cause the wrapped OutputStream to be flushed.

Performance of unbuffered writes can be significantly slower than buffered writes. binaryEncoder(OutputStream, BinaryEncoder) returns BinaryEncoder instances that are tuned for performance but may buffer output. The unbuffered, 'direct' encoder may be desired when buffering semantics are problematic, or if the lifetime of the encoder is so short that the buffer would not be useful.

BinaryEncoder instances returned by this method are not thread-safe.

Parameters:

out - The OutputStream to initialize to. Cannot be null.

reuse - The BinaryEncoder to attempt to reuse given the factory configuration. A BinaryEncoder implementation may not be compatible with reuse, causing a new instance to be returned. If null, a new instance is returned.

Returns:

A BinaryEncoder that uses out as its data output. If reuse is null, this will be a new instance. If reuse is not null, then the returned instance may be a new instance or reuse reconfigured to use out.

See Also:

DirectBinaryEncoder, Encoder

blockingBinaryEncoder

public BinaryEncoder blockingBinaryEncoder(OutputStream out,
                                           BinaryEncoder reuse)

Creates or reinitializes a BinaryEncoder with the OutputStream provided as the destination for written data. If reuse is provided, an attempt will be made to reconfigure reuse rather than construct a new instance, but this is not guaranteed, a new instance may be returned.

The BinaryEncoder implementation returned buffers its output, calling Flushable.flush() is required for output to appear on the underlying OutputStream.

The returned BinaryEncoder implements the Avro binary encoding using blocks delimited with byte sizes for Arrays and Maps. This allows for some decoders to skip over large Arrays or Maps without decoding the contents, but adds some overhead. The default block size is configured with configureBlockSize(int)

BinaryEncoder instances returned by this method are not thread-safe.

Parameters:

out - The OutputStream to initialize to. Cannot be null.

reuse - The BinaryEncoder to attempt to reuse given the factory configuration. A BinaryEncoder implementation may not be compatible with reuse, causing a new instance to be returned. If null, a new instance is returned.

Returns:

A BinaryEncoder that uses out as its data output. If reuse is null, this will be a new instance. If reuse is not null, then the returned instance may be a new instance or reuse reconfigured to use out.

Throws:

IOException

See Also:

BlockingBinaryEncoder, Encoder

jsonEncoder

public JsonEncoder jsonEncoder(Schema schema,
                               OutputStream out)
                        throws IOException

Creates a JsonEncoder using the OutputStream provided for writing data conforming to the Schema provided.

JsonEncoder buffers its output. Data may not appear on the underlying OutputStream until Flushable.flush() is called.

JsonEncoder is not thread-safe.

Parameters:

schema - The Schema for data written to this JsonEncoder. Cannot be null.

out - The OutputStream to write to. Cannot be null.

Returns:

A JsonEncoder configured with out and schema

Throws:

IOException

jsonEncoder

public JsonEncoder jsonEncoder(Schema schema,
                               JsonGenerator gen)
                        throws IOException

Creates a JsonEncoder using the JsonGenerator provided for output of data conforming to the Schema provided.

JsonEncoder buffers its output. Data may not appear on the underlying output until Flushable.flush() is called.

JsonEncoder is not thread-safe.

Parameters:

schema - The Schema for data written to this JsonEncoder. Cannot be null.

gen - The JsonGenerator to write with. Cannot be null.

Returns:

A JsonEncoder configured with gen and schema

Throws:

IOException

validatingEncoder

public ValidatingEncoder validatingEncoder(Schema schema,
                                           Encoder encoder)
                                    throws IOException

Creates a ValidatingEncoder that wraps the Encoder provided. This ValidatingEncoder will ensure that operations against it conform to the schema provided.

Many Encoders buffer their output. Data may not appear on the underlying output until Flushable.flush() is called.

ValidatingEncoder is not thread-safe.

Parameters:

schema - The Schema to validate operations against. Cannot be null.

encoder - The Encoder to wrap. Cannot be be null.

Returns:

A ValidatingEncoder configured to wrap encoder and validate against schema

Throws:

IOException