1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package java.nio.channels;
18
19import java.io.IOException;
20import java.nio.ByteBuffer;
21
22/**
23 * A {@code ReadableByteChannel} is a type of {@link Channel} that can read
24 * bytes.
25 * <p>
26 * Read operations are synchronous on a {@code ReadableByteChannel}, that is,
27 * if a read is already in progress on the channel then subsequent reads will
28 * block until the first read completes. It is undefined whether non-read
29 * operations will block.
30 */
31public interface ReadableByteChannel extends Channel {
32
33    /**
34     * Reads bytes from the channel into the given buffer.
35     * <p>
36     * The maximum number of bytes that will be read is the
37     * {@link java.nio.Buffer#remaining() remaining} number of bytes in the
38     * buffer when the method is invoked. The bytes will be read into the buffer
39     * starting at the buffer's current
40     * {@link java.nio.Buffer#position() position}.
41     * <p>
42     * The call may block if other threads are also attempting to read from the
43     * same channel.
44     * <p>
45     * Upon completion, the buffer's {@code position} is updated to the end of
46     * the bytes that were read. The buffer's
47     * {@link java.nio.Buffer#limit() limit} is not changed.
48     *
49     * @param buffer
50     *            the byte buffer to receive the bytes.
51     * @return the number of bytes actually read.
52     * @throws AsynchronousCloseException
53     *             if another thread closes the channel during the read.
54     * @throws ClosedByInterruptException
55     *             if another thread interrupts the calling thread while the
56     *             operation is in progress. The interrupt state of the calling
57     *             thread is set and the channel is closed.
58     * @throws ClosedChannelException
59     *             if the channel is closed.
60     * @throws IOException
61     *             another I/O error occurs, details are in the message.
62     * @throws NonReadableChannelException
63     *             if the channel was not opened for reading.
64     */
65    public int read(ByteBuffer buffer) throws IOException;
66}
67