001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package java.nio.channels;
018:
019: import java.io.IOException;
020: import java.nio.ByteBuffer;
021:
022: /**
023: * The interface to channels that can read a set of buffers in a single
024: * operation.
025: * <p>
026: * The corresponding interface for writes is called
027: * <code>GatheringByteChannel</code>.
028: */
029: public interface ScatteringByteChannel extends ReadableByteChannel {
030:
031: /**
032: * Reads bytes from the channel into all the given buffers.
033: * <p>
034: * This method is equivalent to:
035: *
036: * <pre>
037: * read(buffers, 0, buffers.length);
038: * </pre>
039: *
040: * </p>
041: *
042: * @param buffers
043: * the array of byte buffers to receive the bytes being read.
044: * @return the number of bytes actually read.
045: * @throws ClosedChannelException
046: * if the channel is closed.
047: * @throws NonReadableChannelException
048: * if the channel is open, but not in a mode that permits
049: * reading.
050: * @throws ClosedByInterruptException
051: * if the thread is interrupted in its IO operation by another
052: * thread closing the channel.
053: * @throws AsynchronousCloseException
054: * if the read is interrupted by another thread sending an
055: * explicit interrupt.
056: * @throws IOException
057: * if some other type of exception occurs. Details are in the
058: * message.
059: */
060: public long read(ByteBuffer[] buffers) throws IOException;
061:
062: /**
063: * Reads bytes from the channel into a subset of the given buffers.
064: * <p>
065: * This method attempts to read all of the <code>remaining()</code> bytes
066: * from <code>length</code> byte buffers, in order, starting at
067: * <code>buffers[offset]</code>. The number of bytes actually read is
068: * returned.
069: * </p>
070: * <p>
071: * If a read operation is in progress, subsequent threads will block until
072: * the read is completed, and will then contend for the ability to read.
073: * </p>
074: *
075: * @param buffers
076: * the array of byte buffers into which the bytes will be read.
077: * @param offset
078: * the index of the first buffer to read.
079: * @param length
080: * the maximum number of buffers to read.
081: * @return the number of bytes actually read.
082: * @throws IndexOutOfBoundsException
083: * if offset < 0 or > buffers.length; or length < 0 or >
084: * buffers.length - offset.
085: * @throws NonReadableChannelException
086: * if the channel was not opened for reading.
087: * @throws ClosedChannelException
088: * the channel is currently closed.
089: * @throws AsynchronousCloseException
090: * the channel was closed by another thread while the write was
091: * underway.
092: * @throws ClosedByInterruptException
093: * the thread was interrupted by another thread while the write
094: * was underway.
095: * @throws IOException
096: * if some other type of exception occurs. Details are in the
097: * message.
098: */
099: public long read(ByteBuffer[] buffers, int offset, int length)
100: throws IOException;
101: }
|