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 read data into a set of buffers in a 24 * single operation. The corresponding interface for writes is 25 * {@link GatheringByteChannel}. 26 */ 27 public 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 */ read(ByteBuffer[] buffers)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 */ read(ByteBuffer[] buffers, int offset, int length)88 public long read(ByteBuffer[] buffers, int offset, int length) 89 throws IOException; 90 } 91