1 /*
2 * Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 * <tt>0</tt> <tt><=</tt> <i>n</i> <tt><=</tt> <i>r</i>.
70 * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
71 * are transferred into buffer <tt>dsts[offset]</tt>, up to the next
72 * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
73 * <tt>dsts[offset+1]</tt>, 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 <tt>dsts.length</tt>
91 *
92 * @param length
93 * The maximum number of buffers to be accessed; must be
94 * non-negative and no larger than
95 * <tt>dsts.length</tt> - <tt>offset</tt>
96 *
97 * @return The number of bytes read, possibly zero,
98 * or <tt>-1</tt> if the channel has reached end-of-stream
99 *
100 * @throws IndexOutOfBoundsException
101 * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
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 <tt>c.read(dsts)</tt>
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 <tt>-1</tt> 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 }
Save This Page