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 17 package java.nio.channels; 18 19 import java.io.IOException; 20 import 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 */ 31 public 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 */ read(ByteBuffer buffer)65 public int read(ByteBuffer buffer) throws IOException; 66 } 67