Apply nanoseconds precision for timeout duration. (#453)

Also improve javadocs

Author: maxxedev

src/main/java/org/apache/commons/io/input/QueueInputStream.java

@@ -103,8 +103,8 @@ public Builder setBlockingQueue(final BlockingQueue<Integer> blockingQueue) {
          * @return this.
          */
         public Builder setTimeout(final Duration timeout) {
-            if (timeout != null && timeout.toMillis() < 0) {
-                throw new IllegalArgumentException("waitTime must not be negative");
+            if (timeout != null && timeout.toNanos() < 0) {
+                throw new IllegalArgumentException("timeout must not be negative");
             }
             this.timeout = timeout != null ? timeout : Duration.ZERO;
             return this;
@@ -124,17 +124,17 @@ public static Builder builder() {
 
     private final BlockingQueue<Integer> blockingQueue;
 
-    private final long timeoutMillis;
+    private final long timeoutNanos;
 
     /**
-     * Constructs a new instance with no limit to its internal buffer size and zero wait time.
+     * Constructs a new instance with no limit to its internal queue size and zero timeout.
      */
     public QueueInputStream() {
         this(new LinkedBlockingQueue<>());
     }
 
     /**
-     * Constructs a new instance with given buffer and zero wait time.
+     * Constructs a new instance with given queue and zero timeout.
      *
      * @param blockingQueue backing queue for the stream.
      */
@@ -143,14 +143,14 @@ public QueueInputStream(final BlockingQueue<Integer> blockingQueue) {
     }
 
     /**
-     * Constructs a new instance with given buffer and wait time.
+     * Constructs a new instance with given queue and timeout.
      *
      * @param blockingQueue backing queue for the stream.
      * @param timeout       how long to wait before giving up when polling the queue.
      */
     private QueueInputStream(final BlockingQueue<Integer> blockingQueue, final Duration timeout) {
         this.blockingQueue = Objects.requireNonNull(blockingQueue, "blockingQueue");
-        this.timeoutMillis = Objects.requireNonNull(timeout, "timeout").toMillis();
+        this.timeoutNanos = Objects.requireNonNull(timeout, "timeout").toNanos();
     }
 
     /**
@@ -168,7 +168,7 @@ BlockingQueue<Integer> getBlockingQueue() {
      * @return the timeout duration.
      */
     Duration getTimeout() {
-        return Duration.ofMillis(timeoutMillis);
+        return Duration.ofNanos(timeoutNanos);
     }
 
     /**
@@ -183,13 +183,13 @@ public QueueOutputStream newQueueOutputStream() {
     /**
      * Reads and returns a single byte.
      *
-     * @return either the byte read or {@code -1} if the wait time elapses before a queue element is available.
+     * @return the byte read, or {@code -1} if a timeout occurs before a queue element is available.
      * @throws IllegalStateException if thread is interrupted while waiting.
      */
     @Override
     public int read() {
         try {
-            final Integer value = blockingQueue.poll(timeoutMillis, TimeUnit.MILLISECONDS);
+            final Integer value = blockingQueue.poll(timeoutNanos, TimeUnit.NANOSECONDS);
             return value == null ? EOF : 0xFF & value;
         } catch (final InterruptedException e) {
             Thread.currentThread().interrupt();

src/test/java/org/apache/commons/io/input/QueueInputStreamTest.java

@@ -32,7 +32,7 @@
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.LinkedBlockingQueue;
 import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicReference;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.stream.Stream;
 
 import org.apache.commons.io.IOUtils;
@@ -158,7 +158,7 @@ public void testTimeoutInterrupted() throws Exception {
                 final QueueOutputStream outputStream = inputStream.newQueueOutputStream()) {
 
             // read in a background thread
-            final AtomicReference<Boolean> result = new AtomicReference<>();
+            final AtomicBoolean result = new AtomicBoolean();
             final CountDownLatch latch = new CountDownLatch(1);
             final Thread thread = new Thread(() -> {
                 // when thread is interrupted, verify ...
@@ -205,8 +205,10 @@ public void testUnbufferedReadWrite(final String inputData) throws IOException {
     @ParameterizedTest(name = "inputData={0}")
     @MethodSource("inputData")
     public void testUnbufferedReadWriteWithTimeout(final String inputData) throws IOException {
-        try (QueueInputStream inputStream = QueueInputStream.builder().setTimeout(Duration.ofMinutes(2)).get();
+        final Duration timeout = Duration.ofMinutes(2);
+        try (QueueInputStream inputStream = QueueInputStream.builder().setTimeout(timeout).get();
                 final QueueOutputStream outputStream = inputStream.newQueueOutputStream()) {
+            assertEquals(timeout, inputStream.getTimeout());
             writeUnbuffered(outputStream, inputData);
             final String actualData = assertTimeout(Duration.ofSeconds(1), () -> readUnbuffered(inputStream, inputData.length()));
             assertEquals(inputData, actualData);