KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)GatheringByteChannel.java 1.12 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 write bytes from a sequence of buffers.
16  *
17  * <p> A <i>gathering</i> write operation writes, in a single invocation, a
18  * sequence of bytes from one or more of a given sequence of buffers.
19  * Gathering writes 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>scattering</i> read operations are defined in the {@link
23  * ScatteringByteChannel} interface. </p>
24  *
25  *
26  * @author Mark Reinhold
27  * @author JSR-51 Expert Group
28  * @version 1.12, 03/12/19
29  * @since 1.4
30  */
31
32 public interface GatheringByteChannel
33     extends WritableByteChannel JavaDoc
34 {
35
36     /**
37      * Writes a sequence of bytes to this channel from a subsequence of the
38      * given buffers.
39      *
40      * <p> An attempt is made to write up to <i>r</i> bytes to this channel,
41      * where <i>r</i> is the total number of bytes remaining in the specified
42      * subsequence of the given buffer array, that is,
43      *
44      * <blockquote><pre>
45      * srcs[offset].remaining()
46      * + srcs[offset+1].remaining()
47      * + ... + srcs[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 written, 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>srcs[offset].remaining()</tt> bytes of this sequence
54      * are written from buffer <tt>srcs[offset]</tt>, up to the next
55      * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer
56      * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is
57      * written. As many bytes as possible are written from each buffer, hence
58      * the final position of each updated buffer, except the last updated
59      * buffer, is guaranteed to be equal to that buffer's limit.
60      *
61      * <p> Unless otherwise specified, a write operation will return only after
62      * writing all of the <i>r</i> requested bytes. Some types of channels,
63      * depending upon their state, may write only some of the bytes or possibly
64      * none at all. A socket channel in non-blocking mode, for example, cannot
65      * write any more bytes than are free in the socket's output buffer.
66      *
67      * <p> This method may be invoked at any time. If another thread has
68      * already initiated a write operation upon this channel, however, then an
69      * invocation of this method will block until the first operation is
70      * complete. </p>
71      *
72      * @param srcs
73      * The buffers from which bytes are to be retrieved
74      *
75      * @param offset
76      * The offset within the buffer array of the first buffer from
77      * which bytes are to be retrieved; must be non-negative and no
78      * larger than <tt>srcs.length</tt>
79      *
80      * @param length
81      * The maximum number of buffers to be accessed; must be
82      * non-negative and no larger than
83      * <tt>srcs.length</tt>&nbsp;-&nbsp;<tt>offset</tt>
84      *
85      * @return The number of bytes written, possibly zero
86      *
87      * @throws IndexOutOfBoundsException
88      * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
89      * parameters do not hold
90      *
91      * @throws NonWritableChannelException
92      * If this channel was not opened for writing
93      *
94      * @throws ClosedChannelException
95      * If this channel is closed
96      *
97      * @throws AsynchronousCloseException
98      * If another thread closes this channel
99      * while the write operation is in progress
100      *
101      * @throws ClosedByInterruptException
102      * If another thread interrupts the current thread
103      * while the write operation is in progress, thereby
104      * closing the channel and setting the current thread's
105      * interrupt status
106      *
107      * @throws IOException
108      * If some other I/O error occurs
109      */
110     public long write(ByteBuffer JavaDoc[] srcs, int offset, int length)
111     throws IOException JavaDoc;
112
113
114     /**
115      * Writes a sequence of bytes to this channel from the given buffers.
116      *
117      * <p> An invocation of this method of the form <tt>c.write(srcs)</tt>
118      * behaves in exactly the same manner as the invocation
119      *
120      * <blockquote><pre>
121      * c.write(srcs, 0, srcs.length);</pre></blockquote>
122      *
123      * @param srcs
124      * The buffers from which bytes are to be retrieved
125      *
126      * @return The number of bytes written, possibly zero
127      *
128      * @throws NonWritableChannelException
129      * If this channel was not opened for writing
130      *
131      * @throws ClosedChannelException
132      * If this channel is closed
133      *
134      * @throws AsynchronousCloseException
135      * If another thread closes this channel
136      * while the write operation is in progress
137      *
138      * @throws ClosedByInterruptException
139      * If another thread interrupts the current thread
140      * while the write operation is in progress, thereby
141      * closing the channel and setting the current thread's
142      * interrupt status
143      *
144      * @throws IOException
145      * If some other I/O error occurs
146      */
147     public long write(ByteBuffer JavaDoc[] srcs) throws IOException JavaDoc;
148
149 }
150
Popular Tags