/*
 * 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.juneau.commons.utils;

import static org.apache.juneau.commons.utils.Exceptions.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.f;
import static org.apache.juneau.commons.utils.Shorts.eq;
import static org.apache.juneau.commons.utils.Shorts.ioex;
import static org.apache.juneau.commons.utils.SystemUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.io.*;
import java.nio.charset.*;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.util.function.*;
import java.util.zip.*;

import org.apache.juneau.commons.io.*;
import org.apache.juneau.commons.logging.*;

/**
 * Various I/O related utility methods.
 */
@SuppressWarnings({
   "java:S5164", // Cleanup method provided: cleanupThreadLocals()
   "null", // Eclipse null analysis does not recognise isNotNull()/isNotEmpty() guards on the optional buffer caches and the saved IOException.
   "resource" // Wrapper readers/writers (InputStreamReader, OutputStreamWriter, BufferedReader) are built over caller-owned streams and must not close them.
})
public class IoUtils {

   /** UTF-8 charset */
   public static final Charset UTF8 = StandardCharsets.UTF_8;

   /** Reusable empty input stream. */
   public static final InputStream EMPTY_INPUT_STREAM = new InputStream() {
      @Override
      public int read() {
         return -1;  // end of stream
      }
   };

   private static final int BUFF_SIZE = 1024;

   private static final ThreadLocal<byte[]> BYTE_BUFFER_CACHE = (isTrue(env("juneau.disableIoBufferReuse", false)) ? null : new ThreadLocal<>());
   private static final ThreadLocal<char[]> CHAR_BUFFER_CACHE = (isTrue(env("juneau.disableIoBufferReuse", false)) ? null : new ThreadLocal<>());
   static final AtomicInteger BYTE_BUFFER_CACHE_HITS = new AtomicInteger();

   static final AtomicInteger BYTE_BUFFER_CACHE_MISSES = new AtomicInteger();
   static final AtomicInteger CHAR_BUFFER_CACHE_HITS = new AtomicInteger();
   static final AtomicInteger CHAR_BUFFER_CACHE_MISSES = new AtomicInteger();
   static {
      shutdownMessage(() -> "Byte buffer cache:  hits=" + BYTE_BUFFER_CACHE_HITS.get() + ", misses=" + BYTE_BUFFER_CACHE_MISSES);
      shutdownMessage(() -> "Char buffer cache:  hits=" + CHAR_BUFFER_CACHE_HITS.get() + ", misses=" + CHAR_BUFFER_CACHE_MISSES);
   }

   /**
    * Cleans up thread-local buffer caches for the current thread.
    *
    * <p>
    * This method should be called when a thread is finished using the buffer caches to prevent memory leaks
    * in thread pool environments where threads are reused.
    */
   public static void cleanupThreadLocals() {
      if (BYTE_BUFFER_CACHE != null) {
         BYTE_BUFFER_CACHE.remove();
      }
      if (CHAR_BUFFER_CACHE != null) {
         CHAR_BUFFER_CACHE.remove();
      }
   }

   /** Reusable empty reader. */
   public static final Reader EMPTY_READER = new Reader() {
      @Override
      public void close() throws IOException { /* no-op */ }

      @Override
      public int read() {
         return -1;  // end of stream
      }

      @Override
      public int read(char[] cbuf, int off, int len) throws IOException {
         return -1;  // end of stream
      }
   };

   /**
    * Close all specified input streams, output streams, readers, and writers.
    *
    * @param o
    *    The list of all objects to close.
    *    <jk>null</jk> entries are ignored.
    * @throws IOException Thrown by underlying stream.
    */
   public static void close(Object...o) throws IOException {
      IOException ex = null;
      for (var o2 : o) {
         try {
            if (o2 instanceof InputStream o3)
               o3.close();
            if (o2 instanceof OutputStream o3)
               o3.close();
            if (o2 instanceof Reader o3)
               o3.close();
            if (o2 instanceof Writer o3)
               o3.close();
         } catch (IOException e) {
            ex = e;
         }
      }
      if (isNotNull(ex))
         throw ex;
   }

