001 /** 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 package org.apache.hadoop.hdfs; 019 020 import java.io.IOException; 021 import java.util.EnumSet; 022 023 import org.apache.hadoop.fs.ByteBufferReadable; 024 import org.apache.hadoop.fs.ReadOption; 025 import org.apache.hadoop.hdfs.client.ClientMmap; 026 import org.apache.hadoop.hdfs.client.ClientMmapManager; 027 import org.apache.hadoop.hdfs.protocol.LocatedBlock; 028 029 /** 030 * A BlockReader is responsible for reading a single block 031 * from a single datanode. 032 */ 033 public interface BlockReader extends ByteBufferReadable { 034 035 036 /* same interface as inputStream java.io.InputStream#read() 037 * used by DFSInputStream#read() 038 * This violates one rule when there is a checksum error: 039 * "Read should not modify user buffer before successful read" 040 * because it first reads the data to user buffer and then checks 041 * the checksum. 042 * Note: this must return -1 on EOF, even in the case of a 0-byte read. 043 * See HDFS-5762 for details. 044 */ 045 int read(byte[] buf, int off, int len) throws IOException; 046 047 /** 048 * Skip the given number of bytes 049 */ 050 long skip(long n) throws IOException; 051 052 /** 053 * Returns an estimate of the number of bytes that can be read 054 * (or skipped over) from this input stream without performing 055 * network I/O. 056 */ 057 int available() throws IOException; 058 059 /** 060 * Close the block reader. 061 * 062 * @throws IOException 063 */ 064 void close() throws IOException; 065 066 /** 067 * Read exactly the given amount of data, throwing an exception 068 * if EOF is reached before that amount 069 */ 070 void readFully(byte[] buf, int readOffset, int amtToRead) throws IOException; 071 072 /** 073 * Similar to {@link #readFully(byte[], int, int)} except that it will 074 * not throw an exception on EOF. However, it differs from the simple 075 * {@link #read(byte[], int, int)} call in that it is guaranteed to 076 * read the data if it is available. In other words, if this call 077 * does not throw an exception, then either the buffer has been 078 * filled or the next call will return EOF. 079 */ 080 int readAll(byte[] buf, int offset, int len) throws IOException; 081 082 /** 083 * @return true only if this is a local read. 084 */ 085 boolean isLocal(); 086 087 /** 088 * @return true only if this is a short-circuit read. 089 * All short-circuit reads are also local. 090 */ 091 boolean isShortCircuit(); 092 093 /** 094 * Get a ClientMmap object for this BlockReader. 095 * 096 * @param opts The read options to use. 097 * @return The ClientMmap object, or null if mmap is not 098 * supported. 099 */ 100 ClientMmap getClientMmap(EnumSet<ReadOption> opts, 101 ClientMmapManager mmapManager); 102 }