1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package java.nio.channels;
18
19import java.io.IOException;
20import java.nio.ByteBuffer;
21
22/**
23 * The interface for channels that can read data into a set of buffers in a
24 * single operation. The corresponding interface for writes is
25 * {@link GatheringByteChannel}.
26 */
27public interface ScatteringByteChannel extends ReadableByteChannel {
28
29    /**
30     * Reads bytes from this channel into the specified array of buffers.
31     * <p>
32     * This method is equivalent to {@code read(buffers, 0, buffers.length);}
33     *
34     * @param buffers
35     *            the array of byte buffers to store the bytes being read.
36     * @return the number of bytes actually read.
37     * @throws AsynchronousCloseException
38     *             if the channel is closed by another thread during this read
39     *             operation.
40     * @throws ClosedByInterruptException
41     *             if another thread interrupts the calling thread while the
42     *             operation is in progress. The interrupt state of the calling
43     *             thread is set and the channel is closed.
44     * @throws ClosedChannelException
45     *             if the channel is closed.
46     * @throws IOException
47     *             if another I/O error occurs; details are in the message.
48     * @throws NonWritableChannelException
49     *             if the channel has not been opened in a mode that permits
50     *             reading.
51     */
52    public long read(ByteBuffer[] buffers) throws IOException;
53
54    /**
55     * Attempts to read all {@code remaining()} bytes from {@code length} byte
56     * buffers, in order, starting at {@code buffers[offset]}. The number of
57     * bytes actually read is returned.
58     * <p>
59     * If a read operation is in progress, subsequent threads will block until
60     * the read is completed and will then contend for the ability to read.
61     *
62     * @param buffers
63     *            the array of byte buffers into which the bytes will be copied.
64     * @param offset
65     *            the index of the first buffer to store bytes in.
66     * @param length
67     *            the maximum number of buffers to store bytes in.
68     * @return the number of bytes actually read.
69     * @throws AsynchronousCloseException
70     *             if the channel is closed by another thread during this read
71     *             operation.
72     * @throws ClosedByInterruptException
73     *             if another thread interrupts the calling thread while the
74     *             operation is in progress. The interrupt state of the calling
75     *             thread is set and the channel is closed.
76     * @throws ClosedChannelException
77     *             if the channel is closed.
78     * @throws IndexOutOfBoundsException
79     *             if {@code offset < 0} or {@code length < 0}, or if
80     *             {@code offset + length} is greater than the size of
81     *             {@code buffers}.
82     * @throws IOException
83     *             if another I/O error occurs; details are in the message.
84     * @throws NonWritableChannelException
85     *             if the channel has not been opened in a mode that permits
86     *             reading.
87     */
88    public long read(ByteBuffer[] buffers, int offset, int length)
89            throws IOException;
90}
91