   /**
    * Reads and discards the remainder of a reader or input stream, ignoring any exceptions.
    *
    * <p>
    * Reads until end-of-stream using a 256-unit buffer.  Any {@link IOException} stops the drain silently.
    * No-op if the object is <jk>null</jk> or is neither a {@link Reader} nor an {@link InputStream}.
    * The stream is not closed.
    *
    * @param in The reader or input stream to drain.
    */
   public static void drainQuietly(Closeable in) {
      try {
         if (in instanceof Reader r) {
            var buf = new char[256];
            while (r.read(buf) != -1) { /* discard */ }
         } else if (in instanceof InputStream is) {
            var buf = new byte[256];
            while (is.read(buf) != -1) { /* discard */ }
         }
      } catch (IOException ignored) {
         // best-effort
      }
   }

   /**
    * Close input stream and ignore any exceptions.
    *
    * <p>
    * No-op if input stream is <jk>null</jk>.
    *
    * @param is The input stream to close.
    */
   public static void closeQuietly(InputStream is) {
      if (isNotNull(is))
         safe(is::close);
   }

   /**
    * Quietly close all specified input streams, output streams, readers, and writers.
    *
    * @param o The list of all objects to quietly close.
    */
   public static void closeQuietly(Object...o) {
      for (var o2 : o) {
         if (o2 instanceof InputStream o3)
            closeQuietly(o3);
         if (o2 instanceof OutputStream o3)
            closeQuietly(o3);
         if (o2 instanceof Reader o3)
            closeQuietly(o3);
         if (o2 instanceof Writer o3)
            closeQuietly(o3);
      }
   }

   /**
    * Close output stream and ignore any exceptions.
    *
    * <p>
    * No-op if output stream is <jk>null</jk>.
    *
    * @param os The output stream to close.
    */
   public static void closeQuietly(OutputStream os) {
      if (isNotNull(os))
         runQuietly(os::close);
   }

   /**
    * Close reader and ignore any exceptions.
    *
    * <p>
    * No-op if reader is <jk>null</jk>.
    *
    * @param r The reader to close.
    */
   public static void closeQuietly(Reader r) {
      if (isNotNull(r))
         runQuietly(r::close);
   }

   /**
    * Close writer and ignore any exceptions.
    *
    * <p>
    * No-op if writer is <jk>null</jk>.
    *
    * @param w The writer to close.
    */
   public static void closeQuietly(Writer w) {
      if (isNotNull(w))
         runQuietly(w::close);
   }

   /**
    * Counts the number of bytes in the input stream and then closes the stream.
    *
    * @param is The input stream to read from.  Can be <jk>null</jk> (returns <c>0</c>).
    * @return The number of bytes read.
    * @throws IOException Thrown by underlying stream.
    */
   public static long count(InputStream is) throws IOException {
      if (is == null)
         return 0;
      var c = 0l;
      var i = 0l;
      try {
         while ((i = is.skip(1024)) != 0)
            c += i;
      } finally {
         is.close();
      }
      return c;
   }

   /**
    * Counts the number of characters in the reader and then closes the reader.
    *
    * @param r The reader to read from.  Can be <jk>null</jk> (returns <c>0</c>).
    * @return The number of characters read.
    * @throws IOException Thrown by underlying stream.
    */
   public static long count(Reader r) throws IOException {
      if (r == null)
         return 0;
      var c = 0l;
      var i = 0l;
      try {
         while ((i = r.skip(1024)) != 0)
            c += i;
      } finally {
         r.close();
      }
      return c;
   }

   /**
    * Flushes multiple output streams and writers in a single call.
    *
    * @param o
    *    The objects to flush.
    *    <jk>null</jk> entries are ignored.
    * @throws IOException Thrown by underlying stream.
    */
   public static void flush(Object...o) throws IOException {
      IOException ex = null;
      for (var o2 : o) {
         try {
            if (o2 instanceof OutputStream o3)
               o3.flush();
            if (o2 instanceof Writer o3)
               o3.flush();
         } catch (IOException e) {
            ex = e;
         }
      }
      if (isNotNull(ex))
         throw ex;
   }

