[Java] Clarify thread safety of Decoders returned by DecoderFactory. (#…

…3278)

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

@@ -24,10 +24,14 @@
 
 /**
  * A factory for creating and configuring {@link Decoder}s.
- * <p/>
+ * <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.
+ * </p>
+ * <p>
+ * Although Factories are thread-safe the {@link Decoder}s they return are not.
+ * </p>
  *
  * @see Decoder
  */
@@ -70,7 +74,7 @@ public static DecoderFactory get() {
    *             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>
@@ -87,7 +91,7 @@ public DecoderFactory configureDecoderBufferSize(int size) {
   /**
    * 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() {
@@ -156,7 +160,7 @@ public BinaryDecoder binaryDecoder(InputStream in, BinaryDecoder reuse) {
    * 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
@@ -227,11 +231,11 @@ public BinaryDecoder createBinaryDecoder(byte[] bytes, BinaryDecoder 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) {