Interface FileChannel

All Superinterfaces:
AutoCloseable, ByteChannel, Channel, Closeable, ReadableByteChannel, SeekableByteChannel, WritableByteChannel
public interface FileChannel extends SeekableByteChannel
A seekable byte channel that supports file locking and, on JDK 22 and later, mapping regions of its file into memory.

File system implementations can support locking and memory mapping by returning either a FileChannel or a FileChannel from FileSystem.newByteChannel(Path, Set, FileAttribute[]).

Since:
25.5

  • Method Summary

    Modifier and Type
    Method
    Description
    default FileLock
    lock()
    Acquires an exclusive lock on this channel's file, blocking until the lock is acquired, this channel is closed, or the invoking thread is interrupted.
    default FileLock
    lock(long position, long size, boolean shared)
    Acquires a lock on a region of this channel's file, blocking until the lock is acquired, this channel is closed, or the invoking thread is interrupted.
    default Object
    map(FileChannel.MapMode mode, long offset, long size, Object arena)
    Maps a region of this channel's file into a memory segment associated with the given arena.
    FileChannel
    position(long newPosition)
    FileChannel
    truncate(long size)
    default FileLock
    tryLock()
    Attempts to acquire an exclusive lock on this channel's file without blocking.
    default FileLock
    tryLock(long position, long size, boolean shared)
    Attempts to acquire a lock on a region of this channel's file without blocking.

    Methods inherited from interface Channel

    close, isOpen

    Methods inherited from interface SeekableByteChannel

    position, read, size, write

  • Method Details

    • position

      FileChannel position(long newPosition) throws IOException
      Specified by:
      position in interface SeekableByteChannel
      Throws:
      IOException
      Since:
      25.5

    • truncate

      FileChannel truncate(long size) throws IOException
      Specified by:
      truncate in interface SeekableByteChannel
      Throws:
      IOException
      Since:
      25.5

    • lock

      default FileLock lock() throws IOException
      Acquires an exclusive lock on this channel's file, blocking until the lock is acquired, this channel is closed, or the invoking thread is interrupted. This method is equivalent to invoking lock(0, Long.MAX_VALUE, false).
      Returns:
      a newly acquired exclusive lock
      Throws:
      ClosedChannelException - if this channel is closed
      AsynchronousCloseException - if another thread closes this channel while the invoking thread is blocked
      FileLockInterruptionException - if the invoking thread is interrupted while blocked
      OverlappingFileLockException - if an overlapping lock is already held by this Java virtual machine, or another thread is waiting for an overlapping lock
      NonWritableChannelException - if this channel was not opened for writing
      UnsupportedOperationException - if this channel does not support file locking
      IOException - if another I/O error occurs
      Since:
      25.5

    • lock

      default FileLock lock(long position, long size, boolean shared) throws IOException
      Acquires a lock on a region of this channel's file, blocking until the lock is acquired, this channel is closed, or the invoking thread is interrupted. The region need not be contained within or overlap the current file contents. A requested shared lock may be converted to an exclusive lock when shared locks are not supported by the operating system.
      Parameters:
      position - the position of the first byte in the region; must be non-negative
      size - the size of the region; must be non-negative and position + size must not overflow
      shared - true to request a shared lock, or false to request an exclusive lock
      Returns:
      the newly acquired lock
      Throws:
      IllegalArgumentException - if position or size is negative or their sum overflows
      ClosedChannelException - if this channel is closed
      AsynchronousCloseException - if another thread closes this channel while the invoking thread is blocked
      FileLockInterruptionException - if the invoking thread is interrupted while blocked
      OverlappingFileLockException - if an overlapping lock is already held by this Java virtual machine, or another thread is waiting for an overlapping lock
      NonReadableChannelException - if a shared lock is requested and this channel was not opened for reading
      NonWritableChannelException - if an exclusive lock is requested and this channel was not opened for writing
      UnsupportedOperationException - if this channel does not support file locking
      IOException - if another I/O error occurs
      Since:
      25.5

    • tryLock

      default FileLock tryLock() throws IOException
      Attempts to acquire an exclusive lock on this channel's file without blocking. This method is equivalent to invoking tryLock(0, Long.MAX_VALUE, false).
      Returns:
      a newly acquired exclusive lock, or null if another program holds an overlapping lock
      Throws:
      ClosedChannelException - if this channel is closed
      OverlappingFileLockException - if an overlapping lock is already held by this Java virtual machine, or another thread is waiting for an overlapping lock
      NonWritableChannelException - if this channel was not opened for writing
      UnsupportedOperationException - if this channel does not support file locking
      IOException - if another I/O error occurs
      Since:
      25.5

    • tryLock

      default FileLock tryLock(long position, long size, boolean shared) throws IOException
      Attempts to acquire a lock on a region of this channel's file without blocking. The region need not be contained within or overlap the current file contents. A requested shared lock may be converted to an exclusive lock when shared locks are not supported by the operating system.
      Parameters:
      position - the position of the first byte in the region; must be non-negative
      size - the size of the region; must be non-negative and position + size must not overflow
      shared - true to request a shared lock, or false to request an exclusive lock
      Returns:
      the newly acquired lock, or null if another program holds an overlapping lock
      Throws:
      IllegalArgumentException - if position or size is negative or their sum overflows
      ClosedChannelException - if this channel is closed
      OverlappingFileLockException - if an overlapping lock is already held by this Java virtual machine, or another thread is waiting for an overlapping lock
      NonReadableChannelException - if a shared lock is requested and this channel was not opened for reading
      NonWritableChannelException - if an exclusive lock is requested and this channel was not opened for writing
      UnsupportedOperationException - if this channel does not support file locking
      IOException - if another I/O error occurs
      Since:
      25.5

    • map

      default Object map(FileChannel.MapMode mode, long offset, long size, Object arena) throws IOException
      Maps a region of this channel's file into a memory segment associated with the given arena.

      This channel must have been opened for reading for a read-only mapping and for both reading and writing for a read/write or private mapping. Closing this channel does not invalidate the returned segment. Closing arena invalidates the segment and permits the mapped region to be unmapped.

      The arena parameter and return type are intentionally erased to Object to avoid a static dependency on the Foreign Function and Memory API, which is not available on all JDK versions supported by this API. The arena argument must be a java.lang.foreign.Arena, and the returned object is a java.lang.foreign.MemorySegment. When JDK 22 or later becomes the minimum supported version, this method is expected to be deprecated and replaced by a strongly typed variant.

      Parameters:
      mode - the mode in which the file region is mapped
      offset - the offset within the file at which the mapped region starts; must be non-negative
      size - the size of the mapped region, in bytes; must be non-negative
      arena - the java.lang.foreign.Arena associated with the returned segment
      Returns:
      a java.lang.foreign.MemorySegment whose lifetime is controlled by arena
      Throws:
      IOException - if an I/O error occurs
      NonReadableChannelException - if mode requires read access and this channel was not opened for reading
      NonWritableChannelException - if mode requires write access and this channel was not opened for writing
      UnsupportedOperationException - if this channel does not support memory mapping or the requested mode
      IllegalArgumentException - if offset or size is negative or their sum overflows the range of long
      IllegalStateException - if arena has already been closed
      ClassCastException - if arena is not a java.lang.foreign.Arena
      RuntimeException - if arena is confined and this method is called from a thread other than the arena's owner thread; on JDK 22 and later, the concrete exception is java.lang.WrongThreadException
      NullPointerException - if mode or arena is null
      SecurityException - if the FileSystem denied the operation
      Since:
      25.5