   /**
    * Loads a text file from either the file system or classpath.
    *
    * @param name The file name.  Must not be <jk>null</jk>.
    * @param paths The paths to search.
    * @return The file contents, or <jk>null</jk> if not found.
    * @throws IOException Thrown by underlying stream.
    */
   public static String loadSystemResourceAsString(String name, String...paths) throws IOException {
      for (var path : paths) {
         var p = new File(path);
         if (p.exists()) {
            var f = new File(p, name);
            if (f.exists() && f.canRead())
               return read(f);
         }
      }
      var cl = Thread.currentThread().getContextClassLoader();
      if (cl == null)
         cl = ClassLoader.getSystemClassLoader();
      for (var path : paths) {
         var n = eq(path, ".") ? name : path + '/' + name;
         try (var is = cl.getResourceAsStream(n)) {
            if (isNotNull(is))
               return read(is);
         }
         try (var is = ClassLoader.getSystemResourceAsStream(n)) {
            if (isNotNull(is))
               return read(is);
         }
      }
      return null;
   }

   /**
    * Pipes the contents of the specified <c>Reader</c> to the specified <c>Writer</c> a line at a time.
    *
    * <p>
    * Writer is flushed after every line.  Typically useful when writing to consoles.
    *
    * @param in
    *    The reader to pipe from.
    *    <br>Can be <jk>null</jk> (returns <c>0</c>).
    *    <br>Reader is automatically closed.
    * @param out
    *    The file to write the output to.
    *    <br>Can be <jk>null</jk> (returns <c>0</c>).
    *    <br>Writer is flushed but not automatically closed.
    * @return
    *    The number of characters piped.
    * @throws IOException Thrown by underlying stream.
    */
   public static long pipeLines(Reader in, Writer out) throws IOException {
      if (in == null || out == null)
         return 0;
      var total = 0l;
      try (var in2 = in) {
         try (var s = new Scanner(in2)) {
            while (s.hasNextLine()) {
               var l = s.nextLine();
               if (isNotNull(l)) {
                  out.write(l);
                  out.write("\n");
                  out.flush();
                  total += l.length() + 1;
               }
            }
         }
      }
      return total;
   }

   /**
    * Reads the specified byte array containing UTF-8 into a string.
    *
    * @param in
    *    The input.
    *    <br>Can be <jk>null</jk>.
    * @return The new string, or <jk>null</jk> if the input was null.
    */
   public static String read(byte[] in) {
      return read(in, UTF8);
   }

   /**
    * Reads the specified byte array into a string.
    *
    * @param in
    *    The input.
    *    <br>Can be <jk>null</jk>.
    * @param charset The character set to use for decoding.  Must not be <jk>null</jk> when the input is non-<jk>null</jk>.
    * @return The new string, or <jk>null</jk> if the input was null.
    */
   public static String read(byte[] in, Charset charset) {
      if (in == null)
         return null;
      return new String(in, charset);
   }

   /**
    * Reads the contents of a file into a string.
    *
    * <p>
    * Assumes default character encoding.
    *
    * @param in
    *  The file to read.
    *  <br>Can be <jk>null</jk>.
    * @return
    *  The contents of the reader as a string, or <jk>null</jk> if file does not exist.
    * @throws IOException If a problem occurred trying to read from the reader.
    */
   public static String read(File in) throws IOException {
      if (in == null || ! in.exists())
         return null;
      try (var r = FileReaderBuilder.create(in).build()) {
         return read(r, in.length());
      }
   }

   /**
    * Reads the contents of an input stream into a string.
    *
    * <p>
    * Assumes UTF-8 encoding.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @return
    *    The contents of the reader as a string, or <jk>null</jk> if the input stream was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the input stream.
    */
   public static String read(InputStream in) throws IOException {
      return read(in, UTF8);
   }

