luni/src/main/java/java/nio/channels/SeekableByteChannel.java

/*
 * Copyright (C) 2014 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package java.nio.channels;

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

/**
 * An interface for channels that keep a pointer to a current position within an underlying
 * byte-based data source such as a file.
 *
 * <p>SeekableByteChannels have a pointer into the underlying data source which is referred to as a
 * <em>position</em>. The position can be manipulated by moving it within the data source, and the
 * current position can be queried.
 *
 * <p>SeekableByteChannels also have an associated <em>size</em>. The size of the channel is the
 * number of bytes that the data source currently contains. The size of the data source can be
 * manipulated by adding more bytes to the end or by removing bytes from the end. See
 * {@link #truncate}, {@link #position} and {@link #write} for details. The current size can also
 * be queried.
 *
 * @since 1.7
 * @hide 1.7
 */
public interface SeekableByteChannel extends ByteChannel {

  /**
   * Returns the current position as a positive number of bytes from the start of the underlying
   * data source.
   *
   * @throws ClosedChannelException
   *     if this channel is closed.
   * @throws IOException
   *     if another I/O error occurs.
   */
  long position() throws IOException;

  /**
   * Sets the channel's position to {@code newPosition}.
   *
   * <p>The argument is the number of bytes counted from the start of the data source. The position
   * cannot be set to a value that is negative. The new position can be set beyond the current
   * size. If set beyond the current size, attempts to read will return end-of-file. Write
   * operations will succeed but they will fill the bytes between the current end of the data
   * source
   * and the new position with the required number of (unspecified) byte values.
   *
   * @return the channel.
   * @throws IllegalArgumentException
   *     if the new position is negative.
   * @throws ClosedChannelException
   *     if this channel is closed.
   * @throws IOException
   *     if another I/O error occurs.
   */
  SeekableByteChannel position(long newPosition) throws IOException;

  /**
   * Returns the size of the data source underlying this channel in bytes.
   *
   * @throws ClosedChannelException
   *     if this channel is closed.
   * @throws IOException
   *     if an I/O error occurs.
   */
  long size() throws IOException;

  /**
   * Truncates the data source underlying this channel to a given size. Any bytes beyond the given
   * size are removed. If there are no bytes beyond the given size then the contents are
   * unmodified.
   *
   * <p>If the position is currently greater than the given size, then it is set to the new size.
   *
   * @return this channel.
   * @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.
   */
  SeekableByteChannel truncate(long size) throws IOException;

  /**
   * Writes bytes from the given byte buffer to this channel.
   *
   * <p>The bytes are written starting at the channel's current position, and after some number of
   * bytes are written (up to the {@link java.nio.Buffer#remaining() remaining} number of bytes in
   * the buffer) the channel's position is increased by the number of bytes actually written.
   *
   * <p>If the channel's position is beyond the current end of the underlying data source, then the
   * data source is first extended up to the given position by the required number of unspecified
   * byte values.
   *
   * @param buffer
   *     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.
   */
  @Override
  int write(ByteBuffer buffer) throws IOException;

  /**
   * Reads bytes from this channel into the given buffer.
   *
   * <p>If the channels position is beyond the current end of the underlying data source then
   * end-of-file (-1) is returned.
   *
   * <p>The bytes are read starting at the channel's current position, and after some number of
   * bytes are read (up to the {@link java.nio.Buffer#remaining() remaining} number of bytes in the
   * buffer) the channel's position is increased by the number of bytes actually read. The bytes
   * will be read into the buffer starting at the buffer's current
   * {@link java.nio.Buffer#position() position}. The buffer's {@link java.nio.Buffer#limit()
   * limit} is not changed.
   *
   * <p>The call may block if other threads are also attempting to read from the same channel.
   *
   * @param buffer
   *     the byte buffer to receive the bytes.
   * @return the number of bytes actually read, or -1 if the end of the data has been reached
   * @throws AsynchronousCloseException
   *     if another thread closes the channel during the read.
   * @throws ClosedByInterruptException
   *     if another thread interrupts the calling thread while the operation is in progress. The
   *     interrupt state of the calling thread is set and the channel is closed.
   * @throws ClosedChannelException
   *     if the channel is closed.
   * @throws IOException
   *     another I/O error occurs, details are in the message.
   * @throws NonReadableChannelException
   *     if the channel was not opened for reading.
   */
  @Override
  int read(ByteBuffer buffer) throws IOException;

}