Package io.netty.channel

Interface FileRegion

  • All Superinterfaces:
    io.netty.util.ReferenceCounted
    All Known Implementing Classes:
    DefaultFileRegion
    public interface FileRegion
extends io.netty.util.ReferenceCounted
    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

    • Method Detail

      • position

        long position()
        Returns the offset in the file where the transfer began.

      • transfered

        @Deprecated
long transfered()
        Deprecated.
        Use transferred() instead.
        Returns the bytes which was transferred already.

      • transferred

        long transferred()
        Returns the bytes which was transferred already.

        Note: some asynchronous transports (such as the io_uring transport when falling back to a chunked send for non-DefaultFileRegion implementations) advance this counter when bytes have been queued for submission, which may be before they reach the peer. If the channel is closed or the write fails after queuing, the reported value may overstate the number of bytes actually delivered.

      • count

        long count()
        Returns the number of bytes to transfer.

      • transferTo

        long transferTo​(WritableByteChannel target,
                long position)
         throws 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 position()th byte and count() - 1 will make the last byte of the region transferred.
        Throws:
        IOException

      • retain

        FileRegion retain()
        Specified by:
        retain in interface io.netty.util.ReferenceCounted

      • retain

        FileRegion retain​(int increment)
        Specified by:
        retain in interface io.netty.util.ReferenceCounted

      • touch

        FileRegion touch()
        Specified by:
        touch in interface io.netty.util.ReferenceCounted

      • touch

        FileRegion touch​(Object hint)
        Specified by:
        touch in interface io.netty.util.ReferenceCounted