Interface FileRegion

All Superinterfaces:
ReferenceCounted
All Known Implementing Classes:
DefaultFileRegion

public interface FileRegion extends 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 Summary

    Modifier and Type
    Method
    Description
    long
    Returns the number of bytes to transfer.
    long
    Returns the offset in the file where the transfer began.
    Increases the reference count by 1.
    retain(int increment)
    Increases the reference count by the specified increment.
    Records the current access location of this object for debugging purposes.
    touch(Object hint)
    Records the current access location of this object with an additional arbitrary information for debugging purposes.
    long
    Deprecated.
    Use transferred() instead.
    long
    Returns the bytes which was transferred already.
    long
    transferTo(WritableByteChannel target, long position)
    Transfers the content of this file region to the specified channel.

    Methods inherited from interface io.netty.util.ReferenceCounted

    refCnt, release, release
  • Method Details

    • 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.
    • 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()
      Description copied from interface: ReferenceCounted
      Increases the reference count by 1.
      Specified by:
      retain in interface ReferenceCounted
    • retain

      FileRegion retain(int increment)
      Description copied from interface: ReferenceCounted
      Increases the reference count by the specified increment.
      Specified by:
      retain in interface ReferenceCounted
    • touch

      FileRegion touch()
      Description copied from interface: ReferenceCounted
      Records the current access location of this object for debugging purposes. If this object is determined to be leaked, the information recorded by this operation will be provided to you via ResourceLeakDetector. This method is a shortcut to touch(null).
      Specified by:
      touch in interface ReferenceCounted
    • touch

      FileRegion touch(Object hint)
      Description copied from interface: ReferenceCounted
      Records the current access location of this object with an additional arbitrary information for debugging purposes. If this object is determined to be leaked, the information recorded by this operation will be provided to you via ResourceLeakDetector.
      Specified by:
      touch in interface ReferenceCounted