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 */
018package org.apache.hadoop.fs;
019
020import java.io.*;
021
022import org.apache.hadoop.classification.InterfaceAudience;
023import org.apache.hadoop.classification.InterfaceStability;
024
025/**
026 * Stream that permits positional reading.
027 *
028 * Implementations are required to implement thread-safe operations; this may
029 * be supported by concurrent access to the data, or by using a synchronization
030 * mechanism to serialize access.
031 *
032 * Not all implementations meet this requirement. Those that do not cannot
033 * be used as a backing store for some applications, such as Apache HBase.
034 *
035 * Independent of whether or not they are thread safe, some implementations
036 * may make the intermediate state of the system, specifically the position
037 * obtained in {@code Seekable.getPos()} visible.
038 */
039@InterfaceAudience.Public
040@InterfaceStability.Evolving
041public interface PositionedReadable {
042  /**
043   * Read up to the specified number of bytes, from a given
044   * position within a file, and return the number of bytes read. This does not
045   * change the current offset of a file, and is thread-safe.
046   *
047   * <i>Warning: Not all filesystems satisfy the thread-safety requirement.</i>
048   * @param position position within file
049   * @param buffer destination buffer
050   * @param offset offset in the buffer
051   * @param length number of bytes to read
052   * @return actual number of bytes read; -1 means "none"
053   * @throws IOException IO problems.
054   */
055  int read(long position, byte[] buffer, int offset, int length)
056    throws IOException;
057  
058  /**
059   * Read the specified number of bytes, from a given
060   * position within a file. This does not
061   * change the current offset of a file, and is thread-safe.
062   *
063   * <i>Warning: Not all filesystems satisfy the thread-safety requirement.</i>
064   * @param position position within file
065   * @param buffer destination buffer
066   * @param offset offset in the buffer
067   * @param length number of bytes to read
068   * @throws IOException IO problems.
069   * @throws EOFException the end of the data was reached before
070   * the read operation completed
071   */
072  void readFully(long position, byte[] buffer, int offset, int length)
073    throws IOException;
074  
075  /**
076   * Read number of bytes equal to the length of the buffer, from a given
077   * position within a file. This does not
078   * change the current offset of a file, and is thread-safe.
079   *
080   * <i>Warning: Not all filesystems satisfy the thread-safety requirement.</i>
081   * @param position position within file
082   * @param buffer destination buffer
083   * @throws IOException IO problems.
084   * @throws EOFException the end of the data was reached before
085   * the read operation completed
086   */
087  void readFully(long position, byte[] buffer) throws IOException;
088}