This
class
implements a communication channel for efficiently reading and and
writing files. It implements the standard read( )
and write( ) methods of the
ReadableByteChannel,
WritableByteChannel,
GatheringByteChannel and
ScatteringByteChannel methods. In addition,
however, FileChannel provides methods for:
random-access to the file, efficient transfer of bytes between the
file and another channel, file locking, memory mapping, querying and
setting the file size and forcing buffered updates to be written to
disk. These important features are described in further detail below.
Note that since file operations do not typically block for extended
periods the way network operations can,
FileChannel does not subclass
SelectableChannel (it is the only channel class
that does not) and cannot be used with Selector
objects.
FileChannel has no public constructor and no
static factory methods. To obtain a FileChannel,
first create a FileInputStream,
FileOutputStream, or
RandomAccessFile object (see the
java.io package) and then call the
getChannel( ) method of that object. If you use a
FileInputStream, the resulting channel will allow
reading but not writing, and if you use a
FileOutputStream, the channel will allow writing
but not reading. If you obtain a FileChannel from
a RandomAccessFile, then the channel will allow
reading, or both reading and writing, depending on the
mode argument to the
RandomAccessFile constructor.
A FileChannel has a position
or file pointer that specifies the current point in the file. You can
set or query the file position with two methods, both of which share
the name position( ). The
position of a FileChannel and of the stream or
RandomAccessFile from which it is derived are
always the same: changing the position of the channel changes the
position of the stream, and vice versa. The initial position of a
FileChannel is the position of the stream or
RandomAccessFile when the getChannel(
) method was called. If you create a
FileChannel from a
FileOutputStream that was opened in append mode,
then any output to the channel always occurs at the end of the file,
and sets the file position to the end end of the file.
Once you have a FileChannel object, you can use
the standard read( )
and write( ) methods
defined by the various channel interfaces. In addition to updating
the buffer position as they read and write bytes, these methods also
update the file position to or from which those bytes are written or
read. These standard read( ) methods return the
number of bytes actually read, and return -1 if there are no bytes
left in the file to read. The write( ) methods
enlarge the file if they write past the current end-of-file.
FileChannel also defines position-independent
read( ) and write( ) methods
that take a file position as an explicit argument: they read or write
starting at that position of the file, and although they update the
position of the ByteBuffer, they do not update the
file position of the FileChannel. If the specified
position is past the end-of-file, the read( ) method does not read
any bytes and returns -1, and the write( ) method
enlarges the file, leaving any bytes between the old end-of-file and
the specified position undefined.
It is common to read bytes from a FileChannel and
then immediately write them out to some other channel (such as a
SocketChannel: think of a web server, for
example), or to read bytes from a channel and immediately write them
to a FileChannel (consider an FTP client).
FileChannel provides two methods,
transferTo( ) and TRansferFrom(
) that do this very efficiently, without the need for a
temporary ByteBuffer. TRansferTo(
) reads up to the specified number of bytes starting at the
specified location from this FileChannel and
writes them to the specified channel. It does not alter the file
position of the FileChannel, and it returns the
number of bytes actually transferred. transferFrom(
) does the reverse: it reads up to the specified number of
available bytes from the specified channel, and writes them to this
FileChannel at the specified location, without
altering the file position of this channel, and returns the actual
number of bytes transferred. For both methods, if the destination or
source channel is a FileChannel itself, then the
file position of that channel is updated.
The size( )
method returns the size (in bytes) of the underlying file.
truncate( ) reduces the file size to the
specified value, discarding any file content that exceeds that size.
If the specified size is greater than or equal to the current file
size, the file is unchanged. If the file position is greater than the
new size of the file, it the position is changed to the new size.
Use the force( ) method to force any buffered
modifications to the file to be written to the underlying storage
device. If the file resides on a local device, (as opposed to a
network filesystem, for example) then force( )
guarantees that any changes to the file made since the channel was
opened or since a previous call to force( ) will
have been written to the device. The argument to this method is a
hint as to whether file meta-data (such as last modification time) is
to be forced out in addition to file content. If this argument is
true, the system will force content and meta-data.
If false, the system may omit updates to
meta-data. Note that force( ) is only required to
output change made directly through the
FileChannel. File updates made through a
MappedByteBuffer returned by the map(
) method (described below)y should
be forced out with the force( ) method of
MappedByteBuffer.
FileChannel defines two blocking lock(
) and two nonblocking
tryLock( )
methods for locking a file or a region
of a file against concurrent access by another program. (These
methods are not suitable for preventing concurrent access to a file
by two threads within the same Java virtual machine.) The no-argument
versions of these methods attempt to acquire an exclusive lock on the
entire file. The three-argument versions of the methods attempt to
lock a specified region of the file, and may acquire
shared locks in
addition to exclusive locks. (A shared lock prevents
any other process from acquiring an exclusive lock, but does not
prevent other shared locks: typically, you acquire a shared lock when
reading a file that should not be concurrently updated, and acquire
an exclusive lock before writing file content to ensure that no one
else is trying to read it at the same time.) The tryLock(
) methods return a FileLock object, or
null if there was already a conflicting lock on
the file. The lock( ) methods block if there is
already a conflicting lock and never return null.
See FileLock for more information about locks. The
FileChannel file locking mechanism uses whatever
locking capability is provided by the underlying platform. Some
operating systems enforce file locking: if one process holds a lock,
other processes are prevented by the operating system from accessing
the file. Other operating systems merely prevent other processes from
acquiring a conflicting lock: in this case, successful file locking
requires the cooperation of all processes. Some operating systems do
not support shared locks: on these systems an exclusive lock is
returned even when a shared lock is requested.
The map( ) method returns a
MappedByteBuffer that represents the specified region of
the file. File contents can be read directly from the buffer, and (if
the mapping is done in read/write mode) bytes placed in the buffer
will be written to the file. The mapping represented by a
MappedByteBuffer remains valid until the buffer is
garbage collected; the buffer continues to function even if the
FileChannel from which it was created is closed.
File mappings can be done in three different modes which specify
whether bytes can be written into the buffer and what happens when
this is done. See FileChannel.MapMode for a
description of the three modes.
The map( ) method relies on the memory-mapping
facilities provided by the underlying operating system. This means
that a number of details may vary from implementation to
implementation. In particular, it is not specified whether changes to
the underlying file made after the call to map( )
are visible through the MappedByteBuffer. Using a
mapped file is typically more efficient that an unmapped file only
when the file is a large one.
public abstract class FileChannel extends java.nio.channels.spi.
AbstractInterruptibleChannel
implements ByteChannel, GatheringByteChannel, ScatteringByteChannel {
// Protected Constructors
protected FileChannel( );
// Nested Types
public static class MapMode;
// Public Instance Methods
public abstract void force(boolean metaData) throws java.io.IOException;
public final FileLock lock( ) throws java.io.IOException;
public abstract FileLock lock(long position, long size, boolean shared)
throws java.io.IOException;
public abstract java.nio.MappedByteBuffer map(FileChannel.MapMode mode,
long position, long size) throws java.io.IOException;
public abstract long position( ) throws java.io.IOException;
public abstract FileChannel position(long newPosition)
throws java.io.IOException;
public abstract int read(java.nio.ByteBuffer dst, long position)
throws java.io.IOException;
public abstract long size( ) throws java.io.IOException;
public abstract long transferFrom(ReadableByteChannel src, long position,
long count) throws java.io.IOException;
public abstract long transferTo(long position, long count,
WritableByteChannel target) throws java.io.IOException;
public abstract FileChannel truncate(long size) throws java.io.IOException;
public final FileLock tryLock( ) throws java.io.IOException;
public abstract FileLock tryLock(long position, long size, boolean shared)
throws java.io.IOException;
public abstract int write(java.nio.ByteBuffer src, long position)
throws java.io.IOException;
// Methods Implementing GatheringByteChannel
public final long write(java.nio.ByteBuffer[ ] srcs)
throws java.io.IOException;
public abstract long write(java.nio.ByteBuffer[ ] srcs, int offset,
int length) throws java.io.IOException;
// Methods Implementing ReadableByteChannel
public abstract int read(java.nio.ByteBuffer dst)
throws java.io.IOException;
// Methods Implementing ScatteringByteChannel
public final long read(java.nio.ByteBuffer[ ] dsts)
throws java.io.IOException;
public abstract long read(java.nio.ByteBuffer[ ] dsts, int offset,
int length) throws java.io.IOException;
// Methods Implementing WritableByteChannel
public abstract int write(java.nio.ByteBuffer src)
throws java.io.IOException;
}
