lang/java/avro/src/main/java/org/apache/avro/io/DecoderFactory.java

/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.avro.io;

import java.io.IOException;
import java.io.InputStream;

import org.apache.avro.Schema;

/**
 * A factory for creating and configuring {@link Decoder}s.
 * <p/>
 * 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 Decoder
 */

public class DecoderFactory {
  private static final DecoderFactory DEFAULT_FACTORY = new DefaultDecoderFactory();
  static final int DEFAULT_BUFFER_SIZE = 8192;

  int binaryDecoderBufferSize = DEFAULT_BUFFER_SIZE;

  /** Constructor for factory instances */
  public DecoderFactory() {
    super();
  }

  /**
   * @deprecated use the equivalent {@link #get()} instead
   */
  @Deprecated
  public static DecoderFactory defaultFactory() {
    return get();
  }

  /**
   * Returns an immutable static DecoderFactory configured with default settings
   * All mutating methods throw IllegalArgumentExceptions. All creator methods
   * create objects with default settings.
   */
  public static DecoderFactory get() {
    return DEFAULT_FACTORY;
  }

  /**
   * Configures this factory to use the specified buffer size when creating
   * Decoder instances that buffer their input. The default buffer size is
   * 8192 bytes.
   *
   * @param size The preferred buffer size. Valid values are in the range [32,
   *          16*1024*1024]. Values outside this range are rounded to the nearest
   *          value in the range. Values less than 512 or greater than 1024*1024
   *          are not recommended.
   * @return This factory, to enable method chaining:
   * <pre>
   * DecoderFactory myFactory = new DecoderFactory().useBinaryDecoderBufferSize(4096);
   * </pre>
   */
  public DecoderFactory configureDecoderBufferSize(int size) {
    if (size < 32)
      size = 32;
    if (size > 16 * 1024 * 1024)
      size = 16 * 1024 * 1024;
    this.binaryDecoderBufferSize = size;
    return this;
  }

  /**
   * Returns this factory's configured preferred buffer size.  Used when creating
   * Decoder instances that buffer. See {@link #configureDecoderBufferSize}
   * @return The preferred buffer size, in bytes.
   */
  public int getConfiguredBufferSize() {
    return this.binaryDecoderBufferSize;
  }

  /** @deprecated use the equivalent
   *  {@link #binaryDecoder(InputStream, BinaryDecoder)} instead */
  @Deprecated
  public BinaryDecoder createBinaryDecoder(InputStream in, BinaryDecoder reuse) {
    return binaryDecoder(in, reuse);
  }

  /**
   * Creates or reinitializes a {@link BinaryDecoder} with the input stream
   * provided as the source of data. If <i>reuse</i> is provided, it will be
   * reinitialized to the given input stream.
   * <p/>
   * {@link BinaryDecoder} instances returned by this method buffer their input,
   * reading up to {@link #getConfiguredBufferSize()} bytes past the minimum
   * required to satisfy read requests in order to achieve better performance.
   * If the buffering is not desired, use
   * {@link #directBinaryDecoder(InputStream, BinaryDecoder)}.
   * <p/>
   * {@link BinaryDecoder#inputStream()} provides a view on the data that is
   * buffer-aware, for users that need to interleave access to data
   * with the Decoder API.
   *
   * @param in
   *          The InputStream to initialize to
   * @param reuse
   *          The BinaryDecoder to <i>attempt</i> to reuse given the factory
   *          configuration. A BinaryDecoder implementation may not be
   *          compatible with reuse, causing a new instance to be returned. If
   *          null, a new instance is returned.
   * @return A BinaryDecoder that uses <i>in</i> as its source of data. If
   *         <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
   *         is not null, then it may be reinitialized if compatible, otherwise
   *         a new instance will be returned.
   * @see BinaryDecoder
   * @see Decoder
   */
  public BinaryDecoder binaryDecoder(InputStream in, BinaryDecoder reuse) {
    if (null == reuse || !reuse.getClass().equals(BinaryDecoder.class)) {
      return new BinaryDecoder(in, binaryDecoderBufferSize);
    } else {
      return ((BinaryDecoder)reuse).configure(in, binaryDecoderBufferSize);
    }
  }

  /**
   * Creates or reinitializes a {@link BinaryDecoder} with the input stream
   * provided as the source of data. If <i>reuse</i> is provided, it will be
   * reinitialized to the given input stream.
   * <p/>
   * {@link BinaryDecoder} instances returned by this method do not buffer their input.
   * In most cases a buffering BinaryDecoder is sufficient in combination with
   * {@link BinaryDecoder#inputStream()} which provides a buffer-aware view on
   * the data.
   * <p/>
   * 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 {@link BinaryDecoder}
   * API read request.
   * <p/>
   * In the case that the improved performance of a buffering implementation does not outweigh the
   * inconvenience of its buffering semantics, a "direct" decoder can be
   * used.
   * @param in
   *          The InputStream to initialize to
   * @param reuse
   *          The BinaryDecoder to <i>attempt</i> to reuse given the factory
   *          configuration. A BinaryDecoder implementation may not be
   *          compatible with reuse, causing a new instance to be returned. If
   *          null, a new instance is returned.
   * @return A BinaryDecoder that uses <i>in</i> as its source of data. If
   *         <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
   *         is not null, then it may be reinitialized if compatible, otherwise
   *         a new instance will be returned.
   * @see DirectBinaryDecoder
   * @see Decoder
   */
  public BinaryDecoder directBinaryDecoder(InputStream in, BinaryDecoder reuse) {
    if (null == reuse || !reuse.getClass().equals(DirectBinaryDecoder.class)) {
      return new DirectBinaryDecoder(in);
    } else {
      return ((DirectBinaryDecoder)reuse).configure(in);
    }
  }

