1/* 2 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package java.nio.channels; 27 28import java.io.IOException; 29import java.nio.ByteBuffer; 30 31 32/** 33 * A channel that can read bytes into a sequence of buffers. 34 * 35 * <p> A <i>scattering</i> read operation reads, in a single invocation, a 36 * sequence of bytes into one or more of a given sequence of buffers. 37 * Scattering reads are often useful when implementing network protocols or 38 * file formats that, for example, group data into segments consisting of one 39 * or more fixed-length headers followed by a variable-length body. Similar 40 * <i>gathering</i> write operations are defined in the {@link 41 * GatheringByteChannel} interface. </p> 42 * 43 * 44 * @author Mark Reinhold 45 * @author JSR-51 Expert Group 46 * @since 1.4 47 */ 48 49public interface ScatteringByteChannel 50 extends ReadableByteChannel 51{ 52 53 /** 54 * Reads a sequence of bytes from this channel into a subsequence of the 55 * given buffers. 56 * 57 * <p> An invocation of this method attempts to read up to <i>r</i> bytes 58 * from this channel, where <i>r</i> is the total number of bytes remaining 59 * the specified subsequence of the given buffer array, that is, 60 * 61 * <blockquote><pre> 62 * dsts[offset].remaining() 63 * + dsts[offset+1].remaining() 64 * + ... + dsts[offset+length-1].remaining()</pre></blockquote> 65 * 66 * at the moment that this method is invoked. 67 * 68 * <p> Suppose that a byte sequence of length <i>n</i> is read, where 69 * {@code 0} {@code <=} <i>n</i> {@code <=} <i>r</i>. 70 * Up to the first {@code dsts[offset].remaining()} bytes of this sequence 71 * are transferred into buffer {@code dsts[offset]}, up to the next 72 * {@code dsts[offset+1].remaining()} bytes are transferred into buffer 73 * {@code dsts[offset+1]}, and so forth, until the entire byte sequence 74 * is transferred into the given buffers. As many bytes as possible are 75 * transferred into each buffer, hence the final position of each updated 76 * buffer, except the last updated buffer, is guaranteed to be equal to 77 * that buffer's limit. 78 * 79 * <p> This method may be invoked at any time. If another thread has 80 * already initiated a read operation upon this channel, however, then an 81 * invocation of this method will block until the first operation is 82 * complete. </p> 83 * 84 * @param dsts 85 * The buffers into which bytes are to be transferred 86 * 87 * @param offset 88 * The offset within the buffer array of the first buffer into 89 * which bytes are to be transferred; must be non-negative and no 90 * larger than {@code dsts.length} 91 * 92 * @param length 93 * The maximum number of buffers to be accessed; must be 94 * non-negative and no larger than 95 * {@code dsts.length} - {@code offset} 96 * 97 * @return The number of bytes read, possibly zero, 98 * or {@code -1} if the channel has reached end-of-stream 99 * 100 * @throws IndexOutOfBoundsException 101 * If the preconditions on the {@code offset} and {@code length} 102 * parameters do not hold 103 * 104 * @throws NonReadableChannelException 105 * If this channel was not opened for reading 106 * 107 * @throws ClosedChannelException 108 * If this channel is closed 109 * 110 * @throws AsynchronousCloseException 111 * If another thread closes this channel 112 * while the read operation is in progress 113 * 114 * @throws ClosedByInterruptException 115 * If another thread interrupts the current thread 116 * while the read operation is in progress, thereby 117 * closing the channel and setting the current thread's 118 * interrupt status 119 * 120 * @throws IOException 121 * If some other I/O error occurs 122 */ 123 public long read(ByteBuffer[] dsts, int offset, int length) 124 throws IOException; 125 126 /** 127 * Reads a sequence of bytes from this channel into the given buffers. 128 * 129 * <p> An invocation of this method of the form {@code c.read(dsts)} 130 * behaves in exactly the same manner as the invocation 131 * 132 * <blockquote><pre> 133 * c.read(dsts, 0, dsts.length);</pre></blockquote> 134 * 135 * @param dsts 136 * The buffers into which bytes are to be transferred 137 * 138 * @return The number of bytes read, possibly zero, 139 * or {@code -1} if the channel has reached end-of-stream 140 * 141 * @throws NonReadableChannelException 142 * If this channel was not opened for reading 143 * 144 * @throws ClosedChannelException 145 * If this channel is closed 146 * 147 * @throws AsynchronousCloseException 148 * If another thread closes this channel 149 * while the read operation is in progress 150 * 151 * @throws ClosedByInterruptException 152 * If another thread interrupts the current thread 153 * while the read operation is in progress, thereby 154 * closing the channel and setting the current thread's 155 * interrupt status 156 * 157 * @throws IOException 158 * If some other I/O error occurs 159 */ 160 public long read(ByteBuffer[] dsts) throws IOException; 161 162} 163