org.jboss.netty.channel

## 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 Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getCount()` Returns the number of bytes to transfer.
    `long` | `getPosition()` Returns the offset in the file where the transfer began.
    `long` | `transferTo(WritableByteChannel target, long position)` Transfers the content of this file region to the specified channel.

    - ### Methods inherited from interface org.jboss.netty.util.ExternalResourceReleasable

      `releaseExternalResources`

- - ### 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(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 `getPosition()`th byte and ``getCount()` - 1` will make the last byte of the region transferred.
      Throws:
        `IOException`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.