author | bpb |
Fri, 22 Nov 2019 09:00:16 -0800 | |
changeset 59227 | 46084917fde7 |
parent 47216 | 71c04702a3d5 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
59227
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
2 |
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. |
2 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 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 |
* |
|
5506 | 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. |
|
2 | 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 |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
69 |
* {@code 0} {@code <=} <i>n</i> {@code <=} <i>r</i>. |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
70 |
* Up to the first {@code dsts[offset].remaining()} bytes of this sequence |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
71 |
* are transferred into buffer {@code dsts[offset]}, up to the next |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
72 |
* {@code dsts[offset+1].remaining()} bytes are transferred into buffer |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
73 |
* {@code dsts[offset+1]}, and so forth, until the entire byte sequence |
2 | 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 |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
90 |
* larger than {@code dsts.length} |
2 | 91 |
* |
92 |
* @param length |
|
93 |
* The maximum number of buffers to be accessed; must be |
|
94 |
* non-negative and no larger than |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
95 |
* {@code dsts.length} - {@code offset} |
2 | 96 |
* |
97 |
* @return The number of bytes read, possibly zero, |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
98 |
* or {@code -1} if the channel has reached end-of-stream |
2 | 99 |
* |
100 |
* @throws IndexOutOfBoundsException |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
101 |
* If the preconditions on the {@code offset} and {@code length} |
2 | 102 |
* parameters do not hold |
103 |
* |
|
59227
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
104 |
* @throws IllegalArgumentException |
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
105 |
* If any of the buffers is read-only |
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
106 |
* |
2 | 107 |
* @throws NonReadableChannelException |
108 |
* If this channel was not opened for reading |
|
109 |
* |
|
110 |
* @throws ClosedChannelException |
|
111 |
* If this channel is closed |
|
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 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
132 |
* <p> An invocation of this method of the form {@code c.read(dsts)} |
2 | 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, |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
25859
diff
changeset
|
142 |
* or {@code -1} if the channel has reached end-of-stream |
2 | 143 |
* |
59227
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
144 |
* @throws IllegalArgumentException |
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
145 |
* If any of the buffers is read-only |
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
47216
diff
changeset
|
146 |
* |
2 | 147 |
* @throws NonReadableChannelException |
148 |
* If this channel was not opened for reading |
|
149 |
* |
|
150 |
* @throws ClosedChannelException |
|
151 |
* If this channel is closed |
|
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 |
} |