Package 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:

  • Field Details

    • binaryBufferSize

      protected int binaryBufferSize

    • binaryBlockSize

      protected int binaryBlockSize

  • Constructor Details

    • EncoderFactory

      public EncoderFactory()

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • blockingDirectBinaryEncoder

      public BinaryEncoder blockingDirectBinaryEncoder(OutputStream out, BinaryEncoder reuse)
      Creates or reinitializes a BlockingDirectBinaryEncoder 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.

      The BlockingDirectBinaryEncoder will write the block sizes for the arrays and maps so efficient skipping can be done.

      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:

    • 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:

    • 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, OutputStream out, boolean pretty) throws IOException
      Creates a JsonEncoder using the OutputStream provided for writing data conforming to the Schema provided with optional pretty printing.

      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.
      pretty - Pretty print encoding.
      Returns:
      A JsonEncoder configured with out, schema and pretty
      Throws:
      IOException

    • jsonEncoder

      public JsonEncoder jsonEncoder(Schema schema, OutputStream out, boolean pretty, boolean autoflush) throws IOException
      Creates a JsonEncoder using the OutputStream provided for writing data conforming to the Schema provided with optional pretty printing.

      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.
      pretty - Pretty print encoding.
      autoflush - Whether to Automatically flush the data to storage, default is true controls the underlying FLUSH_PASSED_TO_STREAM feature of JsonGenerator
      Returns:
      A JsonEncoder configured with out, schema and pretty
      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