org.apache.avro.io
Class EncoderFactory

java.lang.Object
  extended by 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


Copyright © 2011 The Apache Software Foundation. All Rights Reserved.