java.nio.channels.FileChannel源码解读

版本:JDK7

package java.nio.channels;

import java.io.*;
import java.nio.ByteBuffer;
import java.nio.MappedByteBuffer;
import java.nio.channels.spi.AbstractInterruptibleChannel;
import java.nio.file.*;
import java.nio.file.attribute.FileAttribute;
import java.nio.file.spi.*;
import java.util.Set;
import java.util.HashSet;
import java.util.Collections;

public abstract class FileChannel extends AbstractInterruptibleChannel
    implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel {

    protected FileChannel() { }

    /**
     * Opens or creates a file, returning a file channel to access the file.
     *
     * 

The {@code options} parameter determines how the file is opened. * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE * WRITE} options determine if the file should be opened for reading and/or * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND} * option) is contained in the array then the file is opened for reading. * By default reading or writing commences at the beginning of the file. * @since 1.7 */ public static FileChannel open(Path path, Set options, FileAttribute... attrs) throws IOException { FileSystemProvider provider = path.getFileSystem().provider(); return provider.newFileChannel(path, options, attrs); } private static final FileAttribute[] NO_ATTRIBUTES = new FileAttribute[0]; /** * Opens or creates a file, returning a file channel to access the file. * @since 1.7 */ public static FileChannel open(Path path, OpenOption... options) throws IOException { Set set = new HashSet(options.length); Collections.addAll(set, options); return open(path, set, NO_ATTRIBUTES); } // -- Channel operations -- /** * Reads a sequence of bytes from this channel into the given buffer. */ public abstract int read(ByteBuffer dst) throws IOException; /** * Reads a sequence of bytes from this channel into a subsequence of the * given buffers. */ public abstract long read(ByteBuffer[] dsts, int offset, int length) throws IOException; /** * Reads a sequence of bytes from this channel into the given buffers. */ public final long read(ByteBuffer[] dsts) throws IOException { return read(dsts, 0, dsts.length); } /** * Writes a sequence of bytes to this channel from the given buffer. */ public abstract int write(ByteBuffer src) throws IOException; /** * Writes a sequence of bytes to this channel from a subsequence of the given buffers. */ public abstract long write(ByteBuffer[] srcs, int offset, int length) throws IOException; /** * Writes a sequence of bytes to this channel from the given buffers. */ public final long write(ByteBuffer[] srcs) throws IOException { return write(srcs, 0, srcs.length); } /** * Returns this channel's file position. */ public abstract long position() throws IOException; /** * Sets this channel's file position. * *

Setting the position to a value that is greater than the file's * current size is legal but does not change the size of the file. A later * attempt to read bytes at such a position will immediately return an * end-of-file indication. A later attempt to write bytes at such a * position will cause the file to be grown to accommodate the new bytes; * the values of any bytes between the previous end-of-file and the * newly-written bytes are unspecified.

* * 如果将位置设置在文件结束符之后,然后试图从文件通道中读取数据,读方法将返回-1 —— 文件结束标志。 * 如果将位置设置在文件结束符之后,然后向通道中写数据,文件将撑大到当前位置并(从当前位置开始)写入数据。这可能导致“文件空洞”,磁盘上物理文件中写入的数据间有空隙。 * * @param newPosition * The new position, a non-negative integer counting * the number of bytes from the beginning of the file */ public abstract FileChannel position(long newPosition) throws IOException; /** * Returns the current size of this channel's file. */ public abstract long size() throws IOException; /** * Truncates this channel's file to the given size. 截取一个文件 * *

If the given size is less than the file's current size then the file * is truncated, discarding any bytes beyond the new end of the file. If * the given size is greater than or equal to the file's current size then * the file is not modified. In either case, if this channel's file * position is greater than the given size then it is set to that size. */ public abstract FileChannel truncate(long size) throws IOException; /** * Forces any updates to this channel's file to be written to the storage * device that contains it. * 将通道里尚未写入磁盘的数据强制写到磁盘上。 * 说明: * 1)操作系统将数据缓存在内存中,所以无法保证写入到FileChannel里的数据一定会即时写到磁盘上。 * 2)如果要保证写入到FileChannel里的数据即时写到磁盘上,需要调用force()方法,参数表示是否将文件的元数据写到磁盘上。 */ public abstract void force(boolean metaData) throws IOException; // 通道之间的数据传输 /** * Transfers bytes from this channel's file to the given writable byte channel. */ public abstract long transferTo(long position, long count, WritableByteChannel target) throws IOException; /** * Transfers bytes into this channel's file from the given readable byte channel. */ public abstract long transferFrom(ReadableByteChannel src, long position, long count) throws IOException; /** * Reads a sequence of bytes from this channel into the given buffer, starting at the given file position. * * This method does not modify this channel's position. * If the given position is greater than the file's current size then no bytes are read. */ public abstract int read(ByteBuffer dst, long position) throws IOException; /** * Writes a sequence of bytes to this channel from the given buffer, starting at the given file position. * * This method does not modify this channel's position. * If the given position is greater than the file's current size then the file will be grown to accommodate the new bytes; * the values of any bytes between the previous end-of-file and the newly-written bytes are unspecified. */ public abstract int write(ByteBuffer src, long position) throws IOException; // -- Memory-mapped buffers -- /** * A typesafe enumeration for file-mapping modes. * * @since 1.4 * * @see java.nio.channels.FileChannel#map */ public static class MapMode { /** * Mode for a read-only mapping. */ public static final MapMode READ_ONLY = new MapMode("READ_ONLY"); /** * Mode for a read/write mapping. */ public static final MapMode READ_WRITE = new MapMode("READ_WRITE"); /** * Mode for a private (copy-on-write) mapping. */ public static final MapMode PRIVATE = new MapMode("PRIVATE"); private final String name; private MapMode(String name) { this.name = name; } public String toString() { return name; } } /** * Maps a region of this channel's file directly into memory. * * A region of a file may be mapped into memory in one of three modes: * * Read-only、Read/write、Private * * @param mode * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE * PRIVATE} defined in the {@link MapMode} class, according to * whether the file is to be mapped read-only, read/write, or * privately (copy-on-write), respectively * * @param position * The position within the file at which the mapped region * is to start; must be non-negative * * @param size * The size of the region to be mapped; must be non-negative and * no greater than {@link java.lang.Integer#MAX_VALUE} * * * @see java.nio.channels.FileChannel.MapMode * @see java.nio.MappedByteBuffer */ public abstract MappedByteBuffer map(MapMode mode, long position, long size) throws IOException; // -- Locks -- /** * Acquires a lock on the given region of this channel's file. * *

An invocation of this method will block until the region can be * locked, this channel is closed, or the invoking thread is interrupted, * whichever comes first. * *

If this channel is closed by another thread during an invocation of * this method then an {@link AsynchronousCloseException} will be thrown. * *

If the invoking thread is interrupted while waiting to acquire the * lock then its interrupt status will be set and a {@link * FileLockInterruptionException} will be thrown. If the invoker's * interrupt status is set when this method is invoked then that exception * will be thrown immediately; the thread's interrupt status will not be * changed. * *

The region specified by the position and size * parameters need not be contained within, or even overlap, the actual * underlying file. Lock regions are fixed in size; if a locked region * initially contains the end of the file and the file grows beyond the * region then the new portion of the file will not be covered by the lock. * If a file is expected to grow in size and a lock on the entire file is * required then a region starting at zero, and no smaller than the * expected maximum size of the file, should be locked. The zero-argument * {@link #lock()} method simply locks a region of size {@link * Long#MAX_VALUE}. * *

Some operating systems do not support shared locks, in which case a * request for a shared lock is automatically converted into a request for * an exclusive lock. Whether the newly-acquired lock is shared or * exclusive may be tested by invoking the resulting lock object's {@link * FileLock#isShared() isShared} method. * *

File locks are held on behalf of the entire Java virtual machine. * They are not suitable for controlling access to a file by multiple * threads within the same virtual machine.

* * @param position * The position at which the locked region is to start; must be * non-negative * * @param size * The size of the locked region; must be non-negative, and the sum * position + size must be non-negative * * @param shared * true to request a shared lock, in which case this * channel must be open for reading (and possibly writing); * false to request an exclusive lock, in which case this * channel must be open for writing (and possibly reading) * * @return A lock object representing the newly-acquired lock * * @throws IllegalArgumentException * If the preconditions on the parameters do not hold * * @throws ClosedChannelException * If this channel is closed * * @throws AsynchronousCloseException * If another thread closes this channel while the invoking * thread is blocked in this method * * @throws FileLockInterruptionException * If the invoking thread is interrupted while blocked in this * method * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region * * @throws NonReadableChannelException * If shared is true this channel was not * opened for reading * * @throws NonWritableChannelException * If shared is false but this channel was not * opened for writing * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #tryLock() * @see #tryLock(long,long,boolean) */ public abstract FileLock lock(long position, long size, boolean shared) throws IOException; /** * Acquires an exclusive lock on this channel's file. * *

An invocation of this method of the form fc.lock() behaves * in exactly the same way as the invocation * *

     *     fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) 
* * @return A lock object representing the newly-acquired lock * * @throws ClosedChannelException * If this channel is closed * * @throws AsynchronousCloseException * If another thread closes this channel while the invoking * thread is blocked in this method * * @throws FileLockInterruptionException * If the invoking thread is interrupted while blocked in this * method * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region of the same file * * @throws NonWritableChannelException * If this channel was not opened for writing * * @throws IOException * If some other I/O error occurs * * @see #lock(long,long,boolean) * @see #tryLock() * @see #tryLock(long,long,boolean) */ public final FileLock lock() throws IOException { return lock(0L, Long.MAX_VALUE, false); } /** * Attempts to acquire a lock on the given region of this channel's file. * *

This method does not block. An invocation always returns * immediately, either having acquired a lock on the requested region or * having failed to do so. If it fails to acquire a lock because an * overlapping lock is held by another program then it returns * null. If it fails to acquire a lock for any other reason then * an appropriate exception is thrown. * *

The region specified by the position and size * parameters need not be contained within, or even overlap, the actual * underlying file. Lock regions are fixed in size; if a locked region * initially contains the end of the file and the file grows beyond the * region then the new portion of the file will not be covered by the lock. * If a file is expected to grow in size and a lock on the entire file is * required then a region starting at zero, and no smaller than the * expected maximum size of the file, should be locked. The zero-argument * {@link #tryLock()} method simply locks a region of size {@link * Long#MAX_VALUE}. * *

Some operating systems do not support shared locks, in which case a * request for a shared lock is automatically converted into a request for * an exclusive lock. Whether the newly-acquired lock is shared or * exclusive may be tested by invoking the resulting lock object's {@link * FileLock#isShared() isShared} method. * *

File locks are held on behalf of the entire Java virtual machine. * They are not suitable for controlling access to a file by multiple * threads within the same virtual machine.

* * @param position * The position at which the locked region is to start; must be * non-negative * * @param size * The size of the locked region; must be non-negative, and the sum * position + size must be non-negative * * @param shared * true to request a shared lock, * false to request an exclusive lock * * @return A lock object representing the newly-acquired lock, * or null if the lock could not be acquired * because another program holds an overlapping lock * * @throws IllegalArgumentException * If the preconditions on the parameters do not hold * * @throws ClosedChannelException * If this channel is closed * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region of the same file * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #lock(long,long,boolean) * @see #tryLock() */ public abstract FileLock tryLock(long position, long size, boolean shared) throws IOException; /** * Attempts to acquire an exclusive lock on this channel's file. * *

An invocation of this method of the form fc.tryLock() * behaves in exactly the same way as the invocation * *

     *     fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) 
* * @return A lock object representing the newly-acquired lock, * or null if the lock could not be acquired * because another program holds an overlapping lock * * @throws ClosedChannelException * If this channel is closed * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #lock(long,long,boolean) * @see #tryLock(long,long,boolean) */ public final FileLock tryLock() throws IOException { return tryLock(0L, Long.MAX_VALUE, false); } }

你可能感兴趣的:(NIO)