<action issue="IO-359" dev="ggregory" type="add" due-to="yukoba">Add IOUtils.skip and skipFully(ReadableByteChannel, long).</action>

garydgregory · garydgregory · commit 106c87c9929f · 2012-11-30T14:18:47.000Z
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@1415648 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -47,6 +47,9 @@ The <action> type attribute can be add,update,fix,remove.
   <body>
     <!-- The release date is the date RC is cut -->
     <release version="2.5" date="201?-??-??" description="New features and bug fixes.">    
+      <action issue="IO-359" dev="ggregory" type="add" due-to="yukoba">
+        Add IOUtils.skip and skipFully(ReadableByteChannel, long).
+      </action>            
       <action issue="IO-358" dev="ggregory" type="add" due-to="yukoba">
         Add IOUtils.read and readFully(ReadableByteChannel, ByteBuffer buffer).
       </action>            
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -2342,6 +2342,37 @@ public static long skip(InputStream input, long toSkip) throws IOException {
         return toSkip - remain;
     }
 
+    /**
+     * Skip bytes from a ReadableByteChannel.
+     * This implementation guarantees that it will read as many bytes
+     * as possible before giving up.
+     *
+     * @param input ReadableByteChannel to skip
+     * @param toSkip number of bytes to skip.
+     * @return number of bytes actually skipped.
+     *
+     * @throws IOException if there is a problem reading the ReadableByteChannel
+     * @throws IllegalArgumentException if toSkip is negative
+     * @since 2.5
+     */
+    public static long skip(ReadableByteChannel input, long toSkip) throws IOException {
+        if (toSkip < 0) {
+            throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
+        }
+        ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, SKIP_BUFFER_SIZE));
+        long remain = toSkip;
+        while (remain > 0) {
+            skipByteBuffer.position(0);
+            skipByteBuffer.limit((int) Math.min(remain, SKIP_BUFFER_SIZE));
+            int n = input.read(skipByteBuffer);
+            if (n == EOF) {
+                break;
+            }
+            remain -= n;
+        }
+        return toSkip - remain;
+    }
+
     /**
      * Skip characters from an input character stream.
      * This implementation guarantees that it will read as many characters
@@ -2419,6 +2450,27 @@ public static void skipFully(InputStream input, long toSkip) throws IOException
         }
     }
 
+    /**
+     * Skip the requested number of bytes or fail if there are not enough left.
+     *
+     * @param input ReadableByteChannel to skip
+     * @param toSkip the number of bytes to skip
+     *
+     * @throws IOException if there is a problem reading the ReadableByteChannel
+     * @throws IllegalArgumentException if toSkip is negative
+     * @throws EOFException if the number of bytes skipped was incorrect
+     * @since 2.5
+     */
+    public static void skipFully(ReadableByteChannel input, long toSkip) throws IOException {
+        if (toSkip < 0) {
+            throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
+        }
+        long skipped = skip(input, toSkip);
+        if (skipped != toSkip) {
+            throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
+        }
+    }
+
     /**
      * Skip the requested number of characters or fail if there are not enough left.
      * <p>
diff --git a/src/test/java/org/apache/commons/io/IOUtilsTestCase.java b/src/test/java/org/apache/commons/io/IOUtilsTestCase.java
@@ -739,6 +739,19 @@ public void testSkip_InputStream() throws Exception {
         }
     }
 
+    public void testSkip_ReadableByteChannel() throws Exception {
+        FileInputStream fileInputStream = new FileInputStream(m_testFile);
+        FileChannel fileChannel = fileInputStream.getChannel();
+        try {
+            assertEquals(FILE_SIZE - 10, IOUtils.skip(fileChannel, FILE_SIZE - 10));
+            assertEquals(10, IOUtils.skip(fileChannel, 20));
+            assertEquals(0, IOUtils.skip(fileChannel, 10));
+        } finally {
+            IOUtils.closeQuietly(fileChannel);
+            IOUtils.closeQuietly(fileInputStream);
+        }
+    }
+
     public void testSkipFully_InputStream() throws Exception {
         final int size = 1027;
 
@@ -761,6 +774,30 @@ public void testSkipFully_InputStream() throws Exception {
 
     }
 
+    public void testSkipFully_ReadableByteChannel() throws Exception {
+        FileInputStream fileInputStream = new FileInputStream(m_testFile);
+        FileChannel fileChannel = fileInputStream.getChannel();
+        try {
+            try {
+                IOUtils.skipFully(fileChannel, -1);
+                fail("Should have failed with IllegalArgumentException");
+            } catch (IllegalArgumentException expected) {
+                // expected
+            }
+            IOUtils.skipFully(fileChannel, 0);
+            IOUtils.skipFully(fileChannel, FILE_SIZE - 1);
+            try {
+                IOUtils.skipFully(fileChannel, 2);
+                fail("Should have failed with IOException");
+            } catch (IOException expected) {
+                // expected
+            }
+        } finally {
+            IOUtils.closeQuietly(fileChannel);
+            IOUtils.closeQuietly(fileInputStream);
+        }
+    }
+
     public void testSkipFully_Reader() throws Exception {
         final int size = 1027;
 
