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 17 package java.nio.channels; 18 19 import java.io.IOException; 20 import 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 */ 27 public 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 */ write(ByteBuffer[] buffers)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 */ write(ByteBuffer[] buffers, int offset, int length)93 public long write(ByteBuffer[] buffers, int offset, int length) 94 throws IOException; 95 } 96