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 write a set of buffers in a single
24 * operation. The corresponding interface for read operations is
25 * {@link ScatteringByteChannel}.
26 */
27public interface GatheringByteChannel extends WritableByteChannel {
28
29    /**
30     * Writes bytes from all the given buffers to a channel.
31     * <p>
32     * This method is equivalent to: {@code write(buffers, 0, buffers.length);}
33     *
34     * @param buffers
35     *            the buffers containing bytes to be written.
36     * @return the number of bytes actually written.
37     * @throws AsynchronousCloseException
38     *             if the channel is closed by another thread during this write
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 IndexOutOfBoundsException
47     *             if {@code offset < 0} or {@code length < 0}, or if
48     *             {@code offset + length} is greater than the size of
49     *             {@code buffers}.
50     * @throws IOException
51     *             if another I/O error occurs; details are in the message.
52     * @throws NonWritableChannelException
53     *             if the channel has not been opened in a mode that permits
54     *             writing.
55     */
56    public long write(ByteBuffer[] buffers) throws IOException;
57
58    /**
59     * Attempts to write all <code>remaining()</code> bytes from {@code length}
60     * byte buffers, in order, starting at {@code buffers[offset]}. The number
61     * of bytes actually written is returned.
62     * <p>
63     * If a write operation is in progress, subsequent threads will block until
64     * the write is completed and then contend for the ability to write.
65     *
66     * @param buffers
67     *            the array of byte buffers that is the source for bytes written
68     *            to the channel.
69     * @param offset
70     *            the index of the first buffer in {@code buffers }to get bytes
71     *            from.
72     * @param length
73     *            the number of buffers to get bytes from.
74     * @return the number of bytes actually written.
75     * @throws AsynchronousCloseException
76     *             if the channel is closed by another thread during this write
77     *             operation.
78     * @throws ClosedByInterruptException
79     *             if another thread interrupts the calling thread while the
80     *             operation is in progress. The interrupt state of the calling
81     *             thread is set and the channel is closed.
82     * @throws ClosedChannelException
83     *             if the channel is closed.
84     * @throws IndexOutOfBoundsException
85     *             if {@code offset < 0} or {@code length < 0}, or if
86     *             {@code offset + length} is greater than the size of
87     *             {@code buffers}.
88     * @throws IOException
89     *             if another I/O error occurs; details are in the message.
90     * @throws NonWritableChannelException
91     *             if the channel was not opened for writing.
92     */
93    public long write(ByteBuffer[] buffers, int offset, int length)
94            throws IOException;
95}
96