Java Doc for FileChannel.java in  » Apache-Harmony-Java-SE » java-package » java » nio » channels » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A 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 behaviour has been delegated to the FileInputStream, FileOutputStream, and RandomAccessFile types.

FileChannels created from a FileInputStream, or a RandomAccessFile created in mode "r", are read-only. FileChannels created from a FileOutputStream are write-only. FileChannels created from a RandomAccessFile created in mode "rw" are read/write. FileChannels created from a 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. Some platforms will seek and write atomically, others will not.

FileChannels has a virtual pointer into the file which is referred to as a file position. The position can be manipulated by repositioning it within the file, and its 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:

• request that cached data be forced onto the disk
• lock ranges of bytes associated with the file
• transfer data directly to another channel in a manner that has the potential to be optimized by the platform
• memory-mapping files into NIO buffers to provide efficient manipulation of file data
• read and write to the file at absolute byte offsets in a fashion that does not modify the current position

FileChannels are thread-safe. Only one operation involving manipulation of the file position may be in-flight at once. 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 IO streams opened on the same file by the same JVM process. Therefore modifications performed via a channel will be visible to the stream, and vice versa; including modifications to the file position, content, size, etc.

When this method returns all modifications made to the platform file underlying this channel will be committed to a local storage device.

This is a convenience method for acquiring a maximum length lock on a file.

This is the blocking version of lock acquisition, see also the tryLock() methods.

Attempts to acquire an overlapping lock region will fail.

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 bytes are read starting at the given file position (up to the remaining number of bytes in the buffer).

Any bytes beyond the given size are removed from the file.

This is a convenience method for attempting to acquire a maximum length lock on the file.

The bytes are written starting at the given file position (up to the remaining number of bytes in the buffer).

When this method returns all modifications made to the platform file underlying this channel will be committed to a local storage device. If the file is not hosted locally, such as 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 indicated 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.
Parameters:
  metadata - true if the file metadata should be flushed in addition to thefile content, and false otherwise.
throws:
  ClosedChannelException - if the channel is already closed.
throws:
  IOException - some other problem occurred.

This is a convenience method for acquiring a maximum length lock on a file. It is equivalent to:

 fileChannel.lock(0L, Long.MAX_VALUE, false)
 

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 this thread being interrupted or the channel closed.

If the lock is obtained successfully then the 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 FileLockInterruptionException. If the channel is closed while the thread is waiting to obtain the lock then the thread throws a 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.

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, and writes will succeed, but fill-in the bytes between the current end of file and the position with the required number of (unspecified) byte values.
Parameters:
  offset - the new file position, in bytes. the receiver.
throws:
  IllegalArgumentException - if the new position is negative.
throws:
  ClosedChannelException - if the channel is already closed.
throws:
  IOException - if some other IO problem occurs.

The bytes are read starting at the current file position, and after some number of bytes are read (up to the remaining number of bytes in the buffer) the file position is increased by the number of bytes actually read.
See Also:   java.nio.channels.ReadableByteChannel.read(java.nio.ByteBuffer)

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 the position is beyond the current end of file, then no bytes are read.

Note that file position is unmodified by this method.

The bytes are read starting at the current file position, and after some number of bytes are read (up to the remaining number of bytes in all the buffers) the file position is increased by the number of bytes actually read.

This method behaves exactly like:

 read(buffers, 0, buffers.length);
 

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 be the given size.

This is a convenience method for attempting to acquire a maximum length lock on the file. It is equivalent to:

 fileChannel.tryLock(0L, Long.MAX_VALUE, false)
 

The method returns null if the acquisition would result in an overlapped lock with another OS process.

The method returns null if the acquisition would result in an overlapped lock with another OS process.

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.
See Also:   java.nio.channels.WritableByteChannel.write(java.nio.ByteBuffer)
Parameters:
  src - the source buffer to write

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 file position is unmodified by this method.

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 all the buffers) the file position is increased by the number of bytes actually written.

This method behaves exactly like:

 write(buffers, 0, buffers.length);