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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `binaryBlockSize`
    `protected int` | `binaryBufferSize`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EncoderFactory()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `BinaryEncoder` | `blockingDirectBinaryEncoder(OutputStream out, BinaryEncoder reuse)` Creates or reinitializes a `BlockingDirectBinaryEncoder` 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, OutputStream out)` Creates a `JsonEncoder` using the OutputStream provided for writing data conforming to the Schema provided.
    `JsonEncoder` | `jsonEncoder(Schema schema, OutputStream out, boolean pretty)` Creates a `JsonEncoder` using the OutputStream provided for writing data conforming to the Schema provided with optional pretty printing.
    `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`

    - #### 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:
        `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,
                                         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`

    - #### 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 `Encoder`s 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 © 2009–2024 The Apache Software Foundation. All rights reserved.