1 /*
2 * Copyright (c) 2000, 2019, 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
26 package java.nio.channels;
27
28 import java.io.IOException;
29 import 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
49 public 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 IllegalArgumentException
111 * If any of the buffers is read-only
112 *
113 * @throws AsynchronousCloseException
114 * If another thread closes this channel
115 * while the read operation is in progress
116 *
117 * @throws ClosedByInterruptException
118 * If another thread interrupts the current thread
119 * while the read operation is in progress, thereby
120 * closing the channel and setting the current thread's
121 * interrupt status
122 *
123 * @throws IOException
124 * If some other I/O error occurs
125 */
126 public long read(ByteBuffer[] dsts, int offset, int length)
127 throws IOException;
128
129 /**
130 * Reads a sequence of bytes from this channel into the given buffers.
131 *
132 * <p> An invocation of this method of the form {@code c.read(dsts)}
133 * behaves in exactly the same manner as the invocation
134 *
135 * <blockquote><pre>
136 * c.read(dsts, 0, dsts.length);</pre></blockquote>
137 *
138 * @param dsts
139 * The buffers into which bytes are to be transferred
140 *
141 * @return The number of bytes read, possibly zero,
142 * or {@code -1} if the channel has reached end-of-stream
143 *
144 * @throws NonReadableChannelException
145 * If this channel was not opened for reading
146 *
147 * @throws ClosedChannelException
148 * If this channel is closed
149 *
150 * @throws IllegalArgumentException
151 * If any of the buffers is read-only
152 *
153 * @throws AsynchronousCloseException
154 * If another thread closes this channel
155 * while the read operation is in progress
156 *
157 * @throws ClosedByInterruptException
158 * If another thread interrupts the current thread
159 * while the read operation is in progress, thereby
160 * closing the channel and setting the current thread's
161 * interrupt status
162 *
163 * @throws IOException
164 * If some other I/O error occurs
165 */
166 public long read(ByteBuffer[] dsts) throws IOException;
167
168 }