Interface FileRegion

  • All Superinterfaces:
    ExternalResourceReleasable
    All Known Implementing Classes:
    DefaultFileRegion

    public interface FileRegion
    extends ExternalResourceReleasable
    A region of a file that is sent via a Channel which supports zero-copy file transfer.

    Upgrade your JDK / JRE

    FileChannel.transferTo(long, long, WritableByteChannel) has at least four known bugs in the old versions of Sun JDK and perhaps its derived ones. Please upgrade your JDK to 1.6.0_18 or later version if you are going to use zero-copy file transfer.
    • 5103988 - FileChannel.transferTo() should return -1 for EAGAIN instead throws IOException
    • 6253145 - FileChannel.transferTo() on Linux fails when going beyond 2GB boundary
    • 6427312 - FileChannel.transferTo() throws IOException "system call interrupted"
    • 6470086 - FileChannel.transferTo(2147483647, 1, channel) causes "Value too large" exception

    Check your operating system and JDK / JRE

    If your operating system (or JDK / JRE) does not support zero-copy file transfer, sending a file with FileRegion might fail or yield worse performance. For example, sending a large file doesn't work well in Windows.

    Not all transports support it

    Currently, the NIO transport is the only transport that supports FileRegion. Attempting to write a FileRegion to non-NIO Channel will trigger a ClassCastException or a similar exception.
    • Method Detail

      • getPosition

        long getPosition()
        Returns the offset in the file where the transfer began.
      • getCount

        long getCount()
        Returns the number of bytes to transfer.
      • transferTo

        long transferTo​(java.nio.channels.WritableByteChannel target,
                        long position)
                 throws java.io.IOException
        Transfers the content of this file region to the specified channel.
        Parameters:
        target - the destination of the transfer
        position - the relative offset of the file where the transfer begins from. For example, 0 will make the transfer start from getPosition()th byte and getCount() - 1 will make the last byte of the region transferred.
        Throws:
        java.io.IOException