KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > nio > channels > ScatteringByteChannel


1 /*
2  * @(#)ScatteringByteChannel.java 1.13 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.nio.channels;
9
10 import java.io.IOException JavaDoc;
11 import java.nio.ByteBuffer JavaDoc;
12
13
14 /**
15  * A channel that can read bytes into a sequence of buffers.
16  *
17  * <p> A <i>scattering</i> read operation reads, in a single invocation, a
18  * sequence of bytes into one or more of a given sequence of buffers.
19  * Scattering reads are often useful when implementing network protocols or
20  * file formats that, for example, group data into segments consisting of one
21  * or more fixed-length headers followed by a variable-length body. Similar
22  * <i>gathering</i> write operations are defined in the {@link
23  * GatheringByteChannel} interface. </p>
24  *
25  *
26  * @author Mark Reinhold
27  * @author JSR-51 Expert Group
28  * @version 1.13, 03/12/19
29  * @since 1.4
30  */
31
32 public interface ScatteringByteChannel
33     extends ReadableByteChannel JavaDoc
34 {
35
36     /**
37      * Reads a sequence of bytes from this channel into a subsequence of the
38      * given buffers.
39      *
40      * <p> An invocation of this method attempts to read up to <i>r</i> bytes
41      * from this channel, where <i>r</i> is the total number of bytes remaining
42      * the specified subsequence of the given buffer array, that is,
43      *
44      * <blockquote><pre>
45      * dsts[offset].remaining()
46      * + dsts[offset+1].remaining()
47      * + ... + dsts[offset+length-1].remaining()</pre></blockquote>
48      *
49      * at the moment that this method is invoked.
50      *
51      * <p> Suppose that a byte sequence of length <i>n</i> is read, where
52      * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
53      * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
54      * are transferred into buffer <tt>dsts[offset]</tt>, up to the next
55      * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
56      * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence
57      * is transferred into the given buffers. As many bytes as possible are
58      * transferred into each buffer, hence the final position of each updated
59      * buffer, except the last updated buffer, is guaranteed to be equal to
60      * that buffer's limit.
61      *
62      * <p> This method may be invoked at any time. If another thread has
63      * already initiated a read operation upon this channel, however, then an
64      * invocation of this method will block until the first operation is
65      * complete. </p>
66      *
67      * @param dsts
68      * The buffers into which bytes are to be transferred
69      *
70      * @param offset
71      * The offset within the buffer array of the first buffer into
72      * which bytes are to be transferred; must be non-negative and no
73      * larger than <tt>dsts.length</tt>
74      *
75      * @param length
76      * The maximum number of buffers to be accessed; must be
77      * non-negative and no larger than
78      * <tt>dsts.length</tt>&nbsp;-&nbsp;<tt>offset</tt>
79      *
80      * @return The number of bytes read, possibly zero,
81      * or <tt>-1</tt> if the channel has reached end-of-stream
82      *
83      * @throws IndexOutOfBoundsException
84      * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
85      * parameters do not hold
86      *
87      * @throws NonReadableChannelException
88      * If this channel was not opened for reading
89      *
90      * @throws ClosedChannelException
91      * If this channel is closed
92      *
93      * @throws AsynchronousCloseException
94      * If another thread closes this channel
95      * while the read operation is in progress
96      *
97      * @throws ClosedByInterruptException
98      * If another thread interrupts the current thread
99      * while the read operation is in progress, thereby
100      * closing the channel and setting the current thread's
101      * interrupt status
102      *
103      * @throws IOException
104      * If some other I/O error occurs
105      */
106     public long read(ByteBuffer JavaDoc[] dsts, int offset, int length)
107     throws IOException JavaDoc;
108
109     /**
110      * Reads a sequence of bytes from this channel into the given buffers.
111      *
112      * <p> An invocation of this method of the form <tt>c.read(dsts)</tt>
113      * behaves in exactly the same manner as the invocation
114      *
115      * <blockquote><pre>
116      * c.read(dsts, 0, srcs.length);</pre></blockquote>
117      *
118      * @param dsts
119      * The buffers into which bytes are to be transferred
120      *
121      * @return The number of bytes read, possibly zero,
122      * or <tt>-1</tt> if the channel has reached end-of-stream
123      *
124      * @throws NonReadableChannelException
125      * If this channel was not opened for reading
126      *
127      * @throws ClosedChannelException
128      * If this channel is closed
129      *
130      * @throws AsynchronousCloseException
131      * If another thread closes this channel
132      * while the read operation is in progress
133      *
134      * @throws ClosedByInterruptException
135      * If another thread interrupts the current thread
136      * while the read operation is in progress, thereby
137      * closing the channel and setting the current thread's
138      * interrupt status
139      *
140      * @throws IOException
141      * If some other I/O error occurs
142      */
143     public long read(ByteBuffer JavaDoc[] dsts) throws IOException JavaDoc;
144
145 }
146
Popular Tags