KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)ReadableByteChannel.java 1.16 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.
16  *
17  * <p> Only one read operation upon a readable channel may be in progress at
18  * any given time. If one thread initiates a read operation upon a channel
19  * then any other thread that attempts to initiate another read operation will
20  * block until the first operation is complete. Whether or not other kinds of
21  * I/O operations may proceed concurrently with a read operation depends upon
22  * the type of the channel. </p>
23  *
24  *
25  * @author Mark Reinhold
26  * @author JSR-51 Expert Group
27  * @version 1.16, 03/12/19
28  * @since 1.4
29  */
30
31 public interface ReadableByteChannel extends Channel JavaDoc {
32
33     /**
34      * Reads a sequence of bytes from this channel into the given buffer.
35      *
36      * <p> An attempt is made to read up to <i>r</i> bytes from the channel,
37      * where <i>r</i> is the number of bytes remaining in the buffer, that is,
38      * <tt>dst.remaining()</tt>, at the moment this method is invoked.
39      *
40      * <p> Suppose that a byte sequence of length <i>n</i> is read, where
41      * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
42      * This byte sequence will be transferred into the buffer so that the first
43      * byte in the sequence is at index <i>p</i> and the last byte is at index
44      * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>,
45      * where <i>p</i> is the buffer's position at the moment this method is
46      * invoked. Upon return the buffer's position will be equal to
47      * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
48      *
49      * <p> A read operation might not fill the buffer, and in fact it might not
50      * read any bytes at all. Whether or not it does so depends upon the
51      * nature and state of the channel. A socket channel in non-blocking mode,
52      * for example, cannot read any more bytes than are immediately available
53      * from the socket's input buffer; similarly, a file channel cannot read
54      * any more bytes than remain in the file. It is guaranteed, however, that
55      * if a channel is in blocking mode and there is at least one byte
56      * remaining in the buffer then this method will block until at least one
57      * byte is read.
58      *
59      * <p> This method may be invoked at any time. If another thread has
60      * already initiated a read operation upon this channel, however, then an
61      * invocation of this method will block until the first operation is
62      * complete. </p>
63      *
64      * @param dst
65      * The buffer into which bytes are to be transferred
66      *
67      * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
68      * channel has reached end-of-stream
69      *
70      * @throws NonReadableChannelException
71      * If this channel was not opened for reading
72      *
73      * @throws ClosedChannelException
74      * If this channel is closed
75      *
76      * @throws AsynchronousCloseException
77      * If another thread closes this channel
78      * while the read operation is in progress
79      *
80      * @throws ClosedByInterruptException
81      * If another thread interrupts the current thread
82      * while the read operation is in progress, thereby
83      * closing the channel and setting the current thread's
84      * interrupt status
85      *
86      * @throws IOException
87      * If some other I/O error occurs
88      */
89     public int read(ByteBuffer JavaDoc dst) throws IOException JavaDoc;
90
91 }
92
Popular Tags