/*
    * 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.commons.io.output;
  
  import java.io.IOException;
  import java.io.OutputStream;
  import java.io.Writer;
  import java.nio.ByteBuffer;
  import java.nio.CharBuffer;
  import java.nio.charset.Charset;
  import java.nio.charset.CharsetDecoder;
  import java.nio.charset.CoderResult;
  import java.nio.charset.CodingErrorAction;
  import java.nio.charset.StandardCharsets;
  
  import org.apache.commons.io.Charsets;
  import org.apache.commons.io.IOUtils;
  import org.apache.commons.io.build.AbstractStreamBuilder;
  import org.apache.commons.io.charset.CharsetDecoders;
  
  /**
   * {@link OutputStream} implementation that transforms a byte stream to a character stream using a specified charset encoding and writes the resulting stream to
   * a {@link Writer}. The stream is transformed using a {@link CharsetDecoder} object, guaranteeing that all charset encodings supported by the JRE are handled
   * correctly.
   * <p>
   * The output of the {@link CharsetDecoder} is buffered using a fixed size buffer. This implies that the data is written to the underlying {@link Writer} in
   * chunks that are no larger than the size of this buffer. By default, the buffer is flushed only when it overflows or when {@link #flush()} or {@link #close()}
   * is called. In general there is therefore no need to wrap the underlying {@link Writer} in a {@link java.io.BufferedWriter}. {@link WriterOutputStream} can
   * also be instructed to flush the buffer after each write operation. In this case, all available data is written immediately to the underlying {@link Writer},
   * implying that the current position of the {@link Writer} is correlated to the current position of the {@link WriterOutputStream}.
   * </p>
   * <p>
   * {@link WriterOutputStream} implements the inverse transformation of {@link java.io.OutputStreamWriter}; in the following example, writing to {@code out2}
   * would have the same result as writing to {@code out} directly (provided that the byte sequence is legal with respect to the charset encoding):
   * </p>
   * <p>
   * To build an instance, use {@link Builder}.
   * </p>
   * <pre>
   * OutputStream out = ...
   * Charset cs = ...
   * OutputStreamWriter writer = new OutputStreamWriter(out, cs);
   * WriterOutputStream out2 = WriterOutputStream.builder()
   *   .setWriter(writer)
   *   .setCharset(cs)
   *   .get();
   * </pre>
   * <p>
   * {@link WriterOutputStream} implements the same transformation as {@link java.io.InputStreamReader}, except that the control flow is reversed: both classes
   * transform a byte stream into a character stream, but {@link java.io.InputStreamReader} pulls data from the underlying stream, while
   * {@link WriterOutputStream} pushes it to the underlying stream.
   * </p>
   * <p>
   * Note that while there are use cases where there is no alternative to using this class, very often the need to use this class is an indication of a flaw in
   * the design of the code. This class is typically used in situations where an existing API only accepts an {@link OutputStream} object, but where the stream is
   * known to represent character data that must be decoded for further use.
   * </p>
   * <p>
   * Instances of {@link WriterOutputStream} are not thread safe.
   * </p>
   *
   * @see Builder
   * @see org.apache.commons.io.input.ReaderInputStream
   * @since 2.0
   */
  public class WriterOutputStream extends OutputStream {
  
      // @formatter:off
      /**
       * Builds a new {@link WriterOutputStream}.
       *
       * <p>
       * For example:
       * </p>
       * <pre>{@code
       * WriterOutputStream s = WriterOutputStream.builder()
       *   .setPath(path)
       *   .setBufferSize(8192)
       *   .setCharset(StandardCharsets.UTF_8)
       *   .setWriteImmediately(false)
       *   .get();}
       * </pre>
       *
       * @see #get()
       * @since 2.12.0
      */
     // @formatter:on
     public static class Builder extends AbstractStreamBuilder<WriterOutputStream, Builder> {
 
         private CharsetDecoder charsetDecoder;
         private boolean writeImmediately;
 
         /**
          * Constructs a new Builder.
          */
         public Builder() {
             this.charsetDecoder = getCharset().newDecoder();
         }
 
         /**
          * Builds a new {@link WriterOutputStream}.
          * <p>
          * You must set input that supports {@link #getWriter()} on this builder, otherwise, this method throws an exception.
          * </p>
          * <p>
          * This builder use the following aspects:
          * </p>
          * <ul>
          * <li>{@link #getWriter()}</li>
          * <li>{@link #getBufferSize()}</li>
          * <li>charsetDecoder</li>
          * <li>writeImmediately</li>
          * </ul>
          *
          * @return a new instance.
          * @throws UnsupportedOperationException if the origin cannot provide a Writer.
          * @see #getWriter()
          */
         @SuppressWarnings("resource")
         @Override
         public WriterOutputStream get() throws IOException {
             return new WriterOutputStream(getWriter(), charsetDecoder, getBufferSize(), writeImmediately);
         }
 
         @Override
         public Builder setCharset(final Charset charset) {
             super.setCharset(charset);
             this.charsetDecoder = getCharset().newDecoder();
             return this;
         }
 
         @Override
         public Builder setCharset(final String charset) {
             super.setCharset(charset);
             this.charsetDecoder = getCharset().newDecoder();
             return this;
         }
 
         /**
          * Sets the charset decoder.
          *
          * @param charsetDecoder the charset decoder.
          * @return this
          */
         public Builder setCharsetDecoder(final CharsetDecoder charsetDecoder) {
             this.charsetDecoder = charsetDecoder != null ? charsetDecoder : getCharsetDefault().newDecoder();
             super.setCharset(this.charsetDecoder.charset());
             return this;
         }
 
         /**
          * Sets whether the output buffer will be flushed after each write operation ({@code true}), i.e. all available data will be written to the underlying
          * {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when {@link #flush()} or {@link #close()}
          * is called.
          *
          * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
          *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
          *                         {@link #flush()} or {@link #close()} is called.
          * @return this
          */
         public Builder setWriteImmediately(final boolean writeImmediately) {
             this.writeImmediately = writeImmediately;
             return this;
         }
 
     }
 
     private static final int BUFFER_SIZE = IOUtils.DEFAULT_BUFFER_SIZE;
 
     /**
      * Constructs a new {@link Builder}.
      *
      * @return a new {@link Builder}.
      * @since 2.12.0
      */
     public static Builder builder() {
         return new Builder();
     }
 
     /**
      * Checks if the JDK in use properly supports the given charset.
      *
      * @param charset the charset to check the support for
      */
     private static void checkIbmJdkWithBrokenUTF16(final Charset charset) {
         if (!StandardCharsets.UTF_16.name().equals(charset.name())) {
             return;
         }
         final String TEST_STRING_2 = "v\u00e9s";
         final byte[] bytes = TEST_STRING_2.getBytes(charset);
 
         final CharsetDecoder charsetDecoder2 = charset.newDecoder();
         final ByteBuffer bb2 = ByteBuffer.allocate(16);
         final CharBuffer cb2 = CharBuffer.allocate(TEST_STRING_2.length());
         final int len = bytes.length;
         for (int i = 0; i < len; i++) {
             bb2.put(bytes[i]);
             bb2.flip();
             try {
                 charsetDecoder2.decode(bb2, cb2, i == len - 1);
             } catch (final IllegalArgumentException e) {
                 throw new UnsupportedOperationException("UTF-16 requested when running on an IBM JDK with broken UTF-16 support. "
                         + "Please find a JDK that supports UTF-16 if you intend to use UF-16 with WriterOutputStream");
             }
             bb2.compact();
         }
         cb2.rewind();
         if (!TEST_STRING_2.equals(cb2.toString())) {
             throw new UnsupportedOperationException("UTF-16 requested when running on an IBM JDK with broken UTF-16 support. "
                     + "Please find a JDK that supports UTF-16 if you intend to use UF-16 with WriterOutputStream");
         }
 
     }
 
     private final Writer writer;
     private final CharsetDecoder decoder;
 
     private final boolean writeImmediately;
 
     /**
      * ByteBuffer used as input for the decoder. This buffer can be small as it is used only to transfer the received data to the decoder.
      */
     private final ByteBuffer decoderIn = ByteBuffer.allocate(128);
 
     /**
      * CharBuffer used as output for the decoder. It should be somewhat larger as we write from this buffer to the underlying Writer.
      */
     private final CharBuffer decoderOut;
 
     /**
      * Constructs a new {@link WriterOutputStream} that uses the default character encoding and with a default output buffer size of {@value #BUFFER_SIZE}
      * characters. The output buffer will only be flushed when it overflows or when {@link #flush()} or {@link #close()} is called.
      *
      * @param writer the target {@link Writer}
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer) {
         this(writer, Charset.defaultCharset(), BUFFER_SIZE, false);
     }
 
     /**
      * Constructs a new {@link WriterOutputStream} with a default output buffer size of {@value #BUFFER_SIZE} characters. The output buffer will only be flushed
      * when it overflows or when {@link #flush()} or {@link #close()} is called.
      *
      * @param writer  the target {@link Writer}
      * @param charset the charset encoding
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final Charset charset) {
         this(writer, charset, BUFFER_SIZE, false);
     }
 
     /**
      * Constructs a new {@link WriterOutputStream}.
      *
      * @param writer           the target {@link Writer}
      * @param charset          the charset encoding
      * @param bufferSize       the size of the output buffer in number of characters
      * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final Charset charset, final int bufferSize, final boolean writeImmediately) {
         // @formatter:off
         this(writer,
             Charsets.toCharset(charset).newDecoder()
                     .onMalformedInput(CodingErrorAction.REPLACE)
                     .onUnmappableCharacter(CodingErrorAction.REPLACE)
                     .replaceWith("?"),
              bufferSize,
              writeImmediately);
         // @formatter:on
     }
 
     /**
      * Constructs a new {@link WriterOutputStream} with a default output buffer size of {@value #BUFFER_SIZE} characters. The output buffer will only be flushed
      * when it overflows or when {@link #flush()} or {@link #close()} is called.
      *
      * @param writer  the target {@link Writer}
      * @param decoder the charset decoder
      * @since 2.1
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final CharsetDecoder decoder) {
         this(writer, decoder, BUFFER_SIZE, false);
     }
 
     /**
      * Constructs a new {@link WriterOutputStream}.
      *
      * @param writer           the target {@link Writer}
      * @param decoder          the charset decoder
      * @param bufferSize       the size of the output buffer in number of characters
      * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @since 2.1
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final CharsetDecoder decoder, final int bufferSize, final boolean writeImmediately) {
         checkIbmJdkWithBrokenUTF16(CharsetDecoders.toCharsetDecoder(decoder).charset());
         this.writer = writer;
         this.decoder = CharsetDecoders.toCharsetDecoder(decoder);
         this.writeImmediately = writeImmediately;
         this.decoderOut = CharBuffer.allocate(bufferSize);
     }
 
     /**
      * Constructs a new {@link WriterOutputStream} with a default output buffer size of {@value #BUFFER_SIZE} characters. The output buffer will only be flushed
      * when it overflows or when {@link #flush()} or {@link #close()} is called.
      *
      * @param writer      the target {@link Writer}
      * @param charsetName the name of the charset encoding
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final String charsetName) {
         this(writer, charsetName, BUFFER_SIZE, false);
     }
 
     /**
      * Constructs a new {@link WriterOutputStream}.
      *
      * @param writer           the target {@link Writer}
      * @param charsetName      the name of the charset encoding
      * @param bufferSize       the size of the output buffer in number of characters
      * @param writeImmediately If {@code true} the output buffer will be flushed after each write operation, i.e. all available data will be written to the
      *                         underlying {@link Writer} immediately. If {@code false}, the output buffer will only be flushed when it overflows or when
      *                         {@link #flush()} or {@link #close()} is called.
      * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()}
      */
     @Deprecated
     public WriterOutputStream(final Writer writer, final String charsetName, final int bufferSize, final boolean writeImmediately) {
         this(writer, Charsets.toCharset(charsetName), bufferSize, writeImmediately);
     }
 
     /**
      * Close the stream. Any remaining content accumulated in the output buffer will be written to the underlying {@link Writer}. After that
      * {@link Writer#close()} will be called.
      *
      * @throws IOException if an I/O error occurs.
      */
     @Override
     public void close() throws IOException {
         processInput(true);
         flushOutput();
         writer.close();
     }
 
     /**
      * Flush the stream. Any remaining content accumulated in the output buffer will be written to the underlying {@link Writer}. After that
      * {@link Writer#flush()} will be called.
      *
      * @throws IOException if an I/O error occurs.
      */
     @Override
     public void flush() throws IOException {
         flushOutput();
         writer.flush();
     }
 
     /**
      * Flush the output.
      *
      * @throws IOException if an I/O error occurs.
      */
     private void flushOutput() throws IOException {
         if (decoderOut.position() > 0) {
             writer.write(decoderOut.array(), 0, decoderOut.position());
             decoderOut.rewind();
         }
     }
 
     /**
      * Decode the contents of the input ByteBuffer into a CharBuffer.
      *
      * @param endOfInput indicates end of input
      * @throws IOException if an I/O error occurs.
      */
     private void processInput(final boolean endOfInput) throws IOException {
         // Prepare decoderIn for reading
         decoderIn.flip();
         CoderResult coderResult;
         while (true) {
             coderResult = decoder.decode(decoderIn, decoderOut, endOfInput);
             if (coderResult.isOverflow()) {
                 flushOutput();
             } else if (coderResult.isUnderflow()) {
                 break;
             } else {
                 // The decoder is configured to replace malformed input and unmappable characters,
                 // so we should not get here.
                 throw new IOException("Unexpected coder result");
             }
         }
         // Discard the bytes that have been read
         decoderIn.compact();
     }
 
     /**
      * Write bytes from the specified byte array to the stream.
      *
      * @param b the byte array containing the bytes to write
      * @throws IOException if an I/O error occurs.
      */
     @Override
     public void write(final byte[] b) throws IOException {
         write(b, 0, b.length);
     }
 
     /**
      * Write bytes from the specified byte array to the stream.
      *
      * @param b   the byte array containing the bytes to write
      * @param off the start offset in the byte array
      * @param len the number of bytes to write
      * @throws IOException if an I/O error occurs.
      */
     @Override
     public void write(final byte[] b, int off, int len) throws IOException {
         while (len > 0) {
             final int c = Math.min(len, decoderIn.remaining());
             decoderIn.put(b, off, c);
             processInput(false);
             len -= c;
             off += c;
         }
         if (writeImmediately) {
             flushOutput();
         }
     }
 
     /**
      * Write a single byte to the stream.
      *
      * @param b the byte to write
      * @throws IOException if an I/O error occurs.
      */
     @Override
     public void write(final int b) throws IOException {
         write(new byte[] { (byte) b }, 0, 1);
     }
 }