lang/java/avro/src/main/java/org/apache/avro/io/EncoderFactory.java - avro - Git at Google

 /**
  * 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.OutputStream;

 import org.apache.avro.AvroRuntimeException;
 import org.apache.avro.Schema;
 import org.codehaus.jackson.JsonGenerator;

 /**
  * A factory for creating and configuring {@link Encoder} instances.
  * <p/>
  * Factory methods that create Encoder instances are thread-safe.
  * Multiple instances with different configurations can be cached
  * by an application.
  *
  * @see Encoder
  * @see BinaryEncoder
  * @see JsonEncoder
  * @see ValidatingEncoder
  * @see BufferedBinaryEncoder
  * @see BlockingBinaryEncoder
  * @see DirectBinaryEncoder
  */

 public class EncoderFactory {
   private static final int DEFAULT_BUFFER_SIZE = 2048;
   private static final int DEFAULT_BLOCK_BUFFER_SIZE = 64 * 1024;
   private static final int MIN_BLOCK_BUFFER_SIZE = 64;
   private static final int MAX_BLOCK_BUFFER_SIZE = 1024 * 1024 * 1024;

   private static final EncoderFactory DEFAULT_FACTORY =
     new DefaultEncoderFactory();

   protected int binaryBufferSize = DEFAULT_BUFFER_SIZE;
   protected int binaryBlockSize = DEFAULT_BLOCK_BUFFER_SIZE;

   /**
    * Returns an immutable static DecoderFactory with default configuration.
    * All configuration methods throw AvroRuntimeExceptions if called.
    */
   public static EncoderFactory get() {
     return DEFAULT_FACTORY;
   }

   /**
    * Configures this factory to use the specified buffer size when creating
    * Encoder instances that buffer their output. The default buffer size is 2048
    * bytes.
    *
    * @param 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.
    * @return This factory, to enable method chaining:
    * <pre>
    * EncoderFactory factory = new EncoderFactory().configureBufferSize(4096);
    * </pre>
    * @see #binaryEncoder(OutputStream, BinaryEncoder)
    */
   public EncoderFactory configureBufferSize(int size) {
     if (size < 32)
       size = 32;
     if (size > 16 * 1024 * 1024)
       size = 16 * 1024 * 1024;
     this.binaryBufferSize = size;
     return this;
   }

   /**
    * Returns this factory's configured default buffer size.  Used when creating
    * Encoder instances that buffer writes.
    * @see #configureBufferSize(int)
    * @see #binaryEncoder(OutputStream, BinaryEncoder)
    * @return The preferred buffer size, in bytes.
    */
   public int getBufferSize() {
     return this.binaryBufferSize;
   }

   /**
    * Configures this factory to construct blocking BinaryEncoders with the
    * specified block buffer size. The default buffer size is 64 * 1024 bytes.
    *
    * @param 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.
    * @return This factory, to enable method chaining:
    * <pre>
    * EncoderFactory factory = new EncoderFactory().configureBlockSize(8000);
    * </pre>
    * @see #blockingBinaryEncoder(OutputStream, BinaryEncoder)
    */
   public EncoderFactory configureBlockSize(int size) {
     if (size < MIN_BLOCK_BUFFER_SIZE)
       size = MIN_BLOCK_BUFFER_SIZE;
     if (size > MAX_BLOCK_BUFFER_SIZE)
       size = MAX_BLOCK_BUFFER_SIZE;
     this.binaryBlockSize = size;
     return this;
   }

   /**
    * Returns this factory's configured default block buffer size.
    * {@link BinaryEncoder} instances created with
    * #blockingBinaryEncoder(OutputStream, BinaryEncoder)
    * will have block buffers of this size.
    * <p/>
    * @see #configureBlockSize(int)
    * @see #blockingBinaryEncoder(OutputStream, BinaryEncoder)
    * @return The preferred block size, in bytes.
    */
   public int getBlockSize() {
     return this.binaryBlockSize;
   }

   /**
    * Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
    * provided as the destination for written data. If <i>reuse</i> is provided,
    * an attempt will be made to reconfigure <i>reuse</i> rather than construct a
    * new instance, but this is not guaranteed, a new instance may be returned.
    * <p/>
    * The {@link BinaryEncoder} implementation returned may buffer its output.
    * Data may not appear on the underlying OutputStream until
    * {@link Encoder#flush()} is called.  The buffer size is configured with
    * {@link #configureBufferSize(int)}.
    * </p>  If buffering is not desired, and lower performance is acceptable, use
    * {@link #directBinaryEncoder(OutputStream, BinaryEncoder)}
    * <p/>
    * {@link BinaryEncoder} instances returned by this method are not thread-safe
    *
    * @param out
    *          The OutputStream to write to.  Cannot be null.
    * @param reuse
    *          The BinaryEncoder to <i>attempt</i> 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.
    * @return A BinaryEncoder that uses <i>out</i> as its data output. If
    *         <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
    *         is not null, then the returned instance may be a new instance or
    *         <i>reuse</i> reconfigured to use <i>out</i>.
    * @throws IOException
    * @see BufferedBinaryEncoder
    * @see Encoder
    */
   public BinaryEncoder binaryEncoder(OutputStream out, BinaryEncoder reuse) {
     if (null == reuse || !reuse.getClass().equals(BufferedBinaryEncoder.class)) {
       return new BufferedBinaryEncoder(out, this.binaryBufferSize);
     }  else {
       return ((BufferedBinaryEncoder)reuse).configure(out, this.binaryBufferSize);
     }
   }

   /**
    * Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
    * provided as the destination for written data. If <i>reuse</i> is provided,
    * an attempt will be made to reconfigure <i>reuse</i> rather than construct a
    * new instance, but this is not guaranteed, a new instance may be returned.
    * <p/>
    * The {@link BinaryEncoder} implementation returned does not buffer its
    * output, calling {@link Encoder#flush()} will simply cause the wrapped
    * OutputStream to be flushed.
    * <p/>
    * Performance of unbuffered writes can be significantly slower than buffered
    * writes.  {@link #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.
    * <p/>
    * {@link BinaryEncoder} instances returned by this method are not thread-safe.
    *
    * @param out
    *          The OutputStream to initialize to. Cannot be null.
    * @param reuse
    *          The BinaryEncoder to <i>attempt</i> 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.
    * @return A BinaryEncoder that uses <i>out</i> as its data output. If
    *         <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
    *         is not null, then the returned instance may be a new instance or
    *         <i>reuse</i> reconfigured to use <i>out</i>.
    * @see DirectBinaryEncoder
    * @see Encoder
    */
   public BinaryEncoder directBinaryEncoder(OutputStream out, BinaryEncoder reuse) {
     if (null == reuse || !reuse.getClass().equals(DirectBinaryEncoder.class)) {
       return new DirectBinaryEncoder(out);
     } else {
       return ((DirectBinaryEncoder)reuse).configure(out);
     }
   }

   /**
    * Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
    * provided as the destination for written data. If <i>reuse</i> is provided,
    * an attempt will be made to reconfigure <i>reuse</i> rather than construct a
    * new instance, but this is not guaranteed, a new instance may be returned.
    * <p/>
    * The {@link BinaryEncoder} implementation returned buffers its output,
    * calling {@link Encoder#flush()} is required for output to appear on the underlying
    * OutputStream.
    * <p/>
    * 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
    * {@link #configureBlockSize(int)}
    * <p/>
    * {@link BinaryEncoder} instances returned by this method are not thread-safe.
    *
    * @param out
    *          The OutputStream to initialize to. Cannot be null.
    * @param reuse
    *          The BinaryEncoder to <i>attempt</i> 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.
    * @return A BinaryEncoder that uses <i>out</i> as its data output. If
    *         <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
    *         is not null, then the returned instance may be a new instance or
    *         <i>reuse</i> reconfigured to use <i>out</i>.
    * @throws IOException
    * @see BlockingBinaryEncoder
    * @see Encoder
    */
   public BinaryEncoder blockingBinaryEncoder(OutputStream out,
       BinaryEncoder reuse) {
     int blockSize = this.binaryBlockSize;
     int bufferSize = (blockSize * 2 >= this.binaryBufferSize) ? 32
         : this.binaryBufferSize;
     if (null == reuse || !reuse.getClass().equals(BlockingBinaryEncoder.class)) {
       return new BlockingBinaryEncoder(out, blockSize, bufferSize);
     } else {
       return ((BlockingBinaryEncoder) reuse).configure(out, blockSize, bufferSize);
     }
   }

   /**
    * Creates a {@link JsonEncoder} using the OutputStream provided for writing
    * data conforming to the Schema provided.
    * <p/>
    * {@link JsonEncoder} buffers its output. Data may not appear on the
    * underlying OutputStream until {@link Encoder#flush()} is called.
    * <p/>
    * {@link JsonEncoder} is not thread-safe.
    *
    * @param schema
    *          The Schema for data written to this JsonEncoder. Cannot be null.
    * @param out
    *          The OutputStream to write to. Cannot be null.
    * @return A JsonEncoder configured with <i>out</i> and <i>schema</i>
    * @throws IOException
    */
   public JsonEncoder jsonEncoder(Schema schema, OutputStream out)
       throws IOException {
     return new JsonEncoder(schema, out);
   }

   /**
    * Creates a {@link JsonEncoder} using the OutputStream provided for writing
    * data conforming to the Schema provided with optional pretty printing.
    * <p/>
    * {@link JsonEncoder} buffers its output. Data may not appear on the
    * underlying OutputStream until {@link Encoder#flush()} is called.
    * <p/>
    * {@link JsonEncoder} is not thread-safe.
    *
    * @param schema
    *          The Schema for data written to this JsonEncoder. Cannot be null.
    * @param out
    *          The OutputStream to write to. Cannot be null.
    * @param pretty
    *          Pretty print encoding.
    * @return A JsonEncoder configured with <i>out</i>, <i>schema</i> and <i>pretty</i>
    * @throws IOException
    */
   public JsonEncoder jsonEncoder(Schema schema, OutputStream out, boolean pretty)
       throws IOException {
     return new JsonEncoder(schema, out, pretty);
   }

   /**
    * Creates a {@link JsonEncoder} using the {@link JsonGenerator} provided for
    * output of data conforming to the Schema provided.
    * <p/>
    * {@link JsonEncoder} buffers its output. Data may not appear on the
    * underlying output until {@link Encoder#flush()} is called.
    * <p/>
    * {@link JsonEncoder} is not thread-safe.
    *
    * @param schema
    *          The Schema for data written to this JsonEncoder. Cannot be null.
    * @param gen
    *          The JsonGenerator to write with. Cannot be null.
    * @return A JsonEncoder configured with <i>gen</i> and <i>schema</i>
    * @throws IOException
    * @deprecated internal method
    */
   @Deprecated
   public JsonEncoder jsonEncoder(Schema schema, JsonGenerator gen)
       throws IOException {
     return new JsonEncoder(schema, gen);
   }

   /**
    * Creates a {@link ValidatingEncoder} that wraps the Encoder provided.
    * This ValidatingEncoder will ensure that operations against it conform
    * to the schema provided.
    * <p/>
    * Many {@link Encoder}s buffer their output. Data may not appear on the
    * underlying output until {@link Encoder#flush()} is called.
    * <p/>
    * {@link ValidatingEncoder} is not thread-safe.
    *
    * @param schema
    *          The Schema to validate operations against. Cannot be null.
    * @param encoder
    *          The Encoder to wrap.  Cannot be be null.
    * @return A ValidatingEncoder configured to wrap <i>encoder</i> and validate
    *  against <i>schema</i>
    * @throws IOException
    */
   public ValidatingEncoder validatingEncoder(Schema schema, Encoder encoder)
       throws IOException {
     return new ValidatingEncoder(schema, encoder);
   }

   // default encoder is not mutable
   private static class DefaultEncoderFactory extends EncoderFactory {
     @Override
     public EncoderFactory configureBlockSize(int size) {
       throw new AvroRuntimeException("Default EncoderFactory cannot be configured");
     }
     @Override
     public EncoderFactory configureBufferSize(int size) {
       throw new AvroRuntimeException("Default EncoderFactory cannot be configured");
     }
   }
 }
	/**
	* 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.OutputStream;

	import org.apache.avro.AvroRuntimeException;
	import org.apache.avro.Schema;
	import org.codehaus.jackson.JsonGenerator;

	/**
	* A factory for creating and configuring {@link Encoder} instances.
	* <p/>
	* Factory methods that create Encoder instances are thread-safe.
	* Multiple instances with different configurations can be cached
	* by an application.
	*
	* @see Encoder
	* @see BinaryEncoder
	* @see JsonEncoder
	* @see ValidatingEncoder
	* @see BufferedBinaryEncoder
	* @see BlockingBinaryEncoder
	* @see DirectBinaryEncoder
	*/

	public class EncoderFactory {
	private static final int DEFAULT_BUFFER_SIZE = 2048;
	private static final int DEFAULT_BLOCK_BUFFER_SIZE = 64 * 1024;
	private static final int MIN_BLOCK_BUFFER_SIZE = 64;
	private static final int MAX_BLOCK_BUFFER_SIZE = 1024 * 1024 * 1024;

	private static final EncoderFactory DEFAULT_FACTORY =
	new DefaultEncoderFactory();

	protected int binaryBufferSize = DEFAULT_BUFFER_SIZE;
	protected int binaryBlockSize = DEFAULT_BLOCK_BUFFER_SIZE;

	/**
	* Returns an immutable static DecoderFactory with default configuration.
	* All configuration methods throw AvroRuntimeExceptions if called.
	*/
	public static EncoderFactory get() {
	return DEFAULT_FACTORY;
	}

	/**
	* Configures this factory to use the specified buffer size when creating
	* Encoder instances that buffer their output. The default buffer size is 2048
	* bytes.
	*
	* @param size
	* The buffer size to configure new instances with. Valid values are
	* in the range [32, 1610241024]. 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.
	* @return This factory, to enable method chaining:
	* <pre>
	* EncoderFactory factory = new EncoderFactory().configureBufferSize(4096);
	* </pre>
	* @see #binaryEncoder(OutputStream, BinaryEncoder)
	*/
	public EncoderFactory configureBufferSize(int size) {
	if (size < 32)
	size = 32;
	if (size > 16 * 1024 * 1024)
	size = 16 * 1024 * 1024;
	this.binaryBufferSize = size;
	return this;
	}

	/**
	* Returns this factory's configured default buffer size. Used when creating
	* Encoder instances that buffer writes.
	* @see #configureBufferSize(int)
	* @see #binaryEncoder(OutputStream, BinaryEncoder)
	* @return The preferred buffer size, in bytes.
	*/
	public int getBufferSize() {
	return this.binaryBufferSize;
	}

	/**
	* Configures this factory to construct blocking BinaryEncoders with the
	* specified block buffer size. The default buffer size is 64 * 1024 bytes.
	*
	* @param 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, 102410241024] Values
	* outside this range are set to the nearest value in the range. The
	* encoder will require at least this amount of memory.
	* @return This factory, to enable method chaining:
	* <pre>
	* EncoderFactory factory = new EncoderFactory().configureBlockSize(8000);
	* </pre>
	* @see #blockingBinaryEncoder(OutputStream, BinaryEncoder)
	*/
	public EncoderFactory configureBlockSize(int size) {
	if (size < MIN_BLOCK_BUFFER_SIZE)
	size = MIN_BLOCK_BUFFER_SIZE;
	if (size > MAX_BLOCK_BUFFER_SIZE)
	size = MAX_BLOCK_BUFFER_SIZE;
	this.binaryBlockSize = size;
	return this;
	}

	/**
	* Returns this factory's configured default block buffer size.
	* {@link BinaryEncoder} instances created with
	* #blockingBinaryEncoder(OutputStream, BinaryEncoder)
	* will have block buffers of this size.
	* <p/>
	* @see #configureBlockSize(int)
	* @see #blockingBinaryEncoder(OutputStream, BinaryEncoder)
	* @return The preferred block size, in bytes.
	*/
	public int getBlockSize() {
	return this.binaryBlockSize;
	}

	/**
	* Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
	* provided as the destination for written data. If <i>reuse</i> is provided,
	* an attempt will be made to reconfigure <i>reuse</i> rather than construct a
	* new instance, but this is not guaranteed, a new instance may be returned.
	* <p/>
	* The {@link BinaryEncoder} implementation returned may buffer its output.
	* Data may not appear on the underlying OutputStream until
	* {@link Encoder#flush()} is called. The buffer size is configured with
	* {@link #configureBufferSize(int)}.
	* </p> If buffering is not desired, and lower performance is acceptable, use
	* {@link #directBinaryEncoder(OutputStream, BinaryEncoder)}
	* <p/>
	* {@link BinaryEncoder} instances returned by this method are not thread-safe
	*
	* @param out
	* The OutputStream to write to. Cannot be null.
	* @param reuse
	* The BinaryEncoder to <i>attempt</i> 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.
	* @return A BinaryEncoder that uses <i>out</i> as its data output. If
	* <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
	* is not null, then the returned instance may be a new instance or
	* <i>reuse</i> reconfigured to use <i>out</i>.
	* @throws IOException
	* @see BufferedBinaryEncoder
	* @see Encoder
	*/
	public BinaryEncoder binaryEncoder(OutputStream out, BinaryEncoder reuse) {
	if (null == reuse \|\| !reuse.getClass().equals(BufferedBinaryEncoder.class)) {
	return new BufferedBinaryEncoder(out, this.binaryBufferSize);
	} else {
	return ((BufferedBinaryEncoder)reuse).configure(out, this.binaryBufferSize);
	}
	}

	/**
	* Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
	* provided as the destination for written data. If <i>reuse</i> is provided,
	* an attempt will be made to reconfigure <i>reuse</i> rather than construct a
	* new instance, but this is not guaranteed, a new instance may be returned.
	* <p/>
	* The {@link BinaryEncoder} implementation returned does not buffer its
	* output, calling {@link Encoder#flush()} will simply cause the wrapped
	* OutputStream to be flushed.
	* <p/>
	* Performance of unbuffered writes can be significantly slower than buffered
	* writes. {@link #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.
	* <p/>
	* {@link BinaryEncoder} instances returned by this method are not thread-safe.
	*
	* @param out
	* The OutputStream to initialize to. Cannot be null.
	* @param reuse
	* The BinaryEncoder to <i>attempt</i> 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.
	* @return A BinaryEncoder that uses <i>out</i> as its data output. If
	* <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
	* is not null, then the returned instance may be a new instance or
	* <i>reuse</i> reconfigured to use <i>out</i>.
	* @see DirectBinaryEncoder
	* @see Encoder
	*/
	public BinaryEncoder directBinaryEncoder(OutputStream out, BinaryEncoder reuse) {
	if (null == reuse \|\| !reuse.getClass().equals(DirectBinaryEncoder.class)) {
	return new DirectBinaryEncoder(out);
	} else {
	return ((DirectBinaryEncoder)reuse).configure(out);
	}
	}

	/**
	* Creates or reinitializes a {@link BinaryEncoder} with the OutputStream
	* provided as the destination for written data. If <i>reuse</i> is provided,
	* an attempt will be made to reconfigure <i>reuse</i> rather than construct a
	* new instance, but this is not guaranteed, a new instance may be returned.
	* <p/>
	* The {@link BinaryEncoder} implementation returned buffers its output,
	* calling {@link Encoder#flush()} is required for output to appear on the underlying
	* OutputStream.
	* <p/>
	* 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
	* {@link #configureBlockSize(int)}
	* <p/>
	* {@link BinaryEncoder} instances returned by this method are not thread-safe.
	*
	* @param out
	* The OutputStream to initialize to. Cannot be null.
	* @param reuse
	* The BinaryEncoder to <i>attempt</i> 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.
	* @return A BinaryEncoder that uses <i>out</i> as its data output. If
	* <i>reuse</i> is null, this will be a new instance. If <i>reuse</i>
	* is not null, then the returned instance may be a new instance or
	* <i>reuse</i> reconfigured to use <i>out</i>.
	* @throws IOException
	* @see BlockingBinaryEncoder
	* @see Encoder
	*/
	public BinaryEncoder blockingBinaryEncoder(OutputStream out,
	BinaryEncoder reuse) {
	int blockSize = this.binaryBlockSize;
	int bufferSize = (blockSize * 2 >= this.binaryBufferSize) ? 32
	: this.binaryBufferSize;
	if (null == reuse \|\| !reuse.getClass().equals(BlockingBinaryEncoder.class)) {
	return new BlockingBinaryEncoder(out, blockSize, bufferSize);
	} else {
	return ((BlockingBinaryEncoder) reuse).configure(out, blockSize, bufferSize);
	}
	}

	/**
	* Creates a {@link JsonEncoder} using the OutputStream provided for writing
	* data conforming to the Schema provided.
	* <p/>
	* {@link JsonEncoder} buffers its output. Data may not appear on the
	* underlying OutputStream until {@link Encoder#flush()} is called.
	* <p/>
	* {@link JsonEncoder} is not thread-safe.
	*
	* @param schema
	* The Schema for data written to this JsonEncoder. Cannot be null.
	* @param out
	* The OutputStream to write to. Cannot be null.
	* @return A JsonEncoder configured with <i>out</i> and <i>schema</i>
	* @throws IOException
	*/
	public JsonEncoder jsonEncoder(Schema schema, OutputStream out)
	throws IOException {
	return new JsonEncoder(schema, out);
	}

	/**
	* Creates a {@link JsonEncoder} using the OutputStream provided for writing
	* data conforming to the Schema provided with optional pretty printing.
	* <p/>
	* {@link JsonEncoder} buffers its output. Data may not appear on the
	* underlying OutputStream until {@link Encoder#flush()} is called.
	* <p/>
	* {@link JsonEncoder} is not thread-safe.
	*
	* @param schema
	* The Schema for data written to this JsonEncoder. Cannot be null.
	* @param out
	* The OutputStream to write to. Cannot be null.
	* @param pretty
	* Pretty print encoding.
	* @return A JsonEncoder configured with <i>out</i>, <i>schema</i> and <i>pretty</i>
	* @throws IOException
	*/
	public JsonEncoder jsonEncoder(Schema schema, OutputStream out, boolean pretty)
	throws IOException {
	return new JsonEncoder(schema, out, pretty);
	}

	/**
	* Creates a {@link JsonEncoder} using the {@link JsonGenerator} provided for
	* output of data conforming to the Schema provided.
	* <p/>
	* {@link JsonEncoder} buffers its output. Data may not appear on the
	* underlying output until {@link Encoder#flush()} is called.
	* <p/>
	* {@link JsonEncoder} is not thread-safe.
	*
	* @param schema
	* The Schema for data written to this JsonEncoder. Cannot be null.
	* @param gen
	* The JsonGenerator to write with. Cannot be null.
	* @return A JsonEncoder configured with <i>gen</i> and <i>schema</i>
	* @throws IOException
	* @deprecated internal method
	*/
	@Deprecated
	public JsonEncoder jsonEncoder(Schema schema, JsonGenerator gen)
	throws IOException {
	return new JsonEncoder(schema, gen);
	}

	/**
	* Creates a {@link ValidatingEncoder} that wraps the Encoder provided.
	* This ValidatingEncoder will ensure that operations against it conform
	* to the schema provided.
	* <p/>
	* Many {@link Encoder}s buffer their output. Data may not appear on the
	* underlying output until {@link Encoder#flush()} is called.
	* <p/>
	* {@link ValidatingEncoder} is not thread-safe.
	*
	* @param schema
	* The Schema to validate operations against. Cannot be null.
	* @param encoder
	* The Encoder to wrap. Cannot be be null.
	* @return A ValidatingEncoder configured to wrap <i>encoder</i> and validate
	* against <i>schema</i>
	* @throws IOException
	*/
	public ValidatingEncoder validatingEncoder(Schema schema, Encoder encoder)
	throws IOException {
	return new ValidatingEncoder(schema, encoder);
	}

	// default encoder is not mutable
	private static class DefaultEncoderFactory extends EncoderFactory {
	@Override
	public EncoderFactory configureBlockSize(int size) {
	throw new AvroRuntimeException("Default EncoderFactory cannot be configured");
	}
	@Override
	public EncoderFactory configureBufferSize(int size) {
	throw new AvroRuntimeException("Default EncoderFactory cannot be configured");
	}
	}
	}