java nio SeekableByteChannel源码分析

package java.nio.channels;

import java.nio.ByteBuffer;
import java.io.IOException;

/**
 * 保持当前position并允许改变position的字节通道。
 *
 * <p> 可查找字节通道连接到一个实体，通常是一个文件，
 * 该实体包含一个可读写的可变长度的字节序列。可以通过position()查询和通过position(long)修改当前位置。
 * 通道还提供对通道所连接的实体的当前大小的访问。
 * 当写入的字节超过其当前大小时，size增加;
 * 当它被truncate时，size减小。
 *
 * <p> position(long)和truncate方法如果没有返回值，则指定它们返回调用它们的通道。
 * 这允许被调用的方法成链。该接口的实现应该专门化返回类型，使实现类上的方法调用可以被链接。
 *
 * @since 1.7
 * @see java.nio.file.Files#newByteChannel
 */

public interface SeekableByteChannel
    extends ByteChannel
{
    /**
     * 从这个通道读取一个字节序列到给定的缓冲区。
     *
     * <p> 从这个通道的当前位置开始读取字节，然后用实际读取的字节数更新位置。
     * 否则，此方法的行为与ReadableByteChannel接口中指定的完全相同。
     */
    @Override
    int read(ByteBuffer dst) throws IOException;

    /**
     * 将一个字节序列从给定的缓冲区写入此通道。
     *
     * <p> 字节从该通道的当前位置开始写入，除非该通道连接到一个实体，
     * 比如一个文件， 该文件是用APPEND选项打开的，在这种情况下，位置首先被推进到末尾。
     * 通道所连接的实体会增长，如果必要的话，以容纳写入的字节，然后位置会随着实际写入的字节数而更新。
     * 否则，此方法的行为与WritableByteChannel接口所指定的完全相同。
     */
    @Override
    int write(ByteBuffer src) throws IOException;

    /**
     * 返回此通道的位置。
     *
     * @return  This channel's position,
     *          a non-negative integer counting the number of bytes
     *          from the beginning of the entity to the current position
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If some other I/O error occurs
     */
    long position() throws IOException;

    /**
     * 设置此通道的位置。
     *
     * <p> 将位置设置为大于当前大小的值是合法的，但不会改变实体的大小。
     * 稍后尝试在这样的位置读取字节将，立即返回文件结束指示。
     * 稍后尝试在这样的位置写入字节将，导致实体增长以适应新的字节;
     * 前一个文件结尾和新写入字节之间的任何字节的值都是未指定的。
     *
     * <p> 当连接到使用APPEND选项打开的实体(通常是文件)时，不建议设置通道的位置。
     * 当打开append时，在写入之前，会先将位置推进到末尾。
     *
     * @param  newPosition
     *         The new position, a non-negative integer counting
     *         the number of bytes from the beginning of the entity
     *
     * @return  This channel
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IllegalArgumentException
     *          If the new position is negative
     * @throws  IOException
     *          If some other I/O error occurs
     */
    SeekableByteChannel position(long newPosition) throws IOException;

    /**
     * 返回此通道所连接的实体的当前大小。
     *
     * @return  The current size, measured in bytes
     *
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If some other I/O error occurs
     */
    long size() throws IOException;

    /**
     * 将此通道所连接的实体截断到给定的大小。
     *
     * <p> 如果给定的size小于当前size，则实体将被截断，丢弃新结尾以外的任何字节。
     * 如果给定的size大于或等于当前size，则不修改实体。
     * 在这两种情况下，如果当前位置大于给定的size，则将位置设置为该size。
     *
     * <p> 此接口的实现可以禁止在连接到使用APPEND选项打开的实体(通常是文件)时截断。
     *
     * @param  size
     *         The new size, a non-negative byte count
     *
     * @return  This channel
     *
     * @throws  NonWritableChannelException
     *          If this channel was not opened for writing
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IllegalArgumentException
     *          If the new size is negative
     * @throws  IOException
     *          If some other I/O error occurs
     */
    SeekableByteChannel truncate(long size) throws IOException;
}