* A {@code FileChannel} defines the methods for reading, writing, memory * mapping, and manipulating the logical state of a platform file. This type * does not have a method for opening files, since this behavior has been * delegated to the {@link java.io.FileInputStream}, * {@link java.io.FileOutputStream} and {@link java.io.RandomAccessFile} types. *
* FileChannels created from a {@code FileInputStream} or a * {@code RandomAccessFile} created in mode "r", are read-only. FileChannels * created from a {@code FileOutputStream} are write-only. FileChannels created * from a {@code RandomAccessFile} created in mode "rw" are read/write. * FileChannels created from a {@code RandomAccessFile} that was opened in * append-mode will also be in append-mode -- meaning that each write will be * proceeded by a seek to the end of file. *
* FileChannels have a virtual pointer into the file which is referred to as a * file position. The position can be manipulated by moving it * within the file, and the current position can be queried. *
* FileChannels also have an associated size. The size of the file * is the number of bytes that it currently contains. The size can be * manipulated by adding more bytes to the end of the file (which increases the * size) or truncating the file (which decreases the size). The current size can * also be queried. *
* FileChannels have operations beyond the simple read, write, and close. They * can also: *
* FileChannels are thread-safe. Only one operation involving manipulation of * the file position may be executed at the same time. Subsequent calls to such * operations will block, and one of those blocked will be freed to continue * when the first operation has completed. There is no ordered queue or fairness * applied to the blocked threads. *
* It is undefined whether operations that do not manipulate the file position * will also block when there are any other operations in-flight. *
* The logical view of the underlying file is consistent across all FileChannels * and I/O streams opened on the same file by the same VM. * Therefore, modifications performed via a channel will be visible to the * stream and vice versa; this includes modifications to the file position, * content, size, etc. */ public abstract class FileChannel extends AbstractInterruptibleChannel implements GatheringByteChannel, ScatteringByteChannel, ByteChannel { /** * {@code MapMode} defines file mapping mode constants. */ public static class MapMode { /** * Private mapping mode (equivalent to copy on write). */ public static final MapMode PRIVATE = new MapMode("PRIVATE"); /** * Read-only mapping mode. */ public static final MapMode READ_ONLY = new MapMode("READ_ONLY"); /** * Read-write mapping mode. */ public static final MapMode READ_WRITE = new MapMode("READ_WRITE"); // The string used to display the mapping mode. private final String displayName; /* * Private constructor prevents others creating new modes. */ private MapMode(String displayName) { this.displayName = displayName; } /** * Returns a string version of the mapping mode. * * @return this map mode as string. */ @Override public String toString() { return displayName; } } /** * Protected default constructor. */ protected FileChannel() { } /** * Requests that all updates to this channel are committed to the storage * device. *
* When this method returns, all modifications made to the platform file * underlying this channel have been committed if the file resides on a * local storage device. If the file is not hosted locally, for example on a * networked file system, then applications cannot be certain that the * modifications have been committed. *
* There are no assurances given that changes made to the file using methods * defined elsewhere will be committed. For example, changes made via a * mapped byte buffer may not be committed. *
* The metadata parameter indicates whether the update should
* include the file's metadata such as last modification time, last access
* time, etc. Note that passing true may invoke an underlying
* write to the operating system (if the platform is maintaining metadata
* such as last access time), even if the channel is opened read-only.
*
* @param metadata
* {@code true} if the file metadata should be flushed in
* addition to the file content, {@code false} otherwise.
* @throws ClosedChannelException
* if this channel is already closed.
* @throws IOException
* if another I/O error occurs.
*/
public abstract void force(boolean metadata) throws IOException;
/**
* Obtains an exclusive lock on this file.
*
* This is a convenience method for acquiring a maximum length lock on a * file. It is equivalent to: * {@code fileChannel.lock(0L, Long.MAX_VALUE, false);} * * @return the lock object representing the locked file area. * @throws ClosedChannelException * the file channel is closed. * @throws NonWritableChannelException * this channel was not opened for writing. * @throws OverlappingFileLockException * either a lock is already held that overlaps this lock * request, or another thread is waiting to acquire a lock that * will overlap with this request. * @throws FileLockInterruptionException * the calling thread was interrupted while waiting to acquire * the lock. * @throws AsynchronousCloseException * the channel was closed while the calling thread was waiting * to acquire the lock. * @throws IOException * if another I/O error occurs while obtaining the requested * lock. */ public final FileLock lock() throws IOException { return lock(0L, Long.MAX_VALUE, false); } /** * Obtains a lock on a specified region of the file. *
* This is the blocking version of lock acquisition, see also the
* tryLock() methods.
*
* Attempts to acquire an overlapping lock region will fail. The attempt * will fail if the overlapping lock has already been obtained, or if * another thread is currently waiting to acquire the overlapping lock. *
* If the request is not for an overlapping lock, the thread calling this * method will block until the lock is obtained (likely by no contention or * another process releasing a lock), or until this thread is interrupted or * the channel is closed. *
* If the lock is obtained successfully then the {@link FileLock} object * returned represents the lock for subsequent operations on the locked * region. *
* If the thread is interrupted while waiting for the lock, the thread is * set to the interrupted state and throws a * {@link FileLockInterruptionException}. If this channel is closed while * the thread is waiting to obtain the lock then the thread throws a * {@link AsynchronousCloseException}. *
* There is no requirement for the position and size to be within the * current start and length of the file. *
* Some platforms do not support shared locks, and if a request is made for * a shared lock on such a platform, this method will attempt to acquire an * exclusive lock instead. It is undefined whether the lock obtained is * advisory or mandatory. * * @param position * the starting position for the locked region. * @param size * the length of the locked region in bytes. * @param shared * a flag indicating whether an attempt should be made to acquire * a shared lock. * @return the file lock object. * @throws IllegalArgumentException * if {@code position} or {@code size} is negative. * @throws ClosedChannelException * if this channel is closed. * @throws OverlappingFileLockException * if the requested region overlaps an existing lock or pending * lock request. * @throws NonReadableChannelException * if the channel is not opened in read-mode but shared is true. * @throws NonWritableChannelException * if the channel is not opened in write mode but shared is * false. * @throws AsynchronousCloseException * if this channel is closed by another thread while this method * is executing. * @throws FileLockInterruptionException * if the thread is interrupted while in the state of waiting on * the desired file lock. * @throws IOException * if another I/O error occurs. */ public abstract FileLock lock(long position, long size, boolean shared) throws IOException; /** * Maps the file into memory. There can be three modes: read-only, * read/write and private. After mapping, changes made to memory or the file * channel do not affect the other storage place. *
* Note: mapping a file into memory is usually expensive. * * @param mode * one of the three mapping modes. * @param position * the starting position of the file. * @param size * the size of the region to map into memory. * @return the mapped byte buffer. * @throws NonReadableChannelException * if the FileChannel is not opened for reading but the given * mode is "READ_ONLY". * @throws NonWritableChannelException * if the FileChannel is not opened for writing but the given * mode is not "READ_ONLY". * @throws IllegalArgumentException * if the given parameters of position and size are not correct. * Both must be non negative. {@code size} also must not be * bigger than max integer. * @throws IOException * if any I/O error occurs. */ public abstract MappedByteBuffer map(FileChannel.MapMode mode, long position, long size) throws IOException; /** * Returns the current value of the file position pointer. * * @return the current position as a positive integer number of bytes from * the start of the file. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if another I/O error occurs. */ public abstract long position() throws IOException; /** * Sets the file position pointer to a new value. *
* The argument is the number of bytes counted from the start of the file. * The position cannot be set to a value that is negative. The new position * can be set beyond the current file size. If set beyond the current file * size, attempts to read will return end of file. Write operations will * succeed but they will fill the bytes between the current end of file and * the new position with the required number of (unspecified) byte values. * * @param offset * the new file position, in bytes. * @return the receiver. * @throws IllegalArgumentException * if the new position is negative. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if another I/O error occurs. */ public abstract FileChannel position(long offset) throws IOException; /** * Reads bytes from this file channel into the given buffer. *
* The maximum number of bytes that will be read is the remaining number of * bytes in the buffer when the method is invoked. The bytes will be copied * into the buffer starting at the buffer's current position. *
* The call may block if other threads are also attempting to read from this * channel. *
* Upon completion, the buffer's position is set to the end of the bytes * that have been read. The buffer's limit is not changed. * * @param buffer * the byte buffer to receive the bytes. * @return the number of bytes actually read. * @throws AsynchronousCloseException * if another thread closes the channel during the read. * @throws ClosedByInterruptException * if another thread interrupts the calling thread during the * read. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if another I/O error occurs, details are in the message. * @throws NonReadableChannelException * if the channel has not been opened in a mode that permits * reading. */ public abstract int read(ByteBuffer buffer) throws IOException; /** * Reads bytes from this file channel into the given buffer starting from * the specified file position. *
* The bytes are read starting at the given file position (up to the * remaining number of bytes in the buffer). The number of bytes actually * read is returned. *
* If {@code position} is beyond the current end of file, then no bytes are * read. *
* Note that the file position is unmodified by this method.
*
* @param buffer
* the buffer to receive the bytes.
* @param position
* the (non-negative) position at which to read the bytes.
* @return the number of bytes actually read.
* @throws AsynchronousCloseException
* if this channel is closed by another thread while this method
* is executing.
* @throws ClosedByInterruptException
* if another thread interrupts the calling thread while this
* operation is in progress. The calling thread will have the
* interrupt state set, and the channel will be closed.
* @throws ClosedChannelException
* if this channel is closed.
* @throws IllegalArgumentException
* if position is less than 0.
* @throws IOException
* if another I/O error occurs.
* @throws NonReadableChannelException
* if the channel has not been opened in a mode that permits
* reading.
*/
public abstract int read(ByteBuffer buffer, long position)
throws IOException;
/**
* Reads bytes from this file channel and stores them in the specified array
* of buffers. This method attempts to read as many bytes as can be stored
* in the buffer array from this channel and returns the number of bytes
* actually read. It also increases the file position by the number of bytes
* read.
*
* If a read operation is in progress, subsequent threads will block until * the read is completed and will then contend for the ability to read. *
* Calling this method is equivalent to calling * {@code read(buffers, 0, buffers.length);} * * @param buffers * the array of byte buffers into which the bytes will be copied. * @return the number of bytes actually read. * @throws AsynchronousCloseException * if this channel is closed by another thread during this read * operation. * @throws ClosedByInterruptException * if the thread is interrupted by another thread during this * read operation. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if another I/O error occurs; details are in the message. * @throws NonReadableChannelException * if the channel has not been opened in a mode that permits * reading. */ public final long read(ByteBuffer[] buffers) throws IOException { return read(buffers, 0, buffers.length); } /** * Reads bytes from this file channel into a subset of the given buffers. * This method attempts to read all {@code remaining()} bytes from {@code * length} byte buffers, in order, starting at {@code targets[offset]}. It * increases the file position by the number of bytes actually read. The * number of bytes actually read is returned. *
* If a read operation is in progress, subsequent threads will block until * the read is completed and will then contend for the ability to read. * * @param buffers * the array of byte buffers into which the bytes will be copied. * @param start * the index of the first buffer to store bytes in. * @param number * the maximum number of buffers to store bytes in. * @return the number of bytes actually read. * @throws AsynchronousCloseException * if this channel is closed by another thread during this read * operation. * @throws ClosedByInterruptException * if the thread is interrupted by another thread during this * read operation. * @throws ClosedChannelException * if this channel is closed. * @throws IndexOutOfBoundsException * if {@code start < 0} or {@code number < 0}, or if * {@code start + number} is greater than the size of * {@code buffers}. * @throws IOException * if another I/O error occurs; details are in the message. * @throws NonReadableChannelException * if the channel has not been opened in a mode that permits * reading. */ public abstract long read(ByteBuffer[] buffers, int start, int number) throws IOException; /** * Returns the size of the file underlying this channel in bytes. * * @return the size of the file in bytes. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if an I/O error occurs while getting the size of the file. */ public abstract long size() throws IOException; /** * Reads up to {@code count} bytes from {@code src} and stores them in this * channel's file starting at {@code position}. No bytes are transferred if * {@code position} is larger than the size of this channel's file. Less * than {@code count} bytes are transferred if there are less bytes * remaining in the source channel or if the source channel is non-blocking * and has less than {@code count} bytes immediately available in its output * buffer. *
* Note that this channel's position is not modified. * * @param src * the source channel to read bytes from. * @param position * the non-negative start position. * @param count * the non-negative number of bytes to transfer. * @return the number of bytes that are transferred. * @throws IllegalArgumentException * if the parameters are invalid. * @throws NonReadableChannelException * if the source channel is not readable. * @throws NonWritableChannelException * if this channel is not writable. * @throws ClosedChannelException * if either channel has already been closed. * @throws AsynchronousCloseException * if either channel is closed by other threads during this * operation. * @throws ClosedByInterruptException * if the thread is interrupted during this operation. * @throws IOException * if any I/O error occurs. */ public abstract long transferFrom(ReadableByteChannel src, long position, long count) throws IOException; /** * Reads up to {@code count} bytes from this channel's file starting at * {@code position} and writes them to {@code target}. No bytes are * transferred if {@code position} is larger than the size of this channel's * file. Less than {@code count} bytes are transferred if there less bytes * available from this channel's file or if the target channel is * non-blocking and has less than {@code count} bytes free in its input * buffer. *
* Note that this channel's position is not modified. * * @param position * the non-negative position to begin. * @param count * the non-negative number of bytes to transfer. * @param target * the target channel to write to. * @return the number of bytes that were transferred. * @throws IllegalArgumentException * if the parameters are invalid. * @throws NonReadableChannelException * if this channel is not readable. * @throws NonWritableChannelException * if the target channel is not writable. * @throws ClosedChannelException * if either channel has already been closed. * @throws AsynchronousCloseException * if either channel is closed by other threads during this * operation. * @throws ClosedByInterruptException * if the thread is interrupted during this operation. * @throws IOException * if any I/O error occurs. */ public abstract long transferTo(long position, long count, WritableByteChannel target) throws IOException; /** * Truncates the file underlying this channel to a given size. Any bytes * beyond the given size are removed from the file. If there are no bytes * beyond the given size then the file contents are unmodified. *
* If the file position is currently greater than the given size, then it is * set to the new size. * * @param size * the maximum size of the underlying file. * @throws IllegalArgumentException * if the requested size is negative. * @throws ClosedChannelException * if this channel is closed. * @throws NonWritableChannelException * if the channel cannot be written to. * @throws IOException * if another I/O error occurs. * @return this channel. */ public abstract FileChannel truncate(long size) throws IOException; /** * Attempts to acquire an exclusive lock on this file without blocking. *
* This is a convenience method for attempting to acquire a maximum length * lock on the file. It is equivalent to: * {@code fileChannel.tryLock(0L, Long.MAX_VALUE, false);} *
* The method returns {@code null} if the acquisition would result in an * overlapped lock with another OS process. * * @return the file lock object, or {@code null} if the lock would overlap * with an existing exclusive lock in another OS process. * @throws ClosedChannelException * if the file channel is closed. * @throws OverlappingFileLockException * if a lock already exists that overlaps this lock request or * another thread is waiting to acquire a lock that will overlap * with this request. * @throws IOException * if any I/O error occurs. */ public final FileLock tryLock() throws IOException { return tryLock(0L, Long.MAX_VALUE, false); } /** * Attempts to acquire an exclusive lock on this file without blocking. The * method returns {@code null} if the acquisition would result in an * overlapped lock with another OS process. *
* It is possible to acquire a lock for any region even if it's completely * outside of the file's size. The size of the lock is fixed. If the file * grows outside of the lock that region of the file won't be locked by this * lock. * * @param position * the starting position. * @param size * the size of file to lock. * @param shared * true if the lock is shared. * @return the file lock object, or {@code null} if the lock would overlap * with an existing exclusive lock in another OS process. * @throws IllegalArgumentException * if any parameters are invalid. * @throws ClosedChannelException * if the file channel is closed. * @throws OverlappingFileLockException * if a lock is already held that overlaps this lock request or * another thread is waiting to acquire a lock that will overlap * with this request. * @throws IOException * if any I/O error occurs. */ public abstract FileLock tryLock(long position, long size, boolean shared) throws IOException; /** * Writes bytes from the given byte buffer to this file channel. *
* The bytes are written starting at the current file position, and after * some number of bytes are written (up to the remaining number of bytes in * the buffer) the file position is increased by the number of bytes * actually written. * * @param src * the byte buffer containing the bytes to be written. * @return the number of bytes actually written. * @throws NonWritableChannelException * if the channel was not opened for writing. * @throws ClosedChannelException * if the channel was already closed. * @throws AsynchronousCloseException * if another thread closes the channel during the write. * @throws ClosedByInterruptException * if another thread interrupts the calling thread while this * operation is in progress. The interrupt state of the calling * thread is set and the channel is closed. * @throws IOException * if another I/O error occurs, details are in the message. * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) */ public abstract int write(ByteBuffer src) throws IOException; /** * Writes bytes from the given buffer to this file channel starting at the * given file position. *
* The bytes are written starting at the given file position (up to the * remaining number of bytes in the buffer). The number of bytes actually * written is returned. *
* If the position is beyond the current end of file, then the file is first * extended up to the given position by the required number of unspecified * byte values. *
* Note that the file position is not modified by this method.
*
* @param buffer
* the buffer containing the bytes to be written.
* @param position
* the (non-negative) position at which to write the bytes.
* @return the number of bytes actually written.
* @throws IllegalArgumentException
* if position is less than 0.
* @throws ClosedChannelException
* if this channel is closed.
* @throws NonWritableChannelException
* if the channel was not opened in write-mode.
* @throws AsynchronousCloseException
* if this channel is closed by another thread while this method
* is executing.
* @throws ClosedByInterruptException
* if another thread interrupts the calling thread while this
* operation is in progress. The interrupt state of the calling
* thread is set and the channel is closed.
* @throws IOException
* if another I/O error occurs.
*/
public abstract int write(ByteBuffer buffer, long position)
throws IOException;
/**
* Writes bytes from all the given byte buffers to this file channel.
*
* The bytes are written starting at the current file position, and after * the bytes are written (up to the remaining number of bytes in all the * buffers), the file position is increased by the number of bytes actually * written. *
* Calling this method is equivalent to calling * {@code write(buffers, 0, buffers.length);} * * @param buffers * the buffers containing bytes to write. * @return the number of bytes actually written. * @throws AsynchronousCloseException * if this channel is closed by another thread during this write * operation. * @throws ClosedByInterruptException * if another thread interrupts the calling thread while this * operation is in progress. The interrupt state of the calling * thread is set and the channel is closed. * @throws ClosedChannelException * if this channel is closed. * @throws IOException * if another I/O error occurs; details are in the message. * @throws NonWritableChannelException * if this channel was not opened for writing. */ public final long write(ByteBuffer[] buffers) throws IOException { return write(buffers, 0, buffers.length); } /** * Attempts to write a subset of the given bytes from the buffers to this * file channel. This method attempts to write all {@code remaining()} * bytes from {@code length} byte buffers, in order, starting at {@code * sources[offset]}. The number of bytes actually written is returned. *
* If a write operation is in progress, subsequent threads will block until * the write is completed and then contend for the ability to write. * * @param buffers * the array of byte buffers that is the source for bytes written * to this channel. * @param offset * the index of the first buffer in {@code buffers }to get bytes * from. * @param length * the number of buffers to get bytes from. * @return the number of bytes actually written to this channel. * @throws AsynchronousCloseException * if this channel is closed by another thread during this write * operation. * @throws ClosedByInterruptException * if another thread interrupts the calling thread while this * operation is in progress. The interrupt state of the calling * thread is set and the channel is closed. * @throws ClosedChannelException * if this channel is closed. * @throws IndexOutOfBoundsException * if {@code offset < 0} or {@code length < 0}, or if * {@code offset + length} is greater than the size of * {@code buffers}. * @throws IOException * if another I/O error occurs; details are in the message. * @throws NonWritableChannelException * if this channel was not opened for writing. */ public abstract long write(ByteBuffer[] buffers, int offset, int length) throws IOException; }