  /** @deprecated use {@link #binaryDecoder(byte[], int, int, BinaryDecoder)}
   * instead */
  @Deprecated
  public BinaryDecoder createBinaryDecoder(byte[] bytes, int offset,
      int length, BinaryDecoder reuse) {
    if (null == reuse || !reuse.getClass().equals(BinaryDecoder.class)) {
      return new BinaryDecoder(bytes, offset, length);
    } else {
      return reuse.configure(bytes, offset, length);
    }
  }

  /**
   * Creates or reinitializes a {@link BinaryDecoder} with the byte array
   * provided as the source of data. If <i>reuse</i> is provided, it will
   * attempt to reinitialize <i>reuse</i> to the new byte array. This instance
   * will use the provided byte array as its buffer.
   * <p/>
   * {@link 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.
   *
   * @param bytes The byte array to initialize to
   * @param offset The offset to start reading from
   * @param length The maximum number of bytes to read from the byte array
   * @param reuse The BinaryDecoder to attempt to reinitialize. if null a new
   *          BinaryDecoder is created.
   * @return A BinaryDecoder that uses <i>bytes</i> as its source of data. If
   *         <i>reuse</i> is null, this will be a new instance. <i>reuse</i> may
   *         be reinitialized if appropriate, otherwise a new instance is
   *         returned. Clients must not assume that <i>reuse</i> is
   *         reinitialized and returned.
   */
  public BinaryDecoder binaryDecoder(byte[] bytes, int offset,
      int length, BinaryDecoder reuse) {
    if (null == reuse || !reuse.getClass().equals(BinaryDecoder.class)) {
      return new BinaryDecoder(bytes, offset, length);
    } else {
      return reuse.configure(bytes, offset, length);
    }
  }

  /** @deprecated use {@link #binaryDecoder(byte[], BinaryDecoder)} instead */
  @Deprecated
  public BinaryDecoder createBinaryDecoder(byte[] bytes, BinaryDecoder reuse) {
    return binaryDecoder(bytes, 0, bytes.length, reuse);
  }

  /**
   * This method is shorthand for
   * <pre>
   * createBinaryDecoder(bytes, 0, bytes.length, reuse);
   * </pre> {@link #binaryDecoder(byte[], int, int, BinaryDecoder)}
   */
  public BinaryDecoder binaryDecoder(byte[] bytes, BinaryDecoder reuse) {
    return binaryDecoder(bytes, 0, bytes.length, reuse);
  }

  /**
   * Creates a {@link JsonDecoder} using the InputStrim provided for reading
   * data that conforms to the Schema provided.
   * <p/>
   *
   * @param schema
   *          The Schema for data read from this JsonEncoder. Cannot be null.
   * @param input
   *          The InputStream to read from. Cannot be null.
   * @return A JsonEncoder configured with <i>input</i> and <i>schema</i>
   * @throws IOException
   */
  public JsonDecoder jsonDecoder(Schema schema, InputStream input)
      throws IOException {
    return new JsonDecoder(schema, input);
  }

  /**
   * Creates a {@link JsonDecoder} using the String provided for reading data
   * that conforms to the Schema provided.
   * <p/>
   *
   * @param schema
   *          The Schema for data read from this JsonEncoder. Cannot be null.
   * @param input
   *          The String to read from. Cannot be null.
   * @return A JsonEncoder configured with <i>input</i> and <i>schema</i>
   * @throws IOException
   */
  public JsonDecoder jsonDecoder(Schema schema, String input)
      throws IOException {
    return new JsonDecoder(schema, input);
  }

  /**
   * Creates a {@link ValidatingDecoder} wrapping the Decoder provided. This
   * ValidatingDecoder will ensure that operations against it conform to the
   * schema provided.
   *
   * @param schema
   *          The Schema to validate against. Cannot be null.
   * @param wrapped
   *          The Decoder to wrap.
   * @return A ValidatingDecoder configured with <i>wrapped</i> and
   *         <i>schema</i>
   * @throws IOException
   */
  public ValidatingDecoder validatingDecoder(Schema schema, Decoder wrapped)
      throws IOException {
    return new ValidatingDecoder(schema, wrapped);
  }

  /**
   * Creates a {@link ResolvingDecoder} wrapping the Decoder provided. This
   * ResolvingDecoder will resolve input conforming to the <i>writer</i> schema
   * from the wrapped Decoder, and present it as the <i>reader</i> schema.
   *
   * @param writer
   *          The Schema that the source data is in. Cannot be null.
   * @param reader
   *          The Schema that the reader wishes to read the data as. Cannot be
   *          null.
   * @param wrapped
   *          The Decoder to wrap.
   * @return A ResolvingDecoder configured to resolve <i>writer</i> to
   *         <i>reader</i> from <i>in</i>
   * @throws IOException
   */
  public ResolvingDecoder resolvingDecoder(Schema writer, Schema reader,
      Decoder wrapped) throws IOException {
    return new ResolvingDecoder(writer, reader, wrapped);
  }

  private static class DefaultDecoderFactory extends DecoderFactory {
    @Override
    public DecoderFactory configureDecoderBufferSize(int bufferSize) {
      throw new IllegalArgumentException("This Factory instance is Immutable");
    }
  }
}