   /**
    * Reads the contents of an input stream into a string using the specified charset.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param cs
    *    The charset of the contents of the input stream.  Must not be <jk>null</jk> when the input stream is non-<jk>null</jk>.
    * @return
    *    The contents of the reader as a string or <jk>null</jk> if input stream was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the input stream.
    */
   public static String read(InputStream in, Charset cs) throws IOException {
      if (in == null)
         return null;
      try (var isr = new InputStreamReader(in, cs)) {
         return read(isr);
      }
   }

   /**
    * Reads the contents of an input stream into a string using the specified charset.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param cs
    *    The charset of the contents of the input stream.  Must not be <jk>null</jk> when the input stream is non-<jk>null</jk>.
    * @param onException Consumer of any {@link IOException I/O exceptions}.  Must not be <jk>null</jk> (invoked on I/O error).
    * @return
    *    The contents of the reader as a string or <jk>null</jk> if input stream was <jk>null</jk>.
    */
   public static String read(InputStream in, Charset cs, Consumer<IOException> onException) {
      if (in == null)
         return null;
      try (var isr = new InputStreamReader(in, cs)) {
         return read(isr);
      } catch (IOException e) {
         onException.accept(e);
         return null;
      }
   }

   /**
    * Reads the contents of an input stream into a string.
    *
    * <p>
    * Assumes UTF-8 encoding.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param onException Consumer of any {@link IOException I/O exceptions}.  Must not be <jk>null</jk> (invoked on I/O error).
    * @return
    *    The contents of the reader as a string, or <jk>null</jk> if the input stream was <jk>null</jk>.
    */
   public static String read(InputStream in, Consumer<IOException> onException) {
      return read(in, UTF8, onException);
   }

   /**
    * Reads the contents of an input stream into a string, reading up to the specified maximum number of bytes.
    *
    * <p>
    * Assumes UTF-8 encoding.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param maxBytes
    *    The maximum number of bytes to read, or <c>-1</c> to read all bytes.
    * @return
    *    The contents of the input stream as a string, or <jk>null</jk> if the input stream was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the input stream.
    */
   public static String read(InputStream in, int maxBytes) throws IOException {
      return read(in, maxBytes, UTF8);
   }

   /**
    * Reads the contents of an input stream into a string using the specified charset, reading up to the specified maximum number of bytes.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param maxBytes
    *    The maximum number of bytes to read, or <c>-1</c> to read all bytes.
    * @param cs
    *    The charset of the contents of the input stream.  Must not be <jk>null</jk> when the input stream is non-<jk>null</jk>.
    * @return
    *    The contents of the input stream as a string, or <jk>null</jk> if the input stream was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the input stream.
    */
   public static String read(InputStream in, int maxBytes, Charset cs) throws IOException {
      if (in == null)
         return null;
      try (var in2 = in) {
         var bytes = readBytes(in2, maxBytes);
         return new String(bytes, cs);
      }
   }

   /**
    * Reads the contents of an input stream into a string, reading up to the specified maximum number of bytes.
    *
    * <p>
    * Assumes UTF-8 encoding.
    *
    * @param in
    *    The input stream.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param maxBytes
    *    The maximum number of bytes to read, or <c>-1</c> to read all bytes.
    * @return
    *    The contents of the input stream as a string, or <jk>null</jk> if the input stream was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the input stream.
    */
   public static String read(InputStream in, long maxBytes) throws IOException {
      if (maxBytes > Integer.MAX_VALUE)
         maxBytes = Integer.MAX_VALUE;
      return read(in, (int)maxBytes, UTF8);
   }

