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.hdfs;
019
020import org.apache.hadoop.classification.InterfaceAudience;
021import org.apache.hadoop.classification.InterfaceStability;
022
023import java.io.IOException;
024import java.nio.ByteBuffer;
025
026/**
027 * The public API for ReplicaAccessor objects.
028 */
029@InterfaceAudience.Public
030@InterfaceStability.Stable
031public abstract class ReplicaAccessor {
032  /**
033   * Read bytes from the replica.
034   *
035   * @param pos    The position in the replica to start reading at.
036   *                 Must not be negative.
037   * @param buf    The byte array to read into.
038   * @param off    The offset within buf to start reading into.
039   * @param len    The maximum length to read.
040   *
041   * @return       The number of bytes read.  If the read extends past the end
042   *                  of the replica, a short read count will be returned.  We
043   *                  will never return a negative number.  We will never
044   *                  return a short read count unless EOF is reached.
045   */
046  public abstract int read(long pos, byte[] buf, int off, int len)
047      throws IOException;
048
049  /**
050   * Read bytes from the replica.
051   *
052   * @param pos    The position in the replica to start reading at.
053   *                 Must not be negative.
054   * @param buf    The byte buffer to read into.  The amount to read will be
055   *                 dictated by the remaining bytes between the current
056   *                 position and the limit.  The ByteBuffer may or may not be
057   *                 direct.
058   *
059   * @return       The number of bytes read.  If the read extends past the end
060   *                 of the replica, a short read count will be returned.  We
061   *                 will never return a negative number.  We will never return
062   *                 a short read count unless EOF is reached.
063   */
064  public abstract int read(long pos, ByteBuffer buf) throws IOException;
065
066  /**
067   * Release the resources associated with the ReplicaAccessor.
068   *
069   * It is recommended that implementations never throw an IOException.  The
070   * method is declared as throwing IOException in order to remain compatible
071   * with java.io.Closeable.  If an exception is thrown, the ReplicaAccessor
072   * must still be closed when the function returns in order to prevent a
073   * resource leak.
074   */
075  public abstract void close() throws IOException;
076
077  /**
078   * Return true if bytes read via this accessor should count towards the
079   * local byte count statistics.
080   */
081  public abstract boolean isLocal();
082
083  /**
084   * Return true if bytes read via this accessor should count towards the
085   * short-circuit byte count statistics.
086   */
087  public abstract boolean isShortCircuit();
088}