org.apache.avro.io
Class DecoderFactory

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

public class DecoderFactory
extends Object

A factory for creating and configuring Decoders.

Factories are thread-safe, and are generally cached by applications for performance reasons. Multiple instances are only required if multiple concurrent configurations are needed.

See Also:

Decoder

Constructor Summary

DecoderFactory()
Constructor for factory instances

Method Summary

DecoderFactory	configureDecoderBufferSize(int size) Configures this factory to use the specified buffer size when creating Decoder instances that buffer their input.
DecoderFactory	configureDirectDecoder(boolean useDirect) Configures this factory to create "direct" BinaryDecoder instances when applicable.
BinaryDecoder	createBinaryDecoder(byte[] bytes, BinaryDecoder reuse) This method is shorthand for
BinaryDecoder	createBinaryDecoder(byte[] bytes, int offset, int length, BinaryDecoder reuse) Creates or reinitializes a BinaryDecoder with the byte array provided as the source of data.
BinaryDecoder	createBinaryDecoder(InputStream in, BinaryDecoder reuse) Creates or reinitializes a BinaryDecoder with the input stream provided as the source of data.
static DecoderFactory	defaultFactory() Returns an immutable static DecoderFactory configured with default settings All mutating methods throw IllegalArgumentExceptions.
int	getConfiguredBufferSize() Returns this factory's configured preferred buffer size.

Methods inherited from class java.lang.Object

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

Constructor Detail

DecoderFactory

public DecoderFactory()

Constructor for factory instances

Method Detail

defaultFactory

public static DecoderFactory defaultFactory()

Returns an immutable static DecoderFactory configured with default settings All mutating methods throw IllegalArgumentExceptions. All creator methods create objects with default settings.

configureDecoderBufferSize

public DecoderFactory configureDecoderBufferSize(int size)

Configures this factory to use the specified buffer size when creating Decoder instances that buffer their input. The default buffer size is 32000 bytes.

Parameters:

size - The preferred buffer size. Valid values are in the range [32, 16*1024*1024]. Values outide this range are rounded to the nearest value in the range. Values less than 512 or greater than 1024*1024 are not recommended.

Returns:

This factory, to enable method chaining:

 DecoderFactory myFactory = new DecoderFactory().useBinaryDecoderBufferSize(4096);
 

getConfiguredBufferSize

public int getConfiguredBufferSize()

Returns this factory's configured preferred buffer size. Used when creating Decoder instances that buffer. See configureDecoderBufferSize(int)

Returns:

The preferred buffer size, in bytes.

configureDirectDecoder

public DecoderFactory configureDirectDecoder(boolean useDirect)

Configures this factory to create "direct" BinaryDecoder instances when applicable.

The default is false, since buffering or 'read-ahead' decoders can be twice as fast. In most cases a normal BinaryDecoder is sufficient in combination with BinaryDecoder.inputStream() which provides a buffer-aware view on the data.

A "direct" BinaryDecoder does not read ahead from an InputStream or other data source that cannot be rewound. From the perspective of a client, a "direct" decoder must never read beyond the minimum necessary bytes to service a BinaryDecoder API read request.

In the case that the performance of a normal BinaryDecoder does not outweigh the inconvenience of its buffering semantics, a "direct" decoder can be used.

Generally, this distinction only applies to BinaryDecoder that read from an InputStream.

Parameters:

useDirect - If true, this factory will generate "direct" BinaryDecoder implementations when applicable. If false (the default) the faster buffering implementations will be generated.

Returns:

This factory, to enable method chaining:

 DecoderFactory myFactory = new DecoderFactory().configureDirectDecoder(true);
 

createBinaryDecoder

public BinaryDecoder createBinaryDecoder(InputStream in,
                                         BinaryDecoder reuse)

Creates or reinitializes a BinaryDecoder with the input stream provided as the source of data. If reuse is provided, it will be reinitialized to the given input stream.

If this factory is configured to create "direct" BinaryDecoder instances, this will return a non-buffering variant. Otherwise, this instance will buffer the number of bytes configured by this factory, reading up to that many bytes from the InputStream ahead of the minimum required for Decoder API requests. BinaryDecoder.inputStream() provides a view on the data that is buffer-aware, for users that need to access possibly buffered data outside of the Decoder API.

Parameters:

in - The InputStream to initialize to

reuse - The BinaryDecoder to attempt to reuse given the factory configuration. A specific BinaryDecoder implementation may not be compatible with reuse. For example, a BinaryDecoder created as 'direct' can not be reinitialized to function in a non-'direct' mode. If reuse is null a new instance is always created.

Returns:

A BinaryDecoder that uses in as its source of data. If reuse is null, this will be a new instance. If reuse is not null, then it may be reinitialized if compatible, otherwise a new instance will be returned.

example:

 DecoderFactory factory = new DecoderFactory();
 Decoder d = factory.createBinaryDecoder(input, null); // a new BinaryDecoder
 d = createBinaryDecoder(input2, d); // reinitializes d to read from input2
 factory.configureDirectDecoder(true);
 Decoder d2 = factory.createBinaryDecoder(input3, d); // a new BinaryDecoder
 

d2 above is not a reused instance of d because the latter is not 'direct' and can't be reused to create a 'direct' instance. Users must be careful to use the BinaryDecoder returned from the factory and not assume that the factory passed in the reuse argument

createBinaryDecoder

public BinaryDecoder createBinaryDecoder(byte[] bytes,
                                         int offset,
                                         int length,
                                         BinaryDecoder reuse)

Creates or reinitializes a BinaryDecoder with the byte array provided as the source of data. If reuse is provided, it will attempt to reinitiailize reuse to the new byte array. This instance will use the provided byte array as its buffer. BinaryDecoder.inputStream() provides a view on the data that is buffer-aware and can provide a view of the data not yet read by Decoder API methods.

Parameters:

bytes - The byte array to initialize to

offset - The offset to start reading from

length - The maximum number of bytes to read from the byte array

reuse - The BinaryDecoder to attempt to reinitialize. if null a new BinaryDecoder is created.

Returns:

A BinaryDecoder that uses bytes as its source of data. If reuse is null, this will be a new instance. reuse may be reinitialized if appropriate, otherwise a new instance is returned. Clients must not assume that reuse is reinitialized and returned.

createBinaryDecoder

public BinaryDecoder createBinaryDecoder(byte[] bytes,
                                         BinaryDecoder reuse)

This method is shorthand for

 createBinaryDecoder(bytes, 0, bytes.length, reuse);
 

createBinaryDecoder(byte[], int, int, BinaryDecoder)