   /**
    * Pipes the specified object to the specified output stream.
    *
    * @param in
    *    The input byte array.
    *    <br>Can be <jk>null</jk> or any of the following types:
    *    <ul>
    *       <li>{@link Reader}
    *       <li>{@link InputStream}
    *       <li>{@link File}
    *       <li>byte array.
    *    </ul>
    * @return The input converted to a string, or <jk>null</jk> if the input was <jk>null</jk>.
    * @throws IOException If thrown from output stream.
    * @throws IllegalArgumentException If the input is non-<jk>null</jk> but not one of the supported types.
    */
   public static String read(Object in) throws IOException {
      if (in == null)
         return null;
      if (in instanceof Reader in2)
         return read(in2);
      if (in instanceof InputStream in2)
         return read(in2);
      if (in instanceof File in2)
         return read(in2);
      if (in instanceof byte[] in2)
         return read(in2);
      throw iaex("Invalid type passed to read:  %s", ClassUtils.className(in));
   }

   /**
    * Reads the contents of a path into a string.
    *
    * <p>
    * Assumes default character encoding.
    *
    * @param in
    *  The path to read.
    *  <br>Can be <jk>null</jk>.
    * @return
    *  The contents of the reader as a string, or <jk>null</jk> if path does not exist.
    * @throws IOException If a problem occurred trying to read from the reader.
    * @since 9.1.0
    */
   public static String read(Path in) throws IOException {
      if (in == null || ! Files.exists(in)) {
         return null;
      }
      try (var r = PathReaderBuilder.create(in).build()) {
         return read(r, Files.size(in));
      }
   }

   /**
    * Reads the contents of a reader into a string.
    *
    * @param in
    *    The input reader.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @return
    *    The contents of the reader as a string, or <jk>null</jk> if the reader was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the reader.
    */
   public static String read(Reader in) throws IOException {
      try (var in2 = in) {
         return read(in, -1);
      }
   }

   /**
    * Reads the contents of a reader into a string.
    *
    * @param in
    *    The input reader.
    *    <br>Can be <jk>null</jk>.
    *    <br>Stream is automatically closed.
    * @param onException Consumer of any {@link IOException I/O exceptions}.  Must not be <jk>null</jk> (invoked on I/O error).
    * @return
    *    The contents of the reader as a string, or <jk>null</jk> if the reader was <jk>null</jk>.
    */
   public static String read(Reader in, Consumer<IOException> onException) {
      try (var in2 = in) {
         return read(in, -1);
      } catch (IOException e) {
         onException.accept(e);
         return null;
      }
   }

   /**
    * Reads the specified input into a {@link String} until the end of the input is reached.
    *
    * @param in
    *    The input reader.
    *    <br>Can be <jk>null</jk>.
    *    <br>String is automatically closed.
    * @param expectedLength
    *    Specify a positive number if the length of the input is known, or <c>-1</c> if unknown.
    * @return
    *    The contents of the reader as a string, or <jk>null</jk> if the reader was <jk>null</jk>.
    * @throws IOException If a problem occurred trying to read from the reader.
    */
   public static String read(Reader in, long expectedLength) throws IOException {
      if (in == null)
         return null;
      try (var in2 = in) {
         var sb = new StringBuilder(buffSize(expectedLength)); // Assume they're ASCII characters.
         var buf = charBuffer((int)expectedLength);
         var i = 0;
         while ((i = in2.read(buf)) != -1)
            sb.append(buf, 0, i);
         return sb.toString();
      }
   }

   /**
    * Read the specified file into a byte array.
    *
    * @param in
    *    The file to read into a byte array.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    * @return The contents of the file as a byte array.  Never <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public static byte[] readBytes(File in) throws IOException {
      return readBytes(in, -1);
   }

   /**
    * Read the specified file into a byte array.
    *
    * @param in
    *    The file to read into a byte array.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    * @param maxBytes
    *    The maximum number of bytes to read, or <jk>-1</jk> to read all bytes.
    * @return The contents of the file as a byte array.  Never <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public static byte[] readBytes(File in, int maxBytes) throws IOException {
      if (in == null || ! (in.exists() && in.canRead()))
         return new byte[0];
      try (var is = new FileInputStream(in)) {
         return readBytes(is, maxBytes);
      }
   }

   /**
    * Reads the specified input stream into the specified byte array.
    *
    * @param in
    *    The input stream to read.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    *    <br>Stream is automatically closed.
    * @return A byte array containing the contents.  Never <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public static byte[] readBytes(InputStream in) throws IOException {
      try (var in2 = in) {
         return readBytes(in2, -1);
      }
   }

   /**
    * Reads the specified input stream into the specified byte array.
    *
    * @param in
    *    The input stream to read.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    *    <br>Stream is not automatically closed.
    * @param maxBytes
    *    The maximum number of bytes or <c>-1</c> to read the entire stream.
    * @return A byte array containing the contents.  Never <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public static byte[] readBytes(InputStream in, int maxBytes) throws IOException {
      if (in == null)
         return new byte[0];
      var buff = new ByteArrayOutputStream(buffSize(maxBytes));
      var nRead = 0;
      var b = byteBuffer(maxBytes);
      while ((nRead = in.read(b, 0, b.length)) != -1)
         buff.write(b, 0, nRead);
      buff.flush();
      return buff.toByteArray();
   }

   /**
    * Reads the specified input stream into the specified byte array.
    *
    * @param in
    *    The input stream to read.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    *    <br>Stream is automatically closed.
    * @return A byte array containing the contents.  Never <jk>null</jk>.
    * @throws IOException Thrown by underlying stream.
    */
   public static byte[] readBytes(Reader in) throws IOException {
      if (in == null)
         return new byte[0];
      try (var in2 = in) {
         return read(in2, -1).getBytes();
      }
   }

   /**
    * Inflates (decompresses) the specified compressed bytes with a hard ceiling on the total output size and an
    * effective output-to-input ratio guard.
    *
    * <p>
    * Building on the bounded-copy family in this class (such as {@link #readBytes(InputStream,int)} and
    * {@link #pipe(InputStream,OutputStream,long)}), this method decompresses untrusted input without letting a
    * small compressed payload expand into an unbounded allocation.  Two independent limits are enforced
    * <i>during</i> inflation, so a violating stream is aborted before its full output is ever materialized:
    * <ul>
    *    <li><b>Absolute cap.</b> If the running output size would exceed <jv>maxOutputBytes</jv>, an
    *       {@link IOException} is thrown.
    *    <li><b>Ratio guard.</b> If the running output size would exceed <jv>maxRatio</jv> times the compressed
    *       input length, an {@link IOException} is thrown &mdash; this catches a highly-compressible payload even
    *       when the absolute cap is generous.
    * </ul>
    *
    * @param compressed
    *    The compressed input bytes.
    *    <br>Can be <jk>null</jk> (returns an empty array).
    * @param nowrap
    *    Pass <jk>true</jk> for a raw (headerless) DEFLATE stream, or <jk>false</jk> for a zlib-wrapped stream.
    *    <br>Must match the format used to compress the input.
    * @param maxOutputBytes
    *    The maximum number of decompressed bytes to allow.
    *    <br>Values <c>&lt;= 0</c> disable the absolute cap (mirroring the <c>maxLength</c> convention used
    *    elsewhere); the ratio guard, if enabled, still applies.
    * @param maxRatio
    *    The maximum allowed ratio of output size to compressed input size.
    *    <br>Values <c>&lt;= 0</c> disable the ratio guard.
    * @return The decompressed bytes.  Never <jk>null</jk>.
    * @throws IOException
    *    If the input is not valid for the selected format, or if either the absolute cap or the ratio guard is
    *    exceeded.
    * @since 10.0.0
    */
   public static byte[] inflate(byte[] compressed, boolean nowrap, long maxOutputBytes, int maxRatio) throws IOException {
      if (compressed == null || compressed.length == 0)
         return new byte[0];
      var cap = maxOutputBytes <= 0 ? Long.MAX_VALUE : maxOutputBytes;
      var ratioLimit = maxRatio <= 0 ? Long.MAX_VALUE : (long)compressed.length * maxRatio;
      var inflater = new Inflater(nowrap);
      // Inflater isn't AutoCloseable at this module's source/target level, so route end() through
      // try-with-resources via a Closeable method reference (inflate() already declares throws IOException).
      try (Closeable end = inflater::end) {
         inflater.setInput(compressed);
         return inflateAll(inflater, cap, ratioLimit, maxRatio);
      }
   }

   private static byte[] inflateAll(Inflater inflater, long cap, long ratioLimit, int maxRatio) throws IOException {
      var out = new ByteArrayOutputStream(BUFF_SIZE);
      var buf = new byte[BUFF_SIZE];
      var total = 0L;
      while (true) {
         var n = inflateChunk(inflater, buf);
         if (n > 0) {
            total += n;
            checkInflateLimits(total, cap, ratioLimit, maxRatio);
            out.write(buf, 0, n);
         } else if (inflater.finished() || inflater.needsDictionary() || inflater.needsInput()) {
            break;
         }
      }
      return out.toByteArray();
   }

   private static int inflateChunk(Inflater inflater, byte[] buf) throws IOException {
      try {
         return inflater.inflate(buf);
      } catch (DataFormatException e) {
         throw ioex(e, "Invalid compressed data");
      }
   }

   private static void checkInflateLimits(long total, long cap, long ratioLimit, int maxRatio) throws IOException {
      if (total > cap)
         throw ioex("Inflated output exceeds maximum allowed %s bytes", cap);
      if (total > ratioLimit)
         throw ioex("Inflated output-to-input ratio exceeds maximum allowed %s", maxRatio);
   }

   /**
    * Wraps the specified reader in a buffered reader.
    *
    * @param r The reader being wrapped.  Can be <jk>null</jk> (returns <jk>null</jk>).
    * @return
    *    The reader wrapped in a {@link BufferedReader}, or the original {@link Reader} if it's already a buffered
    *    reader, or <jk>null</jk> if the argument was <jk>null</jk>.
    */
   public static Reader toBufferedReader(Reader r) {
      if (r == null || r instanceof BufferedReader || r instanceof StringReader)
         return r;
      return new BufferedReader(r);
   }

   private static int buffSize(long max) {
      return (max > 0 && max < BUFF_SIZE) ? (int)max : BUFF_SIZE;
   }

   private static byte[] byteBuffer(int maxBytes) {
      if (isNotNull(BYTE_BUFFER_CACHE)) {
         var x = BYTE_BUFFER_CACHE.get();
         if (x == null) {
            x = new byte[BUFF_SIZE];
            BYTE_BUFFER_CACHE.set(x);
            BYTE_BUFFER_CACHE_MISSES.incrementAndGet();
         } else {
            BYTE_BUFFER_CACHE_HITS.incrementAndGet();
         }
         return x;
      }
      return new byte[buffSize(maxBytes)];
   }

   private static char[] charBuffer(int maxChars) {
      if (isNotNull(CHAR_BUFFER_CACHE)) {
         var x = CHAR_BUFFER_CACHE.get();
         if (x == null) {
            x = new char[BUFF_SIZE];
            CHAR_BUFFER_CACHE.set(x);
            CHAR_BUFFER_CACHE_MISSES.incrementAndGet();
         } else {
            CHAR_BUFFER_CACHE_HITS.incrementAndGet();
         }
         return x;
      }
      return new char[buffSize(maxChars)];
   }

   //-----------------------------------------------------------------------------------------------------------------
   // Canonical-named methods (pipe overloads delegate to these)
   //-----------------------------------------------------------------------------------------------------------------

   /** Pipes bytes to output stream.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(byte[] in, OutputStream out, int maxBytes) throws IOException {
      if (in == null || out == null)
         return 0;
      var length = (maxBytes < 0 || maxBytes > in.length) ? in.length : maxBytes;
      out.write(in, 0, length);
      return length;
   }

   /** Pipes input stream to output stream.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(InputStream in, OutputStream out) throws IOException {
      try (var in2 = in) {
         return pipe(in, out, -1L);
      }
   }

   /** Pipes input stream to output stream with exception handler.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>.  <br><jv>onException</jv> must not be <jk>null</jk> (invoked on I/O error). */
   public static long pipe(InputStream in, OutputStream out, Consumer<IOException> onException) {
      try {
         try (var in2 = in) {
            return pipe(in, out, -1L);
         }
      } catch (IOException e) {
         onException.accept(e);
         return -1;
      }
   }

   /** Pipes input stream to output stream with max bytes.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(InputStream in, OutputStream out, long maxBytes) throws IOException {
      if (in == null || out == null)
         return 0;
      var buffer = byteBuffer((int)maxBytes);
      int readLen;
      var total = 0l;
      if (maxBytes < 0) {
         while ((readLen = in.read(buffer)) != -1) {
            out.write(buffer, 0, readLen);
            total += readLen;
         }
      } else {
         var remaining = maxBytes;
         while (remaining > 0) {
            readLen = in.read(buffer, 0, buffSize(remaining));
            if (readLen == -1)
               break;
            out.write(buffer, 0, readLen);
            total += readLen;
            remaining -= readLen;
         }
      }
      out.flush();
      return total;
   }

   /** Pipes input stream to writer.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(InputStream in, Writer out) throws IOException {
      if (in == null || out == null)
         return 0;
      return pipe(new InputStreamReader(in, UTF8), out);
   }

   /** Pipes input stream to writer with exception handler.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>.  <br><jv>onException</jv> must not be <jk>null</jk> (invoked on I/O error). */
   public static long pipe(InputStream in, Writer out, Consumer<IOException> onException) {
      try {
         if (in == null || out == null)
            return 0;
         return pipe(new InputStreamReader(in, UTF8), out);
      } catch (IOException e) {
         onException.accept(e);
         return -2;
      }
   }

   /** Pipes reader to file.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(Reader in, File out) throws IOException {
      if (out == null || in == null)
         return 0;
      try (var w = FileWriterBuilder.create(out).buffered().build()) {
         return pipe(in, w);
      }
   }

   /** Pipes reader to output stream.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(Reader in, OutputStream out) throws IOException {
      if (in == null || out == null)
         return 0;
      var total = 0l;
      try (var in2 = in) {
         var osw = new OutputStreamWriter(out, UTF8);
         var i = 0;
         var b = charBuffer(-1);
         while ((i = in.read(b)) > 0) {
            total += i;
            osw.write(b, 0, i);
         }
         osw.flush();
      }
      return total;
   }

   /** Pipes reader to output stream with exception handler.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>.  <br><jv>onException</jv> must not be <jk>null</jk> (invoked on I/O error). */
   public static long pipe(Reader in, OutputStream out, Consumer<IOException> onException) {
      try {
         return pipe(in, out);
      } catch (IOException e) {
         onException.accept(e);
         return -1;
      }
   }

   /** Pipes reader to writer.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>. */
   public static long pipe(Reader in, Writer out) throws IOException {
      if (out == null || in == null)
         return 0;
      var total = 0l;
      try (var in2 = in) {
         var buffer = charBuffer(-1);
         int readLen;
         while ((readLen = in.read(buffer)) != -1) {
            out.write(buffer, 0, readLen);
            total += readLen;
         }
      }
      out.flush();
      return total;
   }

   /** Pipes reader to writer with exception handler.  <br>Returns <c>0</c> if either <jv>in</jv> or <jv>out</jv> is <jk>null</jk>.  <br><jv>onException</jv> must not be <jk>null</jk> (invoked on I/O error). */
   public static long pipe(Reader in, Writer out, Consumer<IOException> onException) {
      try {
         return pipe(in, out);
      } catch (IOException e) {
         onException.accept(e);
         return -1;
      }
   }

   /**
    * Prints all the specified lines to the log with line numbers.
    *
    * @param lines The lines to print.  Must not be <jk>null</jk> (individual <jk>null</jk> entries render as <js>"null"</js>).
    */
   public static final void printLines(String[] lines) {
      RichLogger log = RichLogger.getLogger(IoUtils.class);
      for (var i = 0; i < lines.length; i++)
         log.info(f("%4s:%s", i + 1, lines[i]));
   }

   /**
    * Constructor.
    */
   protected IoUtils